Getting started

This is the fastest path through Spec0: install the CLI, set up your AI agent in one command, then publish your first spec, spin up a mock, and wire it into CI.

Prerequisites

• Node.js 20+ (for the CLI)
• A Spec0 account — sign up at spec0.io
• An OpenAPI spec — any 3.0.x / 3.1.x, YAML or JSON

1. Install the CLI

npm install -g @spec0/cli
spec0 --version

2. Authenticate

spec0 auth login

A browser tab opens; approve and return to the terminal. Your credentials are stored in ~/.spec0/config.json. (For CI and agents, set SPEC0_TOKEN instead — see step 6.)

3. Set up your agent — one command

spec0 setup

This wires up everything an AI coding agent needs, in one step:

1. Verifies your sign-in (so the org-scoped tools are ready to unlock).
2. Installs the Spec0 MCP server into Cursor and Claude.
3. Installs the Spec0 skill for Claude Code so the agent knows to discover and read your APIs through Spec0 instead of guessing.

It's safe to re-run any time. Useful flags: --client cursor|claude|all (default all) and --scope personal|project (where the Claude skill is written).

spec0 mcp install            # point Cursor / Claude at the Spec0 MCP server
spec0 skill install          # install the Spec0 skill for Claude Code
spec0 auth status            # confirm you're signed in

Restart your client. On first MCP use a browser opens to sign in (OAuth); once you're signed in, the org-scoped tools light up. Then ask it things like "which of our APIs handles refunds, and what do I send?" — see API discovery.

4. Publish a spec

From a directory containing your openapi.yaml:

spec0 init                              # detect the spec, write .spec0.yaml
spec0 lint openapi.yaml --min-score 80  # optional quality gate (exit 7 if below)
spec0 publish openapi.yaml --semver     # publish to the public registry

How the version is chosen: with --semver, if the last published version is valid semver, Spec0 bumps the patch component (1.2.3 → 1.2.4); otherwise it uses the spec's info.version, falling back to 0.1.0. Pass --version <tag> to pin an explicit tag. Re-publishing identical content is a no-op. See Versioning for the full model.

5. Spin up a mock

spec0 mock create --api my-api   # provisions a mock (one-time key on first run)
spec0 mock url my-api            # prints the base URL

Point your app at that URL and hit any path in your spec — you get realistic responses generated from the schema. The mock automatically serves your latest published version. See Mock server for variants, conditional responses (CEL), and validation.

6. Wire it into CI

name: Spec0
on:
  push:
    branches: [main]
    paths: ['openapi.yaml']
jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: '20' }
      - run: npm install -g @spec0/cli
      - run: spec0 publish openapi.yaml --semver
        env:
          SPEC0_TOKEN: ${{ secrets.SPEC0_TOKEN }}
          SPEC0_ORG_ID: ${{ secrets.SPEC0_ORG_ID }}

spec0 ci generate github scaffolds this for you. To fail PRs on breaking changes, add spec0 diff --breaking-only — see the block-on-breaking-changes recipe and the full GitHub Actions guide.

What's next

• Concepts — the mental model: registry, specs, versions, mocks, governance.
• CLI — the full command surface and workflow guides.
• Mock server — variants, schema validation, CEL expressions.
• Agents & MCP — let an agent work over your registry, and install the Spec0 skill.