CLI Command Reference

The SpecMarket CLI (specmarket) is your primary interface for discovering, validating, running, and publishing specs. 12 commands cover three workflows: local development, registry interaction, and account management.

Install:

npm install -g @specmarket/cli

Verify:

specmarket --version
# 0.0.1

Authentication

login

Authenticate with the SpecMarket registry.

specmarket login
specmarket login --token <jwt>

Options:

Two modes:

• Interactive (default): Opens your browser to Clerk’s OAuth flow, polls for the token, and stores it locally.
• Token mode: Accepts a JWT directly — useful in CI/CD pipelines where a browser isn’t available.

Credentials are stored at ~/.specmarket/credentials.json with 0600 permissions. Tokens expire after 30 days.

logout

Clear stored credentials.

specmarket logout

Removes ~/.specmarket/credentials.json and confirms which account was logged out.

whoami

Show the currently authenticated user.

specmarket whoami

Displays your username, display name, role, total specs published, reputation score, and token expiry (days remaining). Falls back to cached credential info if the registry is unreachable.

Spec Lifecycle

init

Scaffold a new spec directory with all required template files.

specmarket init
specmarket init --name my-spec --path ./specs/my-spec

Options:

Creates a complete spec scaffold:

my-spec/
├── spec.yaml              # Configuration and metadata
├── PROMPT.md              # AI prompt for execution
├── SPEC.md                # Full specification document
├── SUCCESS_CRITERIA.md    # Pass/fail criteria (checkboxes)
├── stdlib/
│   └── STACK.md           # Technology stack requirements
└── fix_plan.md            # Implementation tracking

Prompts interactively for: spec name (lowercase, hyphens only), display name, SaaS product it replaces (optional), output type, and primary stack.

validate

Check a spec directory for completeness and schema compliance.

specmarket validate <path>

Checks (errors — must pass):

• spec.yaml parses and conforms to the Zod schema
• Required files exist and are non-empty: PROMPT.md, SPEC.md, SUCCESS_CRITERIA.md
• stdlib/STACK.md exists and is non-empty
• SUCCESS_CRITERIA.md has at least one criterion (- [ ] text)
• Infrastructure block validates (if present): default_provider matches a defined provider

Checks (warnings — informational):

• Web-app/api-service specs with no infrastructure services
• Missing infrastructure.setup_time_minutes
• Unreasonable estimates: tokens below 1,000 or above 10,000,000, cost below $0.01, time below 1 minute

specmarket validate ./my-spec
# ✓ spec.yaml valid
# ✓ PROMPT.md exists (2,340 bytes)
# ✓ SPEC.md exists (8,120 bytes)
# ✓ SUCCESS_CRITERIA.md has 12 criteria
# ⚠ No infrastructure services defined (web-app specs usually need at least a database)
# Result: VALID (1 warning)

Exit codes: 0 = valid, 1 = validation error, 2 = runtime error.

run

Execute a spec locally using the Ralph Loop.

specmarket run <path-or-id> [options]

Arguments:

The first argument is either a local path (./my-spec, .) or a registry identifier (@user/spec-name, @user/spec-name@1.2.0). Registry specs are downloaded automatically before execution.

Options:

What happens during a run:

1. Spec is resolved (downloaded from registry if needed)
2. Validation runs (exits with code 1 on failure)
3. Security sandboxing warning is printed
4. If authenticated and telemetry is enabled, you’re prompted once (first time only)
5. Ralph Loop executes with a spinner showing iteration progress
6. Telemetry is submitted (if opted in)
7. Run summary prints: status, loop count, tokens used, cost, time, success criteria results

Stall detection: If 3 consecutive loops produce no git diff, the run is marked as stalled. If 10 consecutive loops fail the same test, the run is marked as failed.

Rate limit: 10 telemetry submissions per hour (authenticated users).

# Run a local spec
specmarket run ./my-spec
 
# Run from registry
specmarket run @alice/notion-clone
 
# Custom constraints
specmarket run ./my-spec --max-loops 100 --max-budget 10 --model claude-opus-4-5
 
# Preview without executing
specmarket run @alice/my-spec --dry-run
 
# Resume a stalled run
specmarket run @alice/my-spec --resume abc123

Exit codes: 0 = success, 1 = validation error, 2 = runtime error, 3 = budget exceeded, 4 = network error, 5 = auth error.

publish

Publish a spec to the SpecMarket registry.

specmarket publish <path>

Requires authentication. Run specmarket login first.

Publishing:

1. Validates the spec (exits on failure)
2. Creates a zip archive (excludes node_modules, dist, .git)
3. Uploads to Convex file storage
4. Creates or updates the registry entry with all metadata

On success, prints the spec ID and version, and suggests specmarket run @username/spec-name to test it live.

Rate limit: 5 publishes per day.

specmarket publish ./my-spec
# ✓ Validated
# ✓ Archived (42 KB)
# ✓ Published @jaiden/my-spec v1.0.0
# Run it: specmarket run @jaiden/my-spec

fork

Fork a published spec into your namespace.

specmarket fork <spec-id> [path]

Requires authentication.

Downloads a published spec, extracts it locally, and updates spec.yaml with fork metadata (forked_from_id, forked_from_version, version reset to 1.0.0). The original spec’s forkCount is incremented.

specmarket fork @alice/notion-clone
specmarket fork @alice/notion-clone ./my-notion-fork

Registry

search

Search the SpecMarket registry.

specmarket search <query> [options]

Options:

Results display in a table:

┌─────────────────────┬────────────────────────┬──────────┬─────────┬──────┬────────┐
│ Name                │ Description            │ Replaces │ Success │ Cost │ Rating │
├─────────────────────┼────────────────────────┼──────────┼─────────┼──────┼────────┤
│ @alice/esign-basic  │ Simple e-signature...  │ DocuSign │ 94%     │ $8   │ ★★★★☆  │
│ @bob/form-builder   │ Drag-and-drop form...  │ Typeform │ 87%     │ $12  │ ★★★★☆  │
└─────────────────────┴────────────────────────┴──────────┴─────────┴──────┴────────┘

Rate limit: 100 requests per minute per IP (enforced server-side via /api/search).

# Basic search
specmarket search "notion clone"
 
# Filter by type and limit
specmarket search "database" --output-type api-service --limit 50
 
# Filter by tag
specmarket search "auth" --tag security --tag authentication
 
# Find cheap alternatives to a specific SaaS
specmarket search "forms" --replaces-saas typeform --max-cost 15
 
# Only show high-success specs on free infrastructure
specmarket search "dashboard" --min-success-rate 80 --free-tier-only
 
# Filter by stack
specmarket search "api" --primary-stack python-fastapi --max-monthly-cost 10

info

Show detailed information about a spec.

specmarket info <spec-id>

Displays everything about a spec: metadata, infrastructure summary (monthly cost, services, providers), community metrics (total runs, success rate, average cost, rating, fork count), creator profile, version history (last 5), and run statistics (most used model, cost distribution).

specmarket info @alice/notion-clone

report

Display a run report.

specmarket report <run-id>

Looks up the run locally first (~/.specmarket/runs/<run-id>/run-report.json), then falls back to the platform (requires auth). Shows status, spec details, model, loop count, tokens, cost, time, and success criteria results.

specmarket report abc123

Configuration

config

Manage CLI settings stored at ~/.specmarket/config.json.

specmarket config set <key> <value>
specmarket config get <key>
specmarket config list
specmarket config delete-telemetry

Configurable keys:

delete-telemetry permanently removes all your run data from the platform. Requires authentication and confirmation. Does not affect local run artifacts.

specmarket config set telemetry true
specmarket config get default-model
specmarket config list
specmarket config delete-telemetry

Exit Codes

Every command exits with a code indicating what happened:

Environment Variables

Debug namespaces: specmarket:cli, specmarket:convex, specmarket:runner, specmarket:auth, specmarket:telemetry.

Related

• Getting Started — Install, find, and run your first spec
• Spec Format Reference — Complete spec.yaml schema
• Publishing Your First Spec — Creator onboarding guide
• Security & Trust — How specs are scanned and sandboxed