AIditorEcosystemDocumentationDesign Log
GitHubGet Started
CLI Commands Reference
← Documentation
Designer28
Developer13
Plugin Developer20
DevOps6
Contracts5

CLI Commands Reference

CLI Commands Reference

DeveloperDeveloper Agent Kit — documentation written for AI agents, readable by humans.

jay-stack-cli setup

Run plugin setup. Plugins can create configuration files, prompt for credentials, and validate their prerequisites.

# Run setup for all installed plugins (interactive — may prompt for input)
jay-stack-cli setup

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

# Re-run setup (e.g., after config change)
jay-stack-cli setup wix-data --force

# Non-interactive mode (CI/scripts — creates config templates without prompting)
jay-stack-cli setup --no-interactive

Setup is interactive by default — plugins can prompt for API keys, credentials, and configuration choices. In non-interactive mode (--no-interactive), prompts are skipped and plugins create config templates with placeholders instead.

Plugins declare their setup handler in plugin.yaml. Setup does three things:

  1. Config templates: Creates config/<plugin>.yaml with credentials (interactive) or placeholders (non-interactive)
  2. Credential prompts: Asks for API keys and configuration when running interactively
  3. Service validation: Attempts to initialize services, reports success or failure

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

Run this after installing new plugins, before jay-stack-cli agent-kit.

jay-stack agent-kit

Materialize contracts, generate discovery indexes, and produce plugin reference data. Run this after setup.

# Default: writes to agent-kit/
jay-stack agent-kit

# Custom output directory for contracts
jay-stack agent-kit --output my-output/

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

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

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

# Skip reference data generation
jay-stack agent-kit --no-references

Outputs:

  • plugins-index.yaml
  • materialized-contracts/<plugin>/*.jay-contract (dynamic contracts)
  • references/<plugin>/ — plugin reference data (product catalogs, collection schemas, etc.)
  • Documentation files (INSTRUCTIONS.md and reference docs)

jay-stack validate

Validate all .jay-html and .jay-contract files.

# Validate entire project
jay-stack validate

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

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

# JSON output
jay-stack validate --json

Example output:

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

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.

Plugins can provide custom validators that run as part of jay-stack validate. Plugin findings include a suggestion field with fix instructions. See the plugin validation.md guide.

Always run validate after creating or editing jay-html and contract files.

jay-stack params

Discover load param values for SSG route generation.

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

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

# Verbose
jay-stack params wix-stores/product-page -v

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

Example output:

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

✅ Found 3 param combination(s)

Use this to discover what param values exist for dynamic routes like [slug]. Only works on contracts whose component has loadParams.

jay-stack action

Run a plugin action from the CLI. Use to discover data for populating pages.

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

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

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

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

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

Action names are listed in plugins-index.yaml under each plugin's actions: array. Each action entry includes a description and a path to the .jay-action file. Read the .jay-action file to see the full input/output schemas before calling an action.

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
}

If not found, lists available actions:

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

Production Commands

For jay-stack build, jay-stack serve, and jay-stack rebuild, see the DevOps guides.

jay-stack dev

Start the development server.

# Normal dev mode
jay-stack dev

# Test mode (enables health/shutdown endpoints)
jay-stack dev --test-mode

# Auto-timeout (implies test mode)
jay-stack dev --timeout 60

Test mode endpoints

Endpoint Method Response
/_jay/health GET {"status":"ready","port":3300,"editorPort":3301,"uptime":5.2}
/_jay/shutdown POST {"status":"shutting_down"}

Wait for server ready

Poll the health endpoint:

# Bash
for i in {1..30}; do
  curl -s http://localhost:3300/_jay/health | grep -q "ready" && break
  sleep 1
done
// TypeScript
async function waitForServer(timeout = 30000): Promise<string> {
  const start = Date.now();
  while (Date.now() - start < timeout) {
    try {
      const res = await fetch('http://localhost:3300/_jay/health');
      if (res.ok) {
        const { port } = await res.json();
        return `http://localhost:${port}`;
      }
    } catch {
      /* not ready */
    }
    await new Promise((r) => setTimeout(r, 500));
  }
  throw new Error('Server not ready');
}

Shutdown

curl -X POST http://localhost:3300/_jay/shutdown

About this document

This page is part of the Jay Stack Agent Kit — documentation generated from the framework source and written primarily for AI agents. The language and structure are optimized for machine consumption — expect precise, specification-style prose rather than narrative documentation. Learn more about the Agent Kit →