CLI Reference | Specwright
Description: AI-native enterprise documentation platform. Living specs, agent-maintained docs, repo-native knowledge.

Skip to content

# CLI Reference ​

Auto-Generated

This page was auto-generated from `specwright --help` on 2026-03-04 16:52 UTC. See source script.

The Specwright CLI provides local spec management commands.

## Installation ​

bash

    # With uv (recommended)
    uv tool install gv-specwright

    # With pip
    pip install gv-specwright

    # Run without installing
    uvx --from gv-specwright specwright --help

## Commands ​

    usage: specwright [-h]

### `specwright setup` ​

Initialize a repository for Specwright. Creates `SPECWRIGHT.yaml`, the spec directory, and a starter template.

bash

    usage: specwright setup [-h] [--team TEAM] [--ticket-system {github,jira,linear}] [--non-interactive]

Options:

Option | Description
--- | ---
`-h, --help` | show this help message and exit
`--team TEAM` | Team name for SPECWRIGHT.yaml
`--ticket-system {github,jira,linear}` | Ticket system (default: github)
`--non-interactive` | Skip prompts (for CI/Actions)

### `specwright login` ​

Authenticate with the Specwright platform using device authorization flow or API key.

bash

    usage: specwright login [-h] [--api-key API_KEY] [--server SERVER]

Options:

Option | Description
--- | ---
`-h, --help` | show this help message and exit
`--api-key API_KEY` | Authenticate with an API key instead of OAuth
`--server SERVER` | Platform URL (default: $SPECWRIGHT_URL or https://specwright.gernerventures.com)

### `specwright logout` ​

Log out and revoke the current session.

bash

    usage: specwright logout [-h]

Options:

Option | Description
--- | ---
`-h, --help` | show this help message and exit

### `specwright auth` ​

Authentication utilities. Use `auth status` to check current authentication state.

bash

    usage: specwright auth [-h] {status} ...

Arguments:

Argument | Description
--- | ---
`status` | Show current authentication status

Options:

Option | Description
--- | ---
`-h, --help` | show this help message and exit

#### `specwright auth status` ​

bash

    usage: specwright auth status [-h]

Options:

Option | Description
--- | ---
`-h, --help` | show this help message and exit

### `specwright tasks` ​

List actionable work items from specs. Shows sections with `todo` or `in_progress` status and their acceptance criteria.

bash

    usage: specwright tasks [-h] [--status STATUS] [--spec SPEC] [--all]

Options:

Option | Description
--- | ---
`-h, --help` | show this help message and exit
`--status STATUS` | Filter by specific status
`--spec SPEC` | Filter to a single spec file
`--all` | Include done/deprecated/draft

### `specwright status` ​

Show spec coverage dashboard. Displays per-spec and aggregate coverage metrics.

bash

    usage: specwright status [-h] [--spec SPEC]

Options:

Option | Description
--- | ---
`-h, --help` | show this help message and exit
`--spec SPEC` | Show detail for a single spec file

### `specwright start` ​

Mark a spec section as `in_progress`. Optionally creates or updates a linked GitHub Issue.

bash

    usage: specwright start [-h] [--issue] section_id

Arguments:

Argument | Description
--- | ---
`section_id` | Section ID, number, or partial slug

Options:

Option | Description
--- | ---
`-h, --help` | show this help message and exit
`--issue` | Create/update GitHub Issue for this section

### `specwright done` ​

Mark a spec section as `done`. Optionally closes the linked GitHub Issue.

bash

    usage: specwright done [-h] [--issue] section_id

Arguments:

Argument | Description
--- | ---
`section_id` | Section ID, number, or partial slug

Options:

Option | Description
--- | ---
`-h, --help` | show this help message and exit
`--issue` | Update/close GitHub Issue if ticket link exists

### `specwright sync` ​

Sync spec sections with the configured ticket system (GitHub Issues, Jira, or Linear). Supports forward sync (spec → tickets) and reverse sync (tickets → spec).

bash

    usage: specwright sync [-h] [--reverse] [--spec SPEC] [--dry-run] [--local]

Options:

Option | Description
--- | ---
`-h, --help` | show this help message and exit
`--reverse` | Pull ticket statuses into spec markdown
`--spec SPEC` | Filter to a single spec file
`--dry-run` | Preview changes without executing
`--local` | Bypass server proxy and use GITHUB_TOKEN / gh CLI directly

### `specwright verify` ​

Verify acceptance criteria against the codebase using Claude. Reports which ACs are realized, partial, or not found.

bash

    usage: specwright verify [-h] [--section SECTION]

Options:

Option | Description
--- | ---
`-h, --help` | show this help message and exit
`--section SECTION` | Filter to a single section ID

### `specwright audit` ​

Audit spec statuses against the codebase using Claude. Checks off realized ACs, inserts evidence comments, and optionally runs ticket sync.

bash

    usage: specwright audit [-h] [--dry-run] [--sync] [--spec SPEC] [--no-ac-updates]

Options:

Option | Description
--- | ---
`-h, --help` | show this help message and exit
`--dry-run` | Preview changes without writing
`--sync` | Run ticket sync after audit
`--spec SPEC` | Filter to a single spec file
`--no-ac-updates` | Skip checking off ACs and inserting evidence

### `specwright plan` ​

Generate a task plan from a spec. Outputs a structured implementation plan based on unchecked acceptance criteria.

bash

    usage: specwright plan [-h] [--output OUTPUT] spec_file

Arguments:

Argument | Description
--- | ---
`spec_file` | Spec file path or partial match

Options:

Option | Description
--- | ---
`-h, --help` | show this help message and exit
`--output OUTPUT` | Write plan to file instead of stdout