configurator-cli

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