jay-cli-commands

name	jay-cli-commands
description	Use jay-stack CLI commands for setup, discovery and validation. Covers jay-stack setup (plugin config and references), jay-stack params (discover URL param values for SSG), jay-stack action (run plugin actions), and jay-stack validate (check jay-html and contract files). Use when discovering data, validating files, or running plugin actions.

Jay-Stack CLI Commands

jay-stack setup

Run plugin setup: create config templates and validate credentials.

# Run setup for all plugins
yarn jay-stack setup

# Run setup for a specific plugin
yarn jay-stack setup wix-stores

# Force re-run (overwrite config templates)
yarn jay-stack setup --force

# Verbose output
yarn jay-stack setup -v

What it does:

1. Config templates — If no config file exists for a plugin, creates one with placeholder values (e.g., config/.wix.yaml with API key placeholders)
2. Credential validation — Attempts to initialize plugin services, reports success or failure

Reference data (product catalogs, collection schemas) is generated by jay-stack agent-kit, not by setup.

Example output:

🔧 Setting up plugins...

📦 wix-server-client
   ✅ Services verified
   Wix client connected (site: 0b177404...)

📦 wix-data
   ✅ Services verified
   4 collections found (2 visible)

📦 wix-stores
   ✅ Services verified
   Wix Stores service verified

Setup complete: 3 configured

When to use: After installing new plugins, before jay-stack agent-kit. Run again after changing credentials.

---

jay-stack validate

Validate all .jay-html and .jay-contract files in the project.

# Validate entire project
yarn jay-stack validate

# Validate a specific path
yarn jay-stack validate src/pages/products/

# Verbose output (per-file status)
yarn jay-stack validate -v

# JSON output (for parsing)
yarn jay-stack validate --json

Output on success:

✅ Jay Stack validation successful!
Scanned 5 .jay-html files, 3 .jay-contract files
No errors found.

Output on failure:

❌ Jay Stack validation failed

Errors:
  ❌ src/pages/products/page.jay-html
     Unknown ref "nonExistentRef" - not found in contract

1 error(s) found, 7 file(s) valid.

JSON output (with --json):

{
  "valid": false,
  "jayHtmlFilesScanned": 5,
  "contractFilesScanned": 3,
  "errors": [
    {
      "file": "src/pages/products/page.jay-html",
      "message": "Unknown ref \"nonExistentRef\" - not found in contract"
    }
  ]
}

Always run validate after creating or editing jay-html and contract files to catch errors early.

---

jay-stack params

Discover load param values for a contract. Used for SSG route discovery — tells you which dynamic route parameter combinations exist.

# Discover all slug values for product pages
yarn jay-stack params wix-stores/product-page

# YAML output
yarn jay-stack params wix-stores/product-page --yaml

# Verbose (shows resolution steps)
yarn jay-stack params wix-stores/product-page -v

Format: <plugin-name>/<contract-name>

Example output (JSON, default):

[
  { "slug": "ceramic-flower-vase" },
  { "slug": "blue-running-shoes" },
  { "slug": "organic-cotton-tshirt" }
]

✅ Found 3 param combination(s)

When to use:

• Before generating pages for dynamic routes like [slug]
• To discover what param values are valid
• Only works on contracts whose component has loadParams (uses withLoadParams())

How it works: Starts a Vite server, loads the plugin component, runs its loadParams async generator, collects all yielded param batches, outputs them.

---

jay-stack action

Run a plugin action from the CLI. Used to discover data (e.g., product lists, categories) that helps you populate pages or choose prop values.

# Run with default input
yarn jay-stack action wix-stores/searchProducts

# Run with input
yarn jay-stack action wix-stores/searchProducts --input '{"query": "shoes", "limit": 5}'

# YAML output
yarn jay-stack action wix-stores/getCategories --yaml

# Verbose
yarn jay-stack action wix-stores/getProductBySlug --input '{"slug": "blue-shirt"}' -v

Format: <plugin-name>/<action-name>

Example output:

{
  "items": [
    { "_id": "prod-1", "name": "Blue Shirt", "slug": "blue-shirt", "price": 29.99 },
    { "_id": "prod-2", "name": "Red Hat", "slug": "red-hat", "price": 19.99 }
  ],
  "totalCount": 2
}

When to use:

• To discover valid prop values (e.g., product IDs for <jay:product-card productId="...">)
• To understand what data a plugin provides
• To explore available actions and their response shapes

Action names are listed in the plugin's plugin.yaml under actions:. The CLI matches by:

1. Exact action name
2. Dotted suffix (e.g., searchProducts matches wix-stores.searchProducts)
3. Full reference (wix-stores/searchProducts)

If an action is not found, the CLI lists all available actions:

❌ Action "badName" not found.
   Available actions: searchProducts, getProductBySlug, getCategories

---

jay-stack agent-kit

Materialize contracts and generate discovery indexes. Run this first before reading contracts.

# Default: writes to agent-kit/materialized-contracts/
yarn jay-stack agent-kit

# Custom output directory
yarn jay-stack agent-kit --output my-output/

# List contracts without writing
yarn jay-stack agent-kit --list

# Filter to specific plugin
yarn jay-stack agent-kit --plugin wix-stores

# Force re-materialization
yarn jay-stack agent-kit --force

Outputs to agent-kit/materialized-contracts/:

• contracts-index.yaml — index of all contracts
• plugins-index.yaml — index of all plugins and their contracts
• <plugin>/*.jay-contract — materialized dynamic contracts

Also creates agent-kit/INSTRUCTIONS.md if it doesn't exist.

See the jay-contracts-and-plugins skill for how to read the generated files.