@specmarket/cli

Command-line tool for discovering, validating, executing, and publishing AI specs on the SpecMarket platform.

Install

npm install -g @specmarket/cli

Requires Node.js >= 20.

Quick Start

# Create a new spec
specmarket init

# Validate it
specmarket validate ./my-spec

# Run it locally (executes the Ralph Loop)
specmarket run ./my-spec

# Or run a spec from the registry
specmarket run @user/docusign-replacement

Commands

Spec Lifecycle

| Command | Description | |---------|-------------| | specmarket init | Interactive scaffold — creates spec directory with spec.yaml, PROMPT.md, SPEC.md, SUCCESS_CRITERIA.md, and stdlib/ | | specmarket validate <path> | Validates spec structure, schema, infrastructure block, and cross-references | | specmarket run <path-or-id> | Executes a Ralph Loop against a local spec or registry spec |

Registry

| Command | Description | |---------|-------------| | specmarket search <query> | Search the registry with filters (no auth required) | | specmarket info <spec-id> | View detailed spec info — metrics, versions, forks, infrastructure | | specmarket publish <path> | Validate and publish a spec to the registry | | specmarket fork <spec-id> [path] | Fork a published spec locally, preserving lineage |

Auth

| Command | Description | |---------|-------------| | specmarket login | Browser-based device code auth via Clerk (--token for CI) | | specmarket logout | Clear stored credentials | | specmarket whoami | Display current auth status |

Reporting & Config

| Command | Description | |---------|-------------| | specmarket report <run-id> | Display a run report from local storage or the platform | | specmarket config get\|set\|list | Manage CLI config (telemetry, default model, etc.) | | specmarket config delete-telemetry | Delete all locally stored telemetry data |

specmarket run Flags

--max-loops <n>       Override max loop count (default: 50)
--max-budget <usd>    Override max spend (default: 2x spec estimate)
--no-telemetry        Disable telemetry for this run
--model <model>       Override the model specified in spec.yaml
--dry-run             Validate and preview — don't execute
--resume <run-id>     Resume a previous incomplete run
--output <path>       Custom output directory

specmarket search Filters

--tag <tag>               Filter by tag (repeatable)
--primary-stack <stack>   Filter by stack (nextjs-typescript, python-fastapi, etc.)
--replaces-saas <name>    Filter by SaaS replacement target
--min-success-rate <n>    Minimum success rate percentage
--max-cost <usd>          Maximum estimated cost
--max-monthly-cost <usd>  Maximum monthly infrastructure cost
--service-category <cat>  Filter by infra service category (repeatable)
--free-tier-only          Only specs deployable on free tiers

How the Ralph Loop Works

1. Validates the spec (specmarket validate internally)
2. Creates a sandboxed working directory under ~/.specmarket/runs/<run-id>/
3. Copies spec files into the sandbox
4. Loops: feeds PROMPT.md to claude --print, captures tokens/duration/diffs per iteration
5. Terminates on: success (all criteria met), stall (3 loops with no meaningful diff), failure (10 loops stuck on same test), or budget exceeded
6. Generates run-report.json with full metadata

Telemetry

Opt-in only. When authenticated and opted in, run metadata (tokens, cost, pass/fail, loop count) is submitted to the platform. No source code is ever transmitted.

specmarket config set telemetry true   # opt in
specmarket config set telemetry false  # opt out
specmarket config delete-telemetry     # delete stored data

Exit Codes

| Code | Meaning | |------|---------| | 0 | Success | | 1 | Validation error | | 2 | Runtime error | | 3 | Budget exceeded | | 4 | Network error | | 5 | Auth error |

Config & Credentials

• Config: ~/.specmarket/config.json
• Credentials: ~/.specmarket/credentials.json
• Run data: ~/.specmarket/runs/

Development

# From monorepo root
pnpm install

# Build
pnpm --filter @specmarket/cli build

# Run tests
pnpm --filter @specmarket/cli test

# Watch mode
pnpm --filter @specmarket/cli dev

License

MIT