---
# This file is auto-generated. Do not edit manually.
# Generated: 2026-03-04 16:10 UTC
---

# CLI Reference

::: tip Auto-Generated
This page was auto-generated from `specwright --help` on 2026-03-04 16:10 UTC.
See [source script](https://github.com/Gerner-Ventures/gv-exp-specwright/blob/main/docs-site/.vitepress/scripts/gen-cli-ref.py).
:::

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 |


---
