CLI
Primitiv command-line interface reference.
Commands
| Command | Description |
|---|---|
primitiv init [dir] | Detect your project (framework, TypeScript, Tailwind, Figma, Storybook, package manager) and generate primitiv.config.js. Also writes a project-scoped MCP config, refreshes a Primitiv block in AGENTS.md and CLAUDE.md (or creates AGENTS.md if neither exists), installs a verify --strict GitHub Actions workflow on GitHub repos, and drops a /build-component skill for Claude Code. |
primitiv build [config] | Scan sources, resolve conflicts, lint for token misuse, write the contract. |
primitiv serve [config] | Start the MCP server against the built contract. Hot-reloads when the contract file changes. |
primitiv verify [config] [flags] | Re-run build and exit non-zero if conflicts are unresolved, token misuse is detected, or the contract is stale. Intended for CI. |
All commands accept an optional path argument. If omitted, Primitiv uses the current directory (init) or ./primitiv.config.js (build, serve, verify).
Frameworks detected by init
Next, Nuxt, Astro, SvelteKit, Remix, Expo, Qwik, Vite, Solid, React. Meta-frameworks are checked before their underlying libs to avoid mislabelling (SvelteKit, Astro, and Remix all depend on Vite internally, but they aren't reported as Vite). Monorepo workspace recursion is not supported yet — the root package.json drives detection.
Package manager is auto-detected from the lockfile (bun.lock → bunx, pnpm-lock.yaml → pnpm dlx, yarn.lock → yarn dlx, otherwise npx) and used in the generated MCP config.
Flags for verify
| Flag | Effect |
|---|---|
--strict | Escalate stale contract and token misuse to hard failure (exit 2). |
--json | Emit a machine-readable report to stdout. |
--fast | Use file mtimes for drift detection instead of rebuilding. Faster, but unreliable in CI / fresh clones. |
Exit codes for verify
| Code | Meaning |
|---|---|
0 | Contract is fresh, conflicts resolved, no token misuse |
1 | Stale contract OR token misuse detected (warning level, default) |
2 | Unresolved conflicts, OR --strict escalation of stale / token misuse |
3 | No config or contract found |
See Verify in CI for a worked example with token-misuse output and how to suppress false positives.