CLI Reference

Auto-Generated

This page was auto-generated from specwright --help on 2026-03-04 18:08 UTC. See source script.

The Specwright CLI provides local spec management commands.

Installation

# 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.

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.

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.

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.

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

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.

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.

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.

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.

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).

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.

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.

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.

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

---