Configurator CLI

The Saleor Configurator CLI is a declarative "commerce as code" tool that syncs YAML configuration files with Saleor e-commerce instances.

Core Commands

introspect

Fetches the current configuration from a Saleor instance and writes it to config.yml.

npx configurator introspect --url=$SALEOR_API_URL --token=$SALEOR_TOKEN

Use cases:

• Initial setup: Pull existing store configuration
• Backup: Snapshot current state before changes
• Recovery: Restore from known-good state

deploy

Pushes local config.yml changes to a Saleor instance.

npx configurator deploy --url=$SALEOR_API_URL --token=$SALEOR_TOKEN

Important flags:

• --dry-run: Preview changes without applying
• --fail-on-delete: Abort if any deletions would occur
• --include <types>: Only deploy specific entity types
• --exclude <types>: Skip specific entity types
• --skip-media: Skip media file uploads

Safety notes:

• Always run diff before deploy to preview changes
• Use --fail-on-delete in CI/CD pipelines
• Back up with introspect before major changes

diff

Compares local config.yml with remote Saleor instance.

npx configurator diff --url=$SALEOR_API_URL --token=$SALEOR_TOKEN

Output shows:

• + CREATE: New entities to be created
• ~ UPDATE: Entities with modifications
• - DELETE: Entities that will be removed

start

Interactive setup wizard for new configurations.

npx configurator start

Common Flags

Environment Variables

Instead of passing flags, set environment variables:

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

# Then run without flags:
npx configurator deploy

Or use a .env file in your project root.

Exit Codes

Development Mode

When developing the Configurator itself:

# Run from source
pnpm dev introspect --url=$URL --token=$TOKEN
pnpm dev deploy --url=$URL --token=$TOKEN
pnpm dev diff --url=$URL --token=$TOKEN

Common Workflows

Initial Store Setup

# 1. Create config from existing store
npx configurator introspect --url=$URL --token=$TOKEN

# 2. Edit config.yml to make changes

# 3. Preview changes
npx configurator diff --url=$URL --token=$TOKEN

# 4. Deploy changes
npx configurator deploy --url=$URL --token=$TOKEN

Safe CI/CD Deployment

# Fail if any entities would be deleted
npx configurator deploy \
  --url=$URL \
  --token=$TOKEN \
  --fail-on-delete

Selective Deployment

# Deploy only channels and products
npx configurator deploy \
  --url=$URL \
  --token=$TOKEN \
  --include channels,products

# Deploy everything except products
npx configurator deploy \
  --url=$URL \
  --token=$TOKEN \
  --exclude products

See Also

• For complete command reference, see reference/commands.md
• For all flags and options, see reference/flags.md
• For error code details, see reference/error-codes.md