npm package: @specmarket/cli
Description: SpecMarket CLI - discover, validate, execute, and publish AI specs
Latest version: 0.0.6

# @specmarket/cli

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

## Install

```bash
npm install -g @specmarket/cli
```

Requires Node.js >= 20.

## Quick Start

```bash
# 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.**

```bash
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

```bash
# 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