CLI reference

The nitpick CLI is the primary entry point. Global flags apply to all subcommands.

Global flags

Flag	Description
-c, --config <path>	Path to nitpick.yaml. Defaults to ./nitpick.yaml
-h, --help	Show help for any subcommand
-V, --version	Print version

nitpick init

Interactive setup wizard. Walks you through project name, base URL, LLM provider + API key, model selection (with per-run cost estimates), role credentials (login URL path is optional for SPAs that auto-redirect), critical pages, terminal guards, optional flow narrative, and an optional persistent instructions block that the scope router applies on every run.

nitpick init [--force]

Flag	Description
--force	Overwrite existing nitpick.yaml without asking

Writes nitpick.yaml and .env in the current directory. The CLI auto-loads .env on every subsequent run — you don’t need to export credentials manually.

nitpick mcp (v2.0+)

Manage the nitpick-kb MCP server — expose the knowledge base to Claude Code, Claude Desktop, Cursor, Cline, and any MCP-aware client.

nitpick mcp serve

Start the nitpick-kb MCP server on stdio. Add this as a server entry in your host’s MCP config and the KB becomes available as nitpick-kb in Claude Code, Cursor, etc.

nitpick mcp serve [options]

Flag	Description
-c, --config <path>	Path to nitpick.yaml (resolves KB path + trust from config)
--kb <path>	Override KB path (absolute recommended for external clients)
--trust <tier>	read-write (default) | read-only | deny

Tools exposed (read tier, always):

• kb_list_pages — list all discovered pages
• kb_get_page — get the Derived UI Model for a page
• kb_search — full-text search across the KB
• kb_list_open_bugs — list unfixed bugs
• kb_get_flow — get a multi-role flow definition

Additional tools (read-write trust only):

• kb_add_bug — record a new bug
• kb_note_flaky — mark a test as flaky
• kb_put_resolved_question — persist a Phase 3.5 resolution

Example Claude Code settings.json entry:

{
  "mcpServers": {
    "nitpick-kb": {
      "command": "nitpick",
      "args": ["mcp", "serve", "--kb", "/absolute/path/to/knowledge-base", "--trust", "read-write"]
    }
  }
}

nitpick skill (v1.1+)

Manage server-hosted OpenAI Skills. Opt-in alternative to the Chat Completions path — lets the skill live on OpenAI’s side, referenced by ID, instead of re-shipping SKILL.md in every call.

nitpick skill publish [-d <path>]

Zip a skill directory and POST /v1/skills to OpenAI. Prints the returned skill_id to paste into nitpick.yaml under llm.skill_id.

nitpick skill publish                             # defaults to the bundled prd-e2e-orchestrator
nitpick skill publish --dir ./my-custom-skill     # a custom skill you wrote

nitpick skill list

Enumerate every skill published to your OpenAI account.

nitpick skill versions <skill_id>

List all versions of one skill with timestamps.

nitpick skill promote <skill_id> <version>

Set a version as default_version. New runs that reference the skill without pinning skill_version pick this up.

nitpick prep

(Re)install Playwright browsers. Use this once after a fresh install, or later if browsers get cleared or Playwright is upgraded.

nitpick prep [--all-browsers]

Flag	Default	Description
--all-browsers	off	Install chromium, firefox, AND webkit. Default is chromium only.

nitpick providers

List LLM providers and their health status.

nitpick providers [-c <config>]

nitpick crawl

Build the page graph by crawling the app.

nitpick crawl [-c <config>] [--strategy <s>] [--max-depth <n>] [--max-pages <n>]

Flag	Default	Description
--strategy <s>	deterministic	deterministic | agent | auto. agent uses an LLM-driven crawler (v2.0+) for SPAs where the deterministic crawler under-discovers. auto falls back automatically when deterministic returns below a page threshold.
--goal <text>	—	Goal description for the LLM-assist crawler. Used with --strategy agent.
--max-depth <n>	5	BFS depth limit (deterministic)
--max-pages <n>	100	Pages per role

nitpick status

Summary of KB state: pages discovered, critical pages, flows configured.

nitpick status [-c <config>]

nitpick run

The main command. Runs Senior QA orchestration.

nitpick run [-c <config>] [-s <scope>] [options]

Scopes

Flag	Description
-s, --scope full	Test every known page + every configured flow
-s, --scope iterative	Test only pages affected by a described change (default)
-s, --scope smoke	Fast check of critical pages. No LLM, no test generation
-s, --scope targeted	Test a specific list of URLs

Flags

Flag	Description
--change <description>	Required for iterative. Plain-language change description
-u, --url <url...>	Required for targeted. Repeatable: -u /a -u /b
--non-interactive	Skip all HITL prompts. Auto-approves scope and Phase 3.5 kickoff. Agent self-writes approved.json rather than blocking on stdin. Use in CI.
--runs-dir <path>	Where to write run artifacts (default: ./runs)
--resume <run-id>	v1.2+. Resume a crashed / interrupted run. latest = most recent. Pages already marked passed are skipped at zero LLM cost.

Examples

# Iterative with change description
nitpick run --scope iterative --change "I modified the task creation form"

# Full regression, unattended (CI)
nitpick run --scope full --non-interactive

# Smoke check of critical pages
nitpick run --scope smoke

# Targeted specific pages
nitpick run --scope targeted --url /dashboard --url /tasks/new

# Resume a previous run
nitpick run --resume latest

Exit codes

Code	Meaning
0	Run completed, status = completed
1	Run failed, status = failed or cancelled

nitpick serve

Start the HTTP API server.

nitpick serve [-c <config>] [-p <port>]

See HTTP API reference for endpoints.

Environment variables

Variable	Purpose
ANTHROPIC_API_KEY	Anthropic provider key
OPENAI_API_KEY	OpenAI provider key
NITPICK_CONFIG	Config path override (same as -c)
NITPICK_LOG_LEVEL	debug / info (default) / warn / error
NITPICK_PORT	HTTP server port override
NITPICK_SKILLS_DIR	Override bundled skills location
CLAUDE_CODE_SESSION	Auto-set by Claude Code; switches delegate to in-process mode