{
  "markdown": "# Saleor Configurator\n\n> Commerce as Code — Define your Saleor store in YAML, sync with your instance\n\n[![npm version](https://img.shields.io/npm/v/@saleor/configurator.svg)](https://www.npmjs.com/package/@saleor/configurator)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n\nDeclarative configuration management for [Saleor](https://saleor.io) e-commerce stores.\n\n## What is Saleor Configurator?\n\nSaleor Configurator brings **infrastructure-as-code** principles to e-commerce. Instead of manually configuring your store through the dashboard, you define everything in version-controlled YAML files and sync them to your Saleor instance.\n\n**Key Benefits:**\n\n- **Version Control** — Track all store changes in Git with full history\n- **Reproducibility** — Spin up identical configurations across environments\n- **Multi-Environment** — Manage dev, staging, and production from the same codebase\n- **Review Process** — Use pull requests to review configuration changes\n- **Automation** — Integrate with CI/CD for automated deployments\n\n```\n┌─────────────┐     introspect     ┌─────────────┐\n│   Saleor    │ ─────────────────► │  config.yml │\n│  Instance   │                    │   (local)   │\n└─────────────┘                    └─────────────┘\n       ▲                                  │\n       │                                  │\n       │         deploy                   │ modify\n       └──────────────────────────────────┘\n```\n\n## Quick Start\n\n**Prerequisites:** Node.js 20+\n\n### Compatibility\n\nConfigurator releases follow the supported Saleor major and minor version. Configurator `3.23.x` targets Saleor `3.23.x`.\n\nThe supported Saleor minor is declared in `package.json#saleor.schemaVersion`. Patch versions within that Saleor minor are treated as compatible. Older Saleor minors may still work, but they are not active support targets for the latest configurator line.\n\n### Installation\n\n```bash\n# Run directly (recommended)\nnpx @saleor/configurator start\npnpm dlx @saleor/configurator start\n\n# Or install globally\nnpm install -g @saleor/configurator\npnpm add -g @saleor/configurator\n```\n\n### Getting Your API Token\n\nBefore using Saleor Configurator, you need an API token from your Saleor instance. This token allows the CLI to read and modify your store configuration.\n\n#### Step 1: Access Your Saleor Dashboard\n\nGo to your Saleor Dashboard:\n- **Saleor Cloud**: `https://your-store.saleor.cloud/dashboard/`\n- **Self-hosted**: `https://your-domain.com/dashboard/`\n\n#### Step 2: Create a New App\n\n1. Navigate to **Extensions** → **Installed** in the sidebar\n2. Click **Add Extension** → **Provide details manually**\n3. Enter a name like `Configurator` or `Configuration Manager`\n\n#### Step 3: Assign Permissions\n\nGrant the app **all permissions** needed for configuration management:\n\n| Permission Category | Required For |\n|---------------------|--------------|\n| **Products** | Product types, categories, products, variants |\n| **Channels** | Sales channels, currency settings |\n| **Shipping** | Shipping zones, methods, warehouses |\n| **Pages** | Page types (model types), pages (models) |\n| **Menus** | Navigation structures |\n| **Discounts** | Vouchers and sales (if using) |\n| **Settings** | Shop settings, tax configuration |\n\n> **Tip:** For full configuration management, select all available permissions. You can restrict permissions later for specific environments.\n\n#### Step 4: Generate the Token\n\n1. After creating the app, go to the app's detail page\n2. Find the **Tokens** section\n3. Click **Create Token**\n4. Copy the token immediately — it won't be shown again\n\nYour token will look like: `eyJhbGciOiJSUzI1NiIsInR5cCI6...` (JWT format) or a shorter alphanumeric string.\n\n#### Step 5: Store Your Credentials\n\nFor repeated use, store your credentials as environment variables:\n\n```bash\n# Add to your shell profile (~/.bashrc, ~/.zshrc, etc.)\nexport SALEOR_URL=\"https://your-store.saleor.cloud/graphql/\"\nexport SALEOR_TOKEN=\"your-token-here\"\n\n# Then use in commands\nnpx @saleor/configurator introspect --url=$SALEOR_URL --token=$SALEOR_TOKEN\n```\n\n> **Security Note:** Never commit tokens to version control. Use environment variables or a secrets manager.\n\n#### Verify Your Setup\n\nTest that your token works:\n\n```bash\nnpx @saleor/configurator introspect --url=$SALEOR_URL --token=$SALEOR_TOKEN --include shop\n```\n\nIf successful, you'll see your shop settings downloaded. If you get an authentication error, verify your token and URL (ensure the URL ends with `/graphql/`).\n\n### First-Time Setup\n\nThe easiest way to get started is with the interactive wizard:\n\n```bash\nnpx @saleor/configurator start\n```\n\n### Core Workflow\n\n```bash\n# 1. Download your current store configuration\nnpx @saleor/configurator introspect \\\n  --url https://your-store.saleor.cloud/graphql/ \\\n  --token your-app-token\n\n# 2. Modify config.yml to define your desired state\n\n# 3. Preview changes before applying\nnpx @saleor/configurator diff \\\n  --url https://your-store.saleor.cloud/graphql/ \\\n  --token your-app-token\n\n# 4. Deploy your configuration\nnpx @saleor/configurator deploy \\\n  --url https://your-store.saleor.cloud/graphql/ \\\n  --token your-app-token\n```\n\n> **Need a token?** See [Getting Your API Token](#getting-your-api-token) above for step-by-step instructions.\n\n### Quick Reference\n\n| Task | Command |\n|------|---------|\n| Download config | `npx @saleor/configurator introspect --url <URL> --token <TOKEN>` |\n| Preview changes | `npx @saleor/configurator diff --url <URL> --token <TOKEN>` |\n| Deploy changes | `npx @saleor/configurator deploy --url <URL> --token <TOKEN>` |\n| Apply recipe | `npx @saleor/configurator recipe apply <name> --url <URL> --token <TOKEN>` |\n| CI deployment | `npx @saleor/configurator deploy --url <URL> --token <TOKEN> --fail-on-delete` |\n\n## Commands\n\nAll commands support `--help` for detailed usage information.\n\n### `start` — Interactive Wizard\n\nGuided setup for exploring features and connecting to your Saleor instance.\n\n```bash\nnpx @saleor/configurator start\n```\n\n### `introspect` — Download Remote Config\n\nFetches the current configuration from your Saleor instance and saves it locally.\n\n```bash\nnpx @saleor/configurator introspect --url <URL> --token <TOKEN>\n\n# With custom output file\nnpx @saleor/configurator introspect --url <URL> --token <TOKEN> --config production.yml\n```\n\n### `diff` — Preview Changes\n\nShows what would change if you deployed, without making any modifications.\n\n```bash\nnpx @saleor/configurator diff --url <URL> --token <TOKEN>\n```\n\n### `deploy` — Apply Configuration\n\nSyncs your local configuration to the remote Saleor instance.\n\n```bash\n# Interactive mode with confirmation prompts\nnpx @saleor/configurator deploy --url <URL> --token <TOKEN>\n\n# Custom config file\nnpx @saleor/configurator deploy --url <URL> --token <TOKEN> --config production.yml\n```\n\n### `recipe` — Pre-Built Templates\n\nApply ready-to-use configuration templates for common e-commerce scenarios.\n\n```bash\n# List available recipes\nnpx @saleor/configurator recipe list\n\n# Preview a recipe's configuration\nnpx @saleor/configurator recipe show multi-region\n\n# Apply a recipe to your instance\nnpx @saleor/configurator recipe apply multi-region --url <URL> --token <TOKEN>\n\n# Export for customization\nnpx @saleor/configurator recipe export multi-region --output my-config.yml\n```\n\n## Configuration\n\nDefine your store configuration in YAML (default: `config.yml`).\n\n### Structure Overview\n\n```yaml\n# Global store settings\nshop:\n  defaultMailSenderName: \"My Store\"\n  displayGrossPrices: true\n\n# Sales channels (multi-currency, multi-region)\nchannels:\n  - name: \"United States\"\n    slug: us\n    currencyCode: USD\n    defaultCountry: US\n\n# Product catalog structure\nproductTypes:\n  - name: \"Book\"\n    isShippingRequired: true\n    productAttributes:\n      - name: \"Author\"\n        inputType: PLAIN_TEXT\n\ncategories:\n  - name: \"Fiction\"\n    slug: fiction\n    subcategories:\n      - name: \"Fantasy\"\n        slug: fantasy\n\nproducts:\n  - name: \"Sample Book\"\n    slug: sample-book\n    productType: \"Book\"\n    category: fiction\n    variants:\n      - name: \"Hardcover\"\n        sku: \"BOOK-001\"\n\n# Fulfillment\nwarehouses:\n  - name: \"Main Warehouse\"\n    slug: main-warehouse\n    address:\n      streetAddress1: \"123 Commerce St\"\n      city: \"New York\"\n      country: US\n\nshippingZones:\n  - name: \"US Zone\"\n    countries: [\"US\"]\n    warehouses: [\"main-warehouse\"]\n```\n\n### Domain Modeling\n\nSaleor's domain model consists of interconnected entity types that you can configure declaratively.\n\n#### Core Entities\n\n| Entity | Purpose | Configured Via |\n|--------|---------|----------------|\n| **Products** | Sellable items with variants, pricing, stock | `products` |\n| **Product Types** | Templates defining product structure and attributes | `productTypes` |\n| **Categories** | Hierarchical product taxonomy (one category per product) | `categories` |\n| **Collections** | Flexible product groupings for merchandising | `collections` |\n| **Models** | Custom entities extending beyond products (e.g., Brands, Ingredients) | `models` |\n| **Model Types** | Templates defining model structure | `pageTypes` |\n| **Structures** | Hierarchical navigation linking categories, collections, models, URLs | `menus` |\n\n#### Attributes\n\nAttributes are reusable typed fields assigned to products or models:\n\n| Type | Description | Example |\n|------|-------------|---------|\n| `DROPDOWN` | Single-select from predefined values | Color: Red, Blue, Green |\n| `MULTISELECT` | Multi-select from predefined values | Tags: Sale, New, Featured |\n| `PLAIN_TEXT` | Unformatted text | Material: \"100% Cotton\" |\n| `RICH_TEXT` | Formatted content blocks | Product description |\n| `NUMERIC` | Numbers with optional units | Weight: 500g |\n| `BOOLEAN` | Yes/no values | Fair trade certified |\n| `DATE` / `DATE_TIME` | Date values | Release date |\n| `FILE` | File attachments | Product manual PDF |\n| `SWATCH` | Color codes or images | Visual color picker |\n| `REFERENCE` | Links to other entities | Related products |\n\n#### Linking Entities with REFERENCE Attributes\n\nConnect products to other products, models, or variants:\n\n```yaml\nproductTypes:\n  - name: \"Perfume\"\n    productAttributes:\n      - name: \"Scent Profiles\"\n        inputType: REFERENCE\n        entityType: PAGE          # Links to Models\n      - name: \"Related Products\"\n        inputType: REFERENCE\n        entityType: PRODUCT       # Links to other Products\n```\n\n#### Custom Entities with Models\n\nExtend your domain beyond products using Models (internally called Pages):\n\n```yaml\n# Define structure with pageTypes\npageTypes:\n  - name: \"Brand\"\n    attributes:\n      - name: \"Country\"\n        inputType: DROPDOWN\n        values: [{ name: \"France\" }, { name: \"Italy\" }, { name: \"USA\" }]\n      - name: \"Founded\"\n        inputType: NUMERIC\n\n# Create instances with models\nmodels:\n  - title: \"Maison Lumière\"\n    slug: \"maison-lumiere\"\n    modelType: \"Brand\"\n    attributes:\n      country: \"France\"\n      founded: 1925\n```\n\n#### Structures (Navigation)\n\nOrganize entities hierarchically using menus:\n\n```yaml\nmenus:\n  - name: \"Main Navigation\"\n    slug: \"main-nav\"\n    items:\n      - name: \"Shop\"\n        category: \"all-products\"      # Link to Category\n      - name: \"Collections\"\n        children:\n          - name: \"Summer Sale\"\n            collection: \"summer-sale\" # Link to Collection\n      - name: \"Our Brands\"\n        page: \"maison-lumiere\"        # Link to Model\n      - name: \"Help\"\n        url: \"https://help.example.com\"  # External URL\n```\n\n**Learn more:** [Saleor Modeling](https://docs.saleor.io/developer/modeling) · [Attributes](https://docs.saleor.io/developer/attributes/overview) · [Products](https://docs.saleor.io/developer/products/overview)\n\n### Entity Identification\n\nEntities are identified by either `slug` or `name` depending on their type:\n\n| Identifier | Entity Types |\n|------------|--------------|\n| **slug** | Channels, Categories, Collections, Menus, Pages, Products, Warehouses |\n| **name** | ProductTypes, PageTypes, TaxClasses, ShippingZones, Attributes |\n\nWhen referencing entities, use the appropriate identifier:\n\n```yaml\nproducts:\n  - name: \"Sample Book\"\n    productType: \"Book\"        # Reference by name (ProductType)\n    category: \"fiction\"        # Reference by slug (Category)\n    collections: [\"featured\"]  # Reference by slug (Collection)\n```\n\n### Complete Reference\n\n- **[SCHEMA.md](SCHEMA.md)** — Full field documentation and validation rules\n- **[example.yml](example.yml)** — Comprehensive working example\n\n## Recipes\n\nRecipes are pre-built YAML configuration templates for common e-commerce scenarios. They complement the [Saleor Recipes documentation](https://docs.saleor.io/recipes/overview) by providing ready-to-deploy configurations you can apply directly or customize.\n\n### Available Recipes\n\n| Recipe | Description | Entities |\n|--------|-------------|----------|\n| **multi-region** | US, EU, UK markets with regional warehouses | Channels, Warehouses, ShippingZones |\n| **digital-products** | Product types for non-physical goods | ProductTypes |\n| **click-and-collect** | Warehouse pickup points with local collection | Warehouses, ShippingZones |\n| **custom-shipping** | Complex shipping zones and rate structures | ShippingZones |\n\n### Quick Start with Recipes\n\n```bash\n# List all recipes with descriptions\nnpx @saleor/configurator recipe list\n\n# Preview what a recipe contains\nnpx @saleor/configurator recipe show multi-region\n\n# Apply directly to your instance\nnpx @saleor/configurator recipe apply multi-region --url <URL> --token <TOKEN>\n\n# Export and customize before applying\nnpx @saleor/configurator recipe export multi-region --output my-store.yml\n# Edit my-store.yml...\nnpx @saleor/configurator deploy --url <URL> --token <TOKEN> --config my-store.yml\n```\n\n> **Note:** More recipes are planned. Check `recipe list` for the current catalog.\n\nSee [recipes/README.md](recipes/README.md) for detailed recipe documentation and customization guides.\n\n## CI/CD Integration\n\nAutomate configuration deployments with GitHub Actions or other CI systems.\n\n### GitHub Actions Example\n\n```yaml\nname: Deploy Saleor Configuration\n\non:\n  push:\n    branches: [main]\n    paths: ['config.yml']\n\njobs:\n  deploy:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v4\n\n      - uses: actions/setup-node@v4\n        with:\n          node-version: '20'\n\n      - name: Preview changes\n        run: |\n          npx @saleor/configurator diff \\\n            --url ${{ secrets.SALEOR_URL }} \\\n            --token ${{ secrets.SALEOR_TOKEN }}\n\n      - name: Deploy configuration\n        run: |\n          npx @saleor/configurator deploy \\\n            --url ${{ secrets.SALEOR_URL }} \\\n            --token ${{ secrets.SALEOR_TOKEN }} \\\n```\n\n### Key Flags for Automation\n\n| Flag | Description |\n|------|-------------|\n| `--json` | Output machine-readable JSON |\n| `--fail-on-delete` | Exit code 6 if deletions detected |\n| `--fail-on-breaking` | Exit code 7 if breaking changes detected |\n| `--quiet` | Suppress non-essential output |\n\nNon-interactive mode is auto-detected in non-TTY environments (pipes, CI, subprocesses).\n\n### Multi-Environment Pattern\n\n```bash\n# Production deployment\nnpx @saleor/configurator deploy \\\n  --url $PROD_URL --token $PROD_TOKEN \\\n  --config config.yml --fail-on-delete\n\n# Staging deployment\nnpx @saleor/configurator deploy \\\n  --url $STAGING_URL --token $STAGING_TOKEN \\\n  --config config.yml\n```\n\nSee [docs/ci-cd/README.md](docs/ci-cd/README.md) for workflow templates, exit codes, and advanced patterns.\n\n## Troubleshooting\n\n### Common Issues\n\n**Authentication Failed**\n- Verify your token in the Saleor dashboard\n- Ensure the app has all required permissions\n- Check that the URL ends with `/graphql/`\n\n**Entity Reference Errors**\n- Verify referenced entities exist (e.g., categories before products)\n- Check identifier types: use `slug` for categories, `name` for product types\n- Run `diff` to see what's missing\n\n**Validation Errors**\n- Check required fields are present\n- Validate enum values match the schema\n- See [SCHEMA.md](SCHEMA.md) for field requirements\n\n### Diagnostic Commands\n\n```bash\n# Test connectivity\nnpx @saleor/configurator introspect --url <URL> --token <TOKEN> --include shop\n\n# Preview without changes (show plan only)\nnpx @saleor/configurator deploy --url <URL> --token <TOKEN> --plan\n\n# Debug mode\nLOG_LEVEL=debug npx @saleor/configurator diff --url <URL> --token <TOKEN>\n```\n\nSee [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md) for detailed troubleshooting procedures.\n\n## AI Agent Integration\n\nSaleor Configurator provides first-class support for AI coding tools through two mechanisms:\n\n### Portable Skills (`skills/`)\n\nNine portable skills usable by any AI coding tool (Codex, Cursor, Copilot, Gemini CLI, etc.):\n\n```bash\n# Install via skills.sh\nnpx skills add saleor/configurator\n```\n\nSkills cover CLI usage, config schema, Saleor domain modeling, product design, recipes, data import, output parsing, deployment workflows, and troubleshooting.\n\n### Claude Code Plugin (`plugin/`)\n\nFull-featured Claude Code plugin with slash commands, autonomous agents, hooks, and MCP integrations:\n\n```bash\nclaude --plugin-dir ./plugin\n```\n\nSee [`AGENTS.md`](AGENTS.md) for the complete AI agent integration guide.\n\n## Contributing\n\n### Development Setup\n\n```bash\n# Clone and install\ngit clone https://github.com/saleor/configurator.git\ncd configurator\npnpm install\n\n# Run in development mode\npnpm dev start\npnpm dev introspect --url <URL> --token <TOKEN>\n\n# Build and test\npnpm build\npnpm test\n```\n\n### Quality Standards\n\n```bash\n# Before committing\npnpm check:fix && pnpm build && pnpm test\n```\n\n### Versioning\n\nThis project uses [Changesets](https://github.com/changesets/changesets) for release notes and publishing, with one repository-specific rule: configurator package major and minor versions follow the supported Saleor major and minor.\n\n```bash\n# Document your changes\npnpm changeset\n```\n\nRelease rules:\n\n- Patch fixes for the current Saleor target use a patch changeset.\n- Moving support to the next Saleor minor updates `package.json#saleor.schemaVersion` and uses a minor changeset.\n- The first Saleor-bound release from `1.x` to `3.23.0` requires manually editing the generated release PR version.\n- Releases are published from `main` by the GitHub Actions release workflow.\n\nFor example, configurator `3.23.x` targets Saleor `3.23.x`; configurator `3.24.0` starts the Saleor `3.24.x` line.\n\nSee [docs/DEVELOPMENT_WORKFLOWS.md](docs/DEVELOPMENT_WORKFLOWS.md) for detailed contribution guidelines.\n\n## Documentation\n\n| Document | Description |\n|----------|-------------|\n| [SCHEMA.md](SCHEMA.md) | Complete configuration field reference |\n| [example.yml](example.yml) | Working example with all entity types |\n| [recipes/README.md](recipes/README.md) | Pre-built recipe templates |\n| [docs/COMMANDS.md](docs/COMMANDS.md) | Complete CLI reference |\n| [docs/ci-cd/README.md](docs/ci-cd/README.md) | CI/CD integration guide |\n| [docs/ENTITY_REFERENCE.md](docs/ENTITY_REFERENCE.md) | Entity types and identification |\n| [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md) | Problem diagnosis and fixes |\n| [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | System design and internals |\n| [docs/DEVELOPMENT_WORKFLOWS.md](docs/DEVELOPMENT_WORKFLOWS.md) | Contributor guide |\n| [docs/CODE_QUALITY.md](docs/CODE_QUALITY.md) | Coding standards |\n| [docs/TESTING_PROTOCOLS.md](docs/TESTING_PROTOCOLS.md) | Testing guidelines |\n\n## License\n\nMIT License - see [LICENSE](LICENSE) for details.\n",
  "bytes": 19574,
  "sha": "9f8a22bc3204e9360b34595b12f2e6bdb041f994715b28816a7fc3866596a2bd",
  "repo_slug": "saleor/configurator",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/skl_saleor_configurator_claude_skills_analyz_50475865/readme"
}