configurator-cli

What this skill does

# 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).

```bash
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`.

```bash
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.

```bash
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.

```bash
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:

```bash
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:

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

Parse with `jq`:
```bash
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

```bash
# 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

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

### Entity-Scoped Debugging

```bash
# 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

```bash
# 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):
```bash
# Save current remote state as backup
pnpm dlx @saleor/configurator introspect --config=backup-config.yml
```

**After a bad deploy**:
```bash
# Restore from backup
pnpm dlx @saleor/configurator deploy --config=backup-config.yml
```

**Using git**:
```bash
# 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):
```bash
# 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