Getting Started

This guide takes you from zero to running your first spec in under 10 minutes. You’ll install the CLI, find a spec, run it, and get a working application in your local directory.

Prerequisites

Before you start, make sure you have:

Node.js 20 or later — Ralph Loops run on Node.js. Check your version with node --version.
pnpm — SpecMarket uses pnpm for package management. Install it with npm install -g pnpm if you don’t have it.
Claude Code — The default spec runner. Install it from claude.ai/code. Works with a Claude subscription.

Optional but recommended:

Docker — For running specs in a sandboxed environment. Not required for basic usage, but strongly recommended for specs from untrusted authors.

1. Install the CLI

pnpm add -g specmarket

Verify the installation:

specmarket --version

2. Create an Account (Optional)

You can run specs without an account, but creating one lets you:

Submit run telemetry (helps the community track spec quality)
Rate and review specs
Publish your own specs
Claim bounties

specmarket login

This opens your browser for authentication via Clerk. After signing in, the CLI stores your credentials locally.

Check your login status:

specmarket whoami

3. Find a Spec

Browse the marketplace from the CLI:

specmarket search "docusign replacement"

You’ll see a table of matching specs with:

Name — The scoped spec name (e.g., @jaiden/docusign-replacement)
Success Rate — Percentage of community runs that met all success criteria
Avg Cost — Average API token cost across all runs
Avg Time — Average build time
Replaces — What SaaS tool this spec replaces

Or browse visually at specmarket.dev/explore.

4. Check the Details

Before running a spec, review its details:

specmarket info @jaiden/docusign-replacement

This shows:

Full description
Technology stack (e.g., Next.js + TypeScript)
Infrastructure requirements (e.g., Supabase for database)
Success criteria (what the spec promises to build)
Version history
Community ratings and reviews
Honest limitations (what percentage of the SaaS it replaces)

5. Run the Spec

Create a clean directory for the output and run the spec:

mkdir my-docusign && cd my-docusign
specmarket run @jaiden/docusign-replacement

The CLI will:

Download the spec from the marketplace
Validate the spec structure
Feed PROMPT.md to your local Claude Code agent
Start the Ralph Loop (code → test → fix → repeat)
Display real-time progress in your terminal

This typically takes 15-60 minutes depending on the spec’s complexity and the model you’re using.

Choosing a Model

Some specs require specific models. The min_model field in spec.yaml tells you the minimum required model. You can use a more capable model for better results:

specmarket run @jaiden/docusign-replacement --model claude-sonnet-4

Sandboxing (Recommended)

For specs from authors you don’t fully trust, run inside a Docker container:

specmarket run @jaiden/docusign-replacement --sandbox docker

This isolates the build process from your host machine. The spec can only write to the /workspace directory inside the container.

6. Review the Output

When the Ralph Loop completes, you’ll see a summary:

Run complete!
  Status: success
  Success criteria: 12/12 passed
  Cost: $11.40
  Time: 34 minutes
  Model: claude-sonnet-4

  Output directory: ./my-docusign/

The output is a standard application in whatever tech stack the spec defines. Check the README in the output directory for deployment instructions.

Run the tests yourself to verify:

cd my-docusign
pnpm install
pnpm test

7. Submit Telemetry (Optional)

If you’re logged in and have opted in to telemetry, the CLI submits a run report:

specmarket report latest

This shows exactly what was submitted: spec ID, version, model, tokens used, cost, time, status, and which success criteria passed or failed. No source code is ever transmitted — only metadata.

Telemetry is opt-in (default: off). Enable it with:

specmarket config set telemetry true

You can delete all your telemetry data at any time:

specmarket config delete-telemetry

What’s Next

Spec Format Reference — Understand how specs are structured
What is a Ralph Loop? — Deep dive into the autonomous build process
Explore Specs — Browse all available specs
Publishing Your First Spec — Create and share your own specs

Troubleshooting

“Command not found: specmarket” Make sure pnpm’s global bin directory is in your PATH. Run pnpm bin -g to find the directory, then add it to your shell profile.

“Spec validation failed” The downloaded spec has structural issues. This is rare for published specs (they’re validated on publish). Try specmarket validate ./path-to-spec for details.

“Ralph Loop stalled” The agent couldn’t make progress. Check the run report for which success criteria failed. Try running again (agents aren’t deterministic — results vary between runs). If the spec consistently stalls, check the spec’s success rate on the marketplace.

“Rate limit exceeded” The CLI enforces rate limits: max 10 run submissions per hour. Wait and try again.