cli

Imported from shopwareLabs/shopware-catalog-generator (src/cli/AGENTS.md). Install upstream with npx skills add shopwareLabs/shopware-catalog-generator --skill cli. Copyright stays with the author.

CLI Reference

Internal documentation for AI agents working on the CLI module, and complete reference for all commands.

Module Overview

The CLI is a thin router in main.ts that parses args and delegates to focused modules:

• blueprint.ts — blueprint create, blueprint hydrate, blueprint fix, blueprint inspire
• generate.ts — generate, process
• image-fix.ts — image fix
• shared.ts — CLIError, validation helpers, executePostProcessors

Important: All application logic lives in src/services/, not in the CLI modules. CLI handlers are thin wrappers that call service functions and print their string[] output. This keeps the CLI and MCP tools in sync — both call the same service functions.

Separate CLI entry points (not routed through main.ts):

• cache-cli.ts — cache:list, cache:clear, cache:trash, cache:restore, cache:empty-trash
• cleanup-cli.ts — cleanup, cleanup:media, cleanup:props
• server.ts — HTTP server mode

Command Reference

Generate

Full pipeline: create blueprint, hydrate with AI, upload to Shopware.

bun run generate --name=music --description="Musical instruments and accessories"

Process

Run post-processors on an existing SalesChannel (already uploaded to Shopware).

bun run process --name=music --only=images,manufacturers,customers

Blueprint Create

Phase 1: Generate blueprint structure without AI calls (instant).

bun run blueprint create --name=music --description="Musical instruments and accessories"

Output: generated/sales-channels/{name}/blueprint.json

Blueprint Hydrate

Phase 2: Fill blueprint with AI-generated content (names, descriptions, properties, images).

bun run blueprint hydrate --name=music

Hydration Modes

If a hydrated blueprint already exists, --only or --rehydrate is required to prevent accidental name changes.

Output: generated/sales-channels/{name}/hydrated-blueprint.json

Blueprint Fix

Fix incomplete hydration by replacing placeholder names in a hydrated blueprint.

bun run blueprint fix --name=music

Blueprint Inspire

Crawl a real store URL to extract categories, example products, brand colors, and description. Saves inspiration.json so blueprint hydrate can use it to orient AI generation.

bun run blueprint inspire --name=music --url=https://some-music-shop.com

Output: generated/sales-channels/{name}/inspiration.json

No AI calls are made. Uses cheerio (MIT) + sharp to parse static HTML and images:

1. JSON-LD BreadcrumbList → category names; fallback: <nav> link text
2. JSON-LD Product / ItemList → example products (follows up to 2 category pages)
3. Brand images → dominant color extraction:
   • SVG icons: fill/stroke attributes parsed directly (e.g. IKEA blue + yellow)
   • Raster icons (apple-touch-icon, PNG favicons): pixel analysis via sharp
   • Fallback: theme-color meta / CSS --primary-color vars (near-white filtered out)
4. og:description or JSON-LD Organization.description → brand description

Image Fix

Regenerate images for a specific product, category, or CMS page.

bun run image fix --name=music --target="Acoustic Guitar" --type=product
bun run image fix --name=music --type=theme --target=logo
bun run image fix --name=music --type=theme              # regenerates all theme media

For --type=theme, --target is optional (defaults to "all"). Valid targets: logo, favicon, share, or all.

Cleanup

Remove generated data from Shopware. Local cache is preserved.

bun run cleanup -- --salesChannel="music"
bun run cleanup -- --salesChannel="music" --full --delete

Global Cleanup (no SalesChannel required)

bun run cleanup -- --unused-props        # Delete property groups with no used options
bun run cleanup -- --unused-options      # Delete individual unused property options
bun run cleanup -- --orphaned-media      # Delete media not linked to any product

Shortcut Scripts

bun run cleanup:media     # Same as --orphaned-media
bun run cleanup:props     # Same as --unused-props

Cache Management

Manage local cached files in generated/. Does not affect Shopware.

bun run cache:list                    # Show cached SalesChannels with stats
bun run cache:clear                   # Move all cached data to trash
bun run cache:clear -- music          # Move specific SalesChannel to trash
bun run cache:trash                   # List trash contents
bun run cache:restore -- <item>       # Restore specific item from trash
bun run cache:restore -- --all        # Restore all items from trash
bun run cache:empty-trash             # Permanently delete trash (irreversible)

Server Mode

Run as an HTTP service with background processing.

bun run server

Generate Request

Minimal request — name and description are derived from the inspiration URL:

curl -X POST http://localhost:3000/generate \
  -H "Content-Type: application/json" \
  -d '{
    "envPath": "http://localhost:8000",
    "shopwareUser": "admin",
    "shopwarePassword": "shopware",
    "inspirationUrl": "https://some-music-shop.com"
  }'

Full request with explicit fields:

curl -X POST http://localhost:3000/generate \
  -H "Content-Type: application/json" \
  -d '{
    "envPath": "http://localhost:8000",
    "salesChannel": "music",
    "description": "Musical instruments and accessories",
    "shopwareUser": "admin",
    "shopwarePassword": "shopware"
  }'

Poll Status

curl http://localhost:3000/status/proc_xxx
# Returns: { "status": "running", "progress": {...}, "logs": [...] }

Adding a New CLI Command

1. Implement the logic in src/services/<category>-service.ts (returns string[] for output)
2. Create a thin CLI handler in src/cli/<category>.ts that calls the service and prints lines
3. Add routing in main.ts switch statement
4. Add to showHelp() output
5. Add a thin MCP tool wrapper in src/mcp/tools/<category>.ts that calls the same service and joins lines
6. Add package.json script alias if appropriate
7. Update this reference and src/mcp/AGENTS.md