Getting started

From zero to a published API in one terminal session.

Prerequisites

• Node 20+
• An OpenAPI spec, 3.0.x or 3.1.x, YAML or JSON — any example works; a trivial openapi.yaml in this guide. Other versions (including Swagger 2.0) are rejected at publish.

Install

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

Authenticate

spec0 auth login

Opens a browser, prompts for the org, writes ~/.config/spec0/config.json. Alternatively, skip this step and export SPEC0_TOKEN + SPEC0_ORG_ID.

Verify:

spec0 doctor

The output shows which source each value came from (env var, config file, or default).

Connect your agent

One command wires up everything an AI coding agent needs — it verifies your sign-in, installs the MCP server, and installs the Claude skill:

spec0 setup

Useful flags: --client cursor|claude|all (default all) and --scope personal|project. It's safe to re-run.

If you'd rather not install our CLI at all, Claude Code can add the MCP server itself:

claude mcp add --transport http spec0 https://api.spec0.io/mcp

Either way, your client runs an OAuth browser sign-in on first use — that sign-in, not the install, is what unlocks the org-scoped tools. See Agents & MCP.

Initialise

cd path/to/repo-with-openapi/
spec0 init

Detects the spec, writes .spec0.yaml:

specFile: openapi.yaml

Lint

spec0 lint openapi.yaml
spec0 lint openapi.yaml --min-score 80      # gate the pipeline
spec0 lint openapi.yaml --format github     # GitHub Actions annotations

Push (team-scoped, private)

spec0 push openapi.yaml --team platform

Publish (public registry)

spec0 publish openapi.yaml --semver

--semver asks the backend to compute the next semver tag based on the diff (PATCH / NON_BREAKING / BREAKING). Your openapi.yaml is not modified.

Verify

spec0 api list
spec0 api show my-api
spec0 log my-api

Next

• GitHub Actions CI — automate the publish.
• Mock server lifecycle — spin up a mock against the published spec.