configurator-cli

name	configurator-cli
version	3.0.0
description	CLI commands for deploying, diffing, and introspecting Saleor stores. Use this skill whenever running ANY configurator CLI command or debugging CLI output. Covers deploy, introspect, diff, validate, --plan, CI/CD setup, and CLI flags.
allowed-tools	Bash, Read, Grep
license	MIT
compatibility	Claude Code or Claude.ai. Requires @saleor/configurator CLI installed.

Configurator CLI

Overview

The Saleor Configurator CLI syncs your YAML configuration with a live Saleor instance. You define your store in config.yml, then use CLI commands to preview and apply changes.

In non-TTY mode (pipes, CI, subprocesses), all commands automatically output a JSON envelope. Use --json to force JSON in a terminal, or --text to force human-readable in non-TTY.

When to Use

• "How do I deploy my config?"
• "How do I pull the current store configuration?"
• "How do I preview changes before deploying?"
• "What flags does deploy support?"
• "How do I set up CI/CD for my store?"
• "What do the exit codes mean?"
• "How do I validate my config without network?"
• When NOT modeling products or writing YAML -- use product-modeling or configurator-schema instead

Core Commands

validate

Validates config.yml against the schema locally (no network required).

pnpm dlx @saleor/configurator validate
pnpm dlx @saleor/configurator validate --config custom-config.yml
pnpm dlx @saleor/configurator validate --json

introspect

Pulls the current configuration from a Saleor instance into config.yml.

pnpm dlx @saleor/configurator introspect --url=$SALEOR_URL --token=$SALEOR_TOKEN

Use cases: initial setup, backup before changes, restore from known-good state.

deploy

Pushes local config.yml changes to a Saleor instance.

pnpm dlx @saleor/configurator deploy --url=$SALEOR_URL --token=$SALEOR_TOKEN

Important flags:

• --plan -- preview changes without applying (replaces --dry-run)
• --plan --json -- machine-readable deployment plan
• --fail-on-delete -- abort if any deletions would occur (exit code 6)
• --fail-on-breaking -- abort if breaking changes detected (exit code 7)
• --include <types> -- only deploy specific entity types
• --exclude <types> -- skip specific entity types
• --report-path <file> -- custom path for deployment report (default: auto-generated in CWD)
• --skip-media -- skip media file uploads

diff

Compares local config.yml with the remote Saleor instance.

pnpm dlx @saleor/configurator diff --url=$SALEOR_URL --token=$SALEOR_TOKEN

Output markers: + CREATE (new), ~ UPDATE (modified), - DELETE (removed).

Entity scoping:

• --entity-type "Categories" -- filter to one entity type
• --entity "Categories/electronics" -- filter to one specific entity

Quick Reference

Flag	Commands	Description
--url	deploy, diff, introspect	Saleor GraphQL endpoint URL
--token	deploy, diff, introspect	Saleor API authentication token
--json	All	Force JSON envelope output
--text	All	Force human-readable output
--drift-check	introspect	Exit code 1 if remote differs from local
--include	deploy, diff, introspect	Comma-separated entity types to include
--exclude	deploy, diff, introspect	Comma-separated entity types to exclude
--fail-on-delete	deploy	Exit code 6 if deletions detected
--fail-on-breaking	deploy	Exit code 7 if breaking changes detected
--plan	deploy	Show plan without executing changes
--report-path	deploy	Custom path for deployment report
--skip-media	deploy, diff	Skip media file comparison/upload
--entity-type	diff	Filter to one entity type
--entity	diff	Filter to one specific entity (Type/name)

Environment Variables

Set credentials via .env.local (auto-loaded) or environment variables:

export SALEOR_URL="https://your-store.saleor.cloud/graphql/"
export SALEOR_TOKEN="your-api-token"

pnpm dlx @saleor/configurator deploy  # No flags needed

JSON Envelope

In non-TTY mode, all commands output:

{
  "command": "deploy",
  "version": "1.3.0",
  "exitCode": 0,
  "result": { },
  "logs": [{ "level": "info", "ts": "...", "message": "..." }],
  "errors": []
}

Parse with jq:

OUTPUT=$(pnpm dlx @saleor/configurator validate --json 2>/dev/null)
echo "$OUTPUT" | jq '.result.valid'
echo "$OUTPUT" | jq '.result.errors[]'

Exit Codes

Code	Meaning	Action
0	Success	Operation completed
1	Unexpected error	Check error message and logs
2	Authentication error	Verify URL and token
3	Network error	Check connectivity
4	Validation error	Fix config.yml syntax/schema
5	Partial failure	Some operations failed, check errors array
6	Deletion blocked	--fail-on-delete triggered
7	Breaking blocked	--fail-on-breaking triggered

Common Workflows

Optimal Agent Workflow

# 1. Validate locally first
pnpm dlx @saleor/configurator validate --json

# 2. Compare with remote
pnpm dlx @saleor/configurator diff --json

# 3. Preview deployment
pnpm dlx @saleor/configurator deploy --plan --json

# 4. Execute deployment
pnpm dlx @saleor/configurator deploy --json

Safe CI/CD Deployment

pnpm dlx @saleor/configurator deploy --fail-on-delete

Entity-Scoped Debugging

# Drill into a specific entity type
pnpm dlx @saleor/configurator diff --entity-type "Categories" --json

# Drill into a specific entity
pnpm dlx @saleor/configurator diff --entity "Categories/electronics" --json

Selective Deployment

# Deploy only channels and products
pnpm dlx @saleor/configurator deploy --include channels,products

# Deploy everything except products
pnpm dlx @saleor/configurator deploy --exclude products

Common Mistakes

Mistake	Fix
Deploying without previewing first	Always run diff or deploy --plan before deploy
Wrong URL format	URL must end with /graphql/ (e.g., https://store.saleor.cloud/graphql/)
Expired or invalid token	Regenerate your API token in Saleor Dashboard
Not using --drift-check for CI drift detection	Use introspect --drift-check to fail CI if remote config has drifted
Forgetting --fail-on-delete in CI	Prevents accidental deletions
Using SALEOR_API_URL	Correct env var is SALEOR_URL

diff vs deploy --plan

	diff	deploy --plan
Purpose	Show field-level differences between local and remote	Show what operations deploy would execute
Output	Per-field changes (old → new values)	Operation summary (creates, updates, deletes)
Scoping	--entity-type, --entity for drill-down	No entity-level scoping
Use when	Debugging what changed, reviewing individual fields	Pre-deploy safety check, CI gates

Recommended workflow: Use diff to understand changes, then deploy --plan to confirm the execution plan.

Rollback & Recovery

Configurator doesn't have a built-in rollback command, but you can recover using these patterns:

Before deploying (recommended):

# Save current remote state as backup
pnpm dlx @saleor/configurator introspect --config=backup-config.yml

After a bad deploy:

# Restore from backup
pnpm dlx @saleor/configurator deploy --config=backup-config.yml

Using git:

# Revert config.yml to last known good state
git checkout HEAD~1 -- config.yml
pnpm dlx @saleor/configurator deploy

Partial recovery (only fix specific entities):

# Deploy only the entity types that need fixing
pnpm dlx @saleor/configurator deploy --include=categories,products

See Also

• For complete command reference, see references/commands.md
• For all flags and options, see references/flags.md
• For error code details, see references/error-codes.md
• For CI/CD setup, see references/ci-cd.md

Related Skills

• configurator-schema - Config.yml structure and validation rules
• saleor-domain - Entity relationships and Saleor concepts
• agent-output-parsing - JSON envelope parsing and drill-down patterns