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

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

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

diff vs deploy --plan

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](references/commands.md)
• For all flags and options, see [references/flags.md](references/flags.md)
• For error code details, see [references/error-codes.md](references/error-codes.md)
• For CI/CD setup, see [references/ci-cd.md](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