> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ticket-rs.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Commands

> Complete tk command reference

Complete reference for every `tk` subcommand and its options. Generated from the `clap` parser surface so it never drifts from the binary.

<Tip>
  Use `tk help <command>` to get detailed help for any command at the terminal.
</Tip>

***

## Core Commands

### `tk init`

Initialize ticket tracking in a directory

```bash theme={null}
tk init [OPTIONS]
```

**Options:**

| Option                  | Description                                              |
| ----------------------- | -------------------------------------------------------- |
| `-p, --prefix <PREFIX>` | Custom prefix for issue IDs (default: tk). Default: `tk` |
| `--index`               | Index and import non-compliant markdown files            |

***

### `tk create`

Create a new issue

**Aliases:** `new`, `add`

```bash theme={null}
tk create <TITLE> [OPTIONS]
```

**Arguments:**

| Argument  | Description                |
| --------- | -------------------------- |
| `<TITLE>` | Issue title. **Required.** |

**Options:**

| Option                            | Description                                                          |
| --------------------------------- | -------------------------------------------------------------------- |
| `-d, --description <DESCRIPTION>` | Issue description (body text)                                        |
| `-p, --priority <PRIORITY>`       | Priority level (0=critical, 4=lowest). Default: `2`                  |
| `-t, --type <ISSUE-TYPE>`         | Issue type (task, feature, bug, epic, spike, chore). Default: `task` |
| `--deps <DEPS>`                   | Blocking dependencies (comma-separated IDs)                          |
| `--parent <PARENT>`               | Parent issue ID                                                      |
| `-l, --labels <LABELS>`           | Labels (comma-separated)                                             |
| `-c, --close <CLOSE>`             | Create as already closed (for post-hoc tracking)                     |

***

### `tk show`

Show issue details

```bash theme={null}
tk show <ID>
```

**Arguments:**

| Argument | Description                        |
| -------- | ---------------------------------- |
| `<ID>`   | Issue ID to display. **Required.** |

***

### `tk list`

List issues

**Aliases:** `ls`

```bash theme={null}
tk list [OPTIONS]
```

**Options:**

| Option                      | Description                                                                          |
| --------------------------- | ------------------------------------------------------------------------------------ |
| `-s, --status <STATUS>`     | Filter by status (open, in\_progress, closed, blocked, deferred)                     |
| `-t, --type <ISSUE-TYPE>`   | Filter by issue type                                                                 |
| `-p, --priority <PRIORITY>` | Filter by priority level (0=critical, 4=lowest)                                      |
| `--all`                     | Show all issues including closed                                                     |
| `-l, --label <LABEL>`       | Filter by label: "x,y" matches issues with ALL labels (AND), "x\|y" matches ANY (OR) |
| `--sparse`                  | Sparse output (minimal details: one "id title" line per issue)                       |
| `--dense`                   | Dense output (full details: labels, assignee, deps, description)                     |
| `-n, --limit <LIMIT>`       | Limit number of results (default 50, use 0 for unlimited). Default: `50`             |

***

### `tk update`

Update an issue

```bash theme={null}
tk update <ID> [FIELDS] [OPTIONS]
```

**Arguments:**

| Argument   | Description                                                        |
| ---------- | ------------------------------------------------------------------ |
| `<ID>`     | Issue ID to update. **Required.**                                  |
| `<FIELDS>` | Field updates in KEY=VALUE format (e.g., status=closed priority=1) |

**Options:**

| Option                      | Description                                                                              |
| --------------------------- | ---------------------------------------------------------------------------------------- |
| `--title <TITLE>`           | New title for the issue                                                                  |
| `-s, --status <STATUS>`     | New status (open, in\_progress, closed, blocked, deferred)                               |
| `-p, --priority <PRIORITY>` | New priority level (0=critical, 4=lowest)                                                |
| `-a, --assignee <ASSIGNEE>` | Assign to user                                                                           |
| `-t, --type <ISSUE-TYPE>`   | Issue type (task, feature, bug, epic, spike, chore)                                      |
| `--add-labels <ADD-LABELS>` | Add labels (comma-separated)                                                             |
| `--dry-run`                 | Dry run - show what would be changed without making changes                              |
| `--if-match <IF-MATCH>`     | ETag for optimistic concurrency control (use with `tk show -f json` to get current ETag) |

***

### `tk close`

Close an issue

```bash theme={null}
tk close <ID> [OPTIONS]
```

**Arguments:**

| Argument | Description                      |
| -------- | -------------------------------- |
| `<ID>`   | Issue ID to close. **Required.** |

**Options:**

| Option                  | Description        |
| ----------------------- | ------------------ |
| `-r, --reason <REASON>` | Reason for closing |

***

### `tk delete`

Delete an issue (move to archive or permanently remove)

**Aliases:** `rm`, `remove`

```bash theme={null}
tk delete <ID> [OPTIONS]
```

**Arguments:**

| Argument | Description                       |
| -------- | --------------------------------- |
| `<ID>`   | Issue ID to delete. **Required.** |

**Options:**

| Option      | Description                             |
| ----------- | --------------------------------------- |
| `--force`   | Permanently delete instead of archiving |
| `-y, --yes` | Skip confirmation prompt                |

***

### `tk dep`

Manage dependencies between issues

```bash theme={null}
tk dep [SUBCOMMAND]
```

#### `tk dep add`

Add a dependency (blocked depends on blocker)

```bash theme={null}
tk dep add <BLOCKED> <BLOCKER> [OPTIONS]
```

**Arguments:**

| Argument    | Description                                       |
| ----------- | ------------------------------------------------- |
| `<BLOCKED>` | Issue that will be blocked. **Required.**         |
| `<BLOCKER>` | Issue that blocks (the dependency). **Required.** |

**Options:**

| Option      | Description                                                 |
| ----------- | ----------------------------------------------------------- |
| `--dry-run` | Dry run - show what would be changed without making changes |

#### `tk dep remove`

Remove a dependency

**Aliases:** `rm`

```bash theme={null}
tk dep remove <BLOCKED> <BLOCKER> [OPTIONS]
```

**Arguments:**

| Argument    | Description                                                 |
| ----------- | ----------------------------------------------------------- |
| `<BLOCKED>` | Issue that is blocked. **Required.**                        |
| `<BLOCKER>` | Issue that blocks (the dependency to remove). **Required.** |

**Options:**

| Option      | Description                                                 |
| ----------- | ----------------------------------------------------------- |
| `--dry-run` | Dry run - show what would be changed without making changes |

#### `tk dep tree`

Show dependency tree

```bash theme={null}
tk dep tree <ID> [OPTIONS]
```

**Arguments:**

| Argument | Description                  |
| -------- | ---------------------------- |
| `<ID>`   | Root issue ID. **Required.** |

**Options:**

| Option                        | Description                                                                                                     |
| ----------------------------- | --------------------------------------------------------------------------------------------------------------- |
| `-d, --direction <DIRECTION>` | Direction: 'down' (what blocks this) or 'up' (what this blocks). Possible values: `down`, `up`. Default: `down` |
| `-m, --max-depth <MAX-DEPTH>` | Maximum tree depth. Default: `10`                                                                               |
| `-s, --status <STATUS>`       | Filter by status (open, in\_progress, etc.)                                                                     |

#### `tk dep list`

List direct dependencies

```bash theme={null}
tk dep list <ID> [OPTIONS]
```

**Arguments:**

| Argument | Description             |
| -------- | ----------------------- |
| `<ID>`   | Issue ID. **Required.** |

**Options:**

| Option                        | Description                                                                                           |
| ----------------------------- | ----------------------------------------------------------------------------------------------------- |
| `-d, --direction <DIRECTION>` | Direction: 'down' (dependencies) or 'up' (dependents). Possible values: `down`, `up`. Default: `down` |

#### `tk dep cycles`

Find dependency cycles

```bash theme={null}
tk dep cycles
```

***

### `tk edit`

Open an issue in your editor

```bash theme={null}
tk edit <ID>
```

**Arguments:**

| Argument | Description                     |
| -------- | ------------------------------- |
| `<ID>`   | Issue ID to edit. **Required.** |

***

### `tk board`

Interactive kanban board (TUI)

```bash theme={null}
tk board [OPTIONS]
```

**Options:**

| Option                | Description                                                         |
| --------------------- | ------------------------------------------------------------------- |
| `-l, --limit <LIMIT>` | Maximum issues per column (non-interactive fallback). Default: `10` |

***

## Workflow Commands

### `tk claim`

Claim an issue (mark in\_progress, show unblocked)

```bash theme={null}
tk claim <ID> [OPTIONS]
```

**Arguments:**

| Argument | Description                      |
| -------- | -------------------------------- |
| `<ID>`   | Issue ID to claim. **Required.** |

**Options:**

| Option              | Description              |
| ------------------- | ------------------------ |
| `-n, --note <NOTE>` | Add a note when claiming |

***

### `tk resolve`

Resolve an issue (close and show unblocked dependents)

**Aliases:** `done`, `finish`

```bash theme={null}
tk resolve <ID> [OPTIONS]
```

**Arguments:**

| Argument | Description                        |
| -------- | ---------------------------------- |
| `<ID>`   | Issue ID to resolve. **Required.** |

**Options:**

| Option              | Description        |
| ------------------- | ------------------ |
| `-n, --note <NOTE>` | Add a closing note |

***

### `tk start`

Start an issue (alias for claim)

```bash theme={null}
tk start <ID>
```

**Arguments:**

| Argument | Description                      |
| -------- | -------------------------------- |
| `<ID>`   | Issue ID to start. **Required.** |

***

### `tk ready`

Show ready work (no open blockers)

```bash theme={null}
tk ready [OPTIONS]
```

**Options:**

| Option                | Description                                     |
| --------------------- | ----------------------------------------------- |
| `-l, --limit <LIMIT>` | Maximum number of issues to show. Default: `20` |
| `--no-cache`          | Skip cache and compute fresh                    |

***

## AI & Analytics Commands

### `tk triage`

AI triage: unified recommendations, quick wins, blockers, health

```bash theme={null}
tk triage [OPTIONS]
```

**Options:**

| Option           | Description                  |
| ---------------- | ---------------------------- |
| `--no-cache`     | Skip cache and compute fresh |
| `--no-pollution` | Skip pollution detection     |

***

### `tk next`

Get single top recommendation (minimal output)

```bash theme={null}
tk next [OPTIONS]
```

**Options:**

| Option       | Description                  |
| ------------ | ---------------------------- |
| `--no-cache` | Skip cache and compute fresh |

***

### `tk priority`

Get AI-optimized priority recommendations

```bash theme={null}
tk priority [OPTIONS]
```

**Options:**

| Option       | Description                  |
| ------------ | ---------------------------- |
| `--no-cache` | Skip cache and compute fresh |

***

### `tk plan`

Get parallel execution plan

```bash theme={null}
tk plan [OPTIONS]
```

**Options:**

| Option       | Description                  |
| ------------ | ---------------------------- |
| `--no-cache` | Skip cache and compute fresh |

***

### `tk stacks`

Detect linear dependency stacks (Graphite-style)

```bash theme={null}
tk stacks [SUBCOMMAND]
```

#### `tk stacks list`

List detected stacks (default)

**Aliases:** `ls`

```bash theme={null}
tk stacks list [OPTIONS]
```

**Options:**

| Option       | Description                            |
| ------------ | -------------------------------------- |
| `--no-cache` | Skip cache and compute fresh           |
| `--all`      | Show stacks including closed issues    |
| `--ready`    | Show only stacks with all issues ready |

#### `tk stacks show`

Show detailed information about a specific stack

```bash theme={null}
tk stacks show <STACK-ID> [OPTIONS]
```

**Arguments:**

| Argument     | Description                                                |
| ------------ | ---------------------------------------------------------- |
| `<STACK-ID>` | Stack ID (e.g., "stack-1") or root issue ID. **Required.** |

**Options:**

| Option       | Description                  |
| ------------ | ---------------------------- |
| `--no-cache` | Skip cache and compute fresh |

#### `tk stacks create`

Create a new dependency chain (stack) from titles or existing issue IDs

**Aliases:** `new`

```bash theme={null}
tk stacks create <ITEMS> [OPTIONS]
```

**Arguments:**

| Argument  | Description                                                             |
| --------- | ----------------------------------------------------------------------- |
| `<ITEMS>` | Issue titles or existing issue IDs (at least 2 required). **Required.** |

**Options:**

| Option                          | Description                                                                     |
| ------------------------------- | ------------------------------------------------------------------------------- |
| `-t, --issue-type <ISSUE-TYPE>` | Issue type for newly created issues (task, feature, bug, etc.). Default: `task` |
| `-p, --priority <PRIORITY>`     | Priority for newly created issues (0=critical, 4=lowest). Default: `2`          |
| `--dry-run`                     | Preview what would happen without making changes                                |

#### `tk stacks validate`

Validate stack integrity (no cycles, valid dependencies)

```bash theme={null}
tk stacks validate <STACK-ID> [OPTIONS]
```

**Arguments:**

| Argument     | Description                                                |
| ------------ | ---------------------------------------------------------- |
| `<STACK-ID>` | Stack ID (e.g., "stack-1") or root issue ID. **Required.** |

**Options:**

| Option       | Description                  |
| ------------ | ---------------------------- |
| `--no-cache` | Skip cache and compute fresh |

#### `tk stacks merge`

Merge a stack (close all issues and combine into final deliverable)

```bash theme={null}
tk stacks merge <STACK-ID> [OPTIONS]
```

**Arguments:**

| Argument     | Description                                                |
| ------------ | ---------------------------------------------------------- |
| `<STACK-ID>` | Stack ID (e.g., "stack-1") or root issue ID. **Required.** |

**Options:**

| Option       | Description                                      |
| ------------ | ------------------------------------------------ |
| `--no-cache` | Skip cache and compute fresh                     |
| `--dry-run`  | Preview what would happen without making changes |
| `-y, --yes`  | Skip confirmation prompt                         |

#### `tk stacks worktree`

Manage git worktrees for stacks

```bash theme={null}
tk stacks worktree [SUBCOMMAND]
```

##### `tk stacks worktree create`

Create a worktree for a specific stack

```bash theme={null}
tk stacks worktree create <STACK-ID> [OPTIONS]
```

**Arguments:**

| Argument     | Description                                                |
| ------------ | ---------------------------------------------------------- |
| `<STACK-ID>` | Stack ID (e.g., "stack-1") or root issue ID. **Required.** |

**Options:**

| Option       | Description                            |
| ------------ | -------------------------------------- |
| `--no-cache` | Skip cache and compute fresh           |
| `--force`    | Force creation even if worktree exists |

##### `tk stacks worktree list`

List existing stack worktrees

**Aliases:** `ls`

```bash theme={null}
tk stacks worktree list
```

##### `tk stacks worktree remove`

Remove a stack worktree

**Aliases:** `rm`

```bash theme={null}
tk stacks worktree remove <STACK-ID> [OPTIONS]
```

**Arguments:**

| Argument     | Description                                                |
| ------------ | ---------------------------------------------------------- |
| `<STACK-ID>` | Stack ID (e.g., "stack-1") or root issue ID. **Required.** |

**Options:**

| Option    | Description                 |
| --------- | --------------------------- |
| `--force` | Force removal even if dirty |

***

### `tk insights`

Get graph analytics (PageRank, betweenness, etc.)

```bash theme={null}
tk insights [OPTIONS]
```

**Options:**

| Option       | Description                  |
| ------------ | ---------------------------- |
| `--no-cache` | Skip cache and compute fresh |

***

### `tk stats`

Show statistics

**Aliases:** `st`

```bash theme={null}
tk stats [OPTIONS]
```

**Options:**

| Option       | Description                  |
| ------------ | ---------------------------- |
| `--no-cache` | Skip cache and compute fresh |

***

### `tk prime`

Output AI-optimized workflow context for Claude Code hooks

```bash theme={null}
tk prime [OPTIONS]
```

**Options:**

| Option           | Description                       |
| ---------------- | --------------------------------- |
| `--full`         | Include full issue details        |
| `--mcp`          | Format output for MCP integration |
| `--stealth`      | Suppress non-essential output     |
| `--no-pollution` | Skip pollution detection          |

***

### `tk graph`

Visualize the dependency graph

```bash theme={null}
tk graph [OPTIONS]
```

**Options:**

| Option            | Description                                         |
| ----------------- | --------------------------------------------------- |
| `--root <ROOT>`   | Show only subgraph rooted at this issue             |
| `--depth <DEPTH>` | Maximum depth to traverse                           |
| `--mermaid`       | Output raw Mermaid.js syntax                        |
| `--html`          | Output self-contained HTML page with rendered graph |
| `--markdown`      | Output Markdown with Mermaid code block             |
| `--no-cache`      | Skip cache and compute fresh                        |

***

### `tk standup`

Generate standup report with git history and analytics

```bash theme={null}
tk standup [OPTIONS]
```

**Options:**

| Option                      | Description                                                                                                       |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `--days <DAYS>`             | Number of days for git history (default: 7). Default: `7`                                                         |
| `-o, --output <OUTPUT>`     | Output format (xml, json, markdown, pretty). Possible values: `xml`, `json`, `markdown`, `pretty`. Default: `xml` |
| `--next-steps <NEXT-STEPS>` | Include detailed next steps for specific issues (comma-separated IDs)                                             |
| `--top-ready <TOP-READY>`   | Include top N ready issues in next steps                                                                          |
| `--no-cache`                | Skip cache and compute fresh                                                                                      |

***

## Search Commands

### `tk search`

Search issues using BM25

```bash theme={null}
tk search <QUERY> [OPTIONS]
```

**Arguments:**

| Argument  | Description                        |
| --------- | ---------------------------------- |
| `<QUERY>` | Search query string. **Required.** |

**Options:**

| Option                | Description                              |
| --------------------- | ---------------------------------------- |
| `-l, --limit <LIMIT>` | Maximum number of results. Default: `10` |

***

### `tk similar`

Find similar issues

```bash theme={null}
tk similar <ID> [OPTIONS]
```

**Arguments:**

| Argument | Description                                        |
| -------- | -------------------------------------------------- |
| `<ID>`   | Issue ID to find similar issues for. **Required.** |

**Options:**

| Option                | Description                             |
| --------------------- | --------------------------------------- |
| `-l, --limit <LIMIT>` | Maximum number of results. Default: `5` |

***

### `tk duplicates`

Find and manage duplicate issues

```bash theme={null}
tk duplicates [OPTIONS]
```

**Options:**

| Option                    | Description                                                  |
| ------------------------- | ------------------------------------------------------------ |
| `--auto-merge`            | Automatically merge detected duplicates                      |
| `--dry-run`               | Preview without making changes                               |
| `--threshold <THRESHOLD>` | Similarity threshold for duplicate detection. Default: `5.0` |
| `--keep-newest`           | Keep newest issue when merging duplicates                    |

***

### `tk grep`

Grep issue content (powered by ripgrep)

```bash theme={null}
tk grep <PATTERN> [OPTIONS]
```

**Arguments:**

| Argument    | Description                                |
| ----------- | ------------------------------------------ |
| `<PATTERN>` | Regex pattern to search for. **Required.** |

**Options:**

| Option              | Description                   |
| ------------------- | ----------------------------- |
| `-i, --ignore-case` | Case insensitive search       |
| `--files-only`      | Only show matching file paths |
| `--absolute`        | Show absolute file paths      |

***

## Integration Commands

### `tk linear`

Linear integration

```bash theme={null}
tk linear [SUBCOMMAND]
```

#### `tk linear sync`

Sync issues with Linear

```bash theme={null}
tk linear sync [OPTIONS]
```

**Options:**

| Option            | Description                                                            |
| ----------------- | ---------------------------------------------------------------------- |
| `--pull`          | Pull issues from Linear                                                |
| `--push`          | Push local issues to Linear                                            |
| `--dry-run`       | Dry run - show what would be synced                                    |
| `--create-only`   | Only create new issues, don't update existing                          |
| `--state <STATE>` | Issue state filter: open, closed, all (default: open). Default: `open` |

#### `tk linear status`

Show Linear sync status

```bash theme={null}
tk linear status
```

#### `tk linear teams`

List available Linear teams

```bash theme={null}
tk linear teams
```

***

### `tk github`

GitHub integration

```bash theme={null}
tk github [SUBCOMMAND]
```

#### `tk github sync`

Sync issues with GitHub

```bash theme={null}
tk github sync [OPTIONS]
```

**Options:**

| Option            | Description                                                            |
| ----------------- | ---------------------------------------------------------------------- |
| `--pull`          | Pull issues from GitHub                                                |
| `--push`          | Push local issues to GitHub                                            |
| `--dry-run`       | Dry run - show what would be synced                                    |
| `--create-only`   | Only create new issues, don't update existing                          |
| `--state <STATE>` | Issue state filter: open, closed, all (default: open). Default: `open` |

#### `tk github status`

Show GitHub sync status

```bash theme={null}
tk github status
```

***

### `tk claude`

Claude Code Tasks integration

```bash theme={null}
tk claude [SUBCOMMAND]
```

#### `tk claude sync`

Sync issues with Claude Code tasks

```bash theme={null}
tk claude sync [OPTIONS]
```

**Options:**

| Option            | Description                                                        |
| ----------------- | ------------------------------------------------------------------ |
| `--pull`          | Pull tasks from Claude to tk                                       |
| `--push`          | Push issues from tk to Claude                                      |
| `--dry-run`       | Dry run - show what would be synced                                |
| `--state <STATE>` | Only sync open/in-progress issues (default: open). Default: `open` |

#### `tk claude status`

Show Claude sync status and current session

```bash theme={null}
tk claude status
```

***

### `tk trello`

Trello integration

```bash theme={null}
tk trello [SUBCOMMAND]
```

#### `tk trello sync`

Sync issues with Trello

```bash theme={null}
tk trello sync [OPTIONS]
```

**Options:**

| Option            | Description                                                           |
| ----------------- | --------------------------------------------------------------------- |
| `--pull`          | Pull cards from Trello                                                |
| `--push`          | Push local issues to Trello                                           |
| `--dry-run`       | Dry run - show what would be synced                                   |
| `--create-only`   | Only create new cards, don't update existing                          |
| `--state <STATE>` | Card state filter: open, closed, all (default: open). Default: `open` |

#### `tk trello status`

Show Trello sync status

```bash theme={null}
tk trello status
```

#### `tk trello boards`

List available Trello boards

```bash theme={null}
tk trello boards
```

#### `tk trello lists`

Show the inferred list\_id -> status mapping for the configured board

```bash theme={null}
tk trello lists
```

***

## Admin Commands

### `tk config`

Manage configuration

```bash theme={null}
tk config [SUBCOMMAND]
```

#### `tk config get`

Get a config value

```bash theme={null}
tk config get <KEY>
```

**Arguments:**

| Argument | Description                                       |
| -------- | ------------------------------------------------- |
| `<KEY>`  | Config key (e.g., linear.api\_key). **Required.** |

#### `tk config set`

Set a config value

```bash theme={null}
tk config set <KEY> <VALUE> [OPTIONS]
```

**Arguments:**

| Argument  | Description                 |
| --------- | --------------------------- |
| `<KEY>`   | Config key. **Required.**   |
| `<VALUE>` | Config value. **Required.** |

**Options:**

| Option     | Description                                           |
| ---------- | ----------------------------------------------------- |
| `--global` | Set as global credential (shared across all projects) |

#### `tk config list`

List all config values

```bash theme={null}
tk config list
```

#### `tk config unset`

Unset a config value

```bash theme={null}
tk config unset <KEY>
```

**Arguments:**

| Argument | Description               |
| -------- | ------------------------- |
| `<KEY>`  | Config key. **Required.** |

***

### `tk setup`

Set up integrations (claude, etc.)

```bash theme={null}
tk setup [SUBCOMMAND]
```

#### `tk setup claude`

Set up Claude Code integration (hooks for tk prime)

```bash theme={null}
tk setup claude [OPTIONS]
```

**Options:**

| Option     | Description                               |
| ---------- | ----------------------------------------- |
| `--global` | Install globally (default: project-local) |
| `--remove` | Remove hooks instead of installing        |

***

### `tk hooks`

Manage git hooks

```bash theme={null}
tk hooks [SUBCOMMAND]
```

#### `tk hooks install`

Install tk git hooks

```bash theme={null}
tk hooks install [OPTIONS]
```

**Options:**

| Option    | Description                    |
| --------- | ------------------------------ |
| `--force` | Force overwrite existing hooks |

#### `tk hooks check`

Check if hooks are installed

```bash theme={null}
tk hooks check
```

#### `tk hooks remove`

Remove tk git hooks

```bash theme={null}
tk hooks remove
```

***

### `tk doctor`

Check installation health and fix issues

```bash theme={null}
tk doctor [OPTIONS]
```

**Options:**

| Option  | Description                       |
| ------- | --------------------------------- |
| `--fix` | Automatically fix detected issues |

***

### `tk validate`

Validate issue database integrity

```bash theme={null}
tk validate
```

***

### `tk lint`

Lint all ticket files (validate frontmatter syntax)

```bash theme={null}
tk lint [OPTIONS]
```

**Options:**

| Option  | Description                      |
| ------- | -------------------------------- |
| `--fix` | Automatically fix linting issues |

***

### `tk rules`

Check issues against custom rules (defined in .tickets/rules.toml)

```bash theme={null}
tk rules [OPTIONS]
```

**Options:**

| Option          | Description                     |
| --------------- | ------------------------------- |
| `-v, --verbose` | Show additional details (notes) |

***

### `tk serve`

Start a local HTTP server with a kanban board view

```bash theme={null}
tk serve [OPTIONS]
```

**Options:**

| Option              | Description                                        |
| ------------------- | -------------------------------------------------- |
| `-p, --port <PORT>` | Port to listen on (default: 8080). Default: `8080` |
| `--open`            | Open browser automatically                         |

***

### `tk cache`

Manage analytics cache

```bash theme={null}
tk cache [SUBCOMMAND]
```

#### `tk cache info`

Show cache statistics and status

```bash theme={null}
tk cache info
```

#### `tk cache clear`

Delete all cached data

```bash theme={null}
tk cache clear
```

#### `tk cache rebuild`

Force rebuild the cache

```bash theme={null}
tk cache rebuild
```

***

## Git Commands

### `tk worktree`

Manage git worktrees with shared tickets

```bash theme={null}
tk worktree [SUBCOMMAND]
```

#### `tk worktree ready`

Create worktrees for all ready issues

```bash theme={null}
tk worktree ready [OPTIONS]
```

**Options:**

| Option              | Description                                                        |
| ------------------- | ------------------------------------------------------------------ |
| `--dry-run`         | Show what would be created without actually creating               |
| `--force`           | Force creation even if worktree exists                             |
| `--limit <LIMIT>`   | Maximum number of worktrees to create (default: 10). Default: `10` |
| `--issues <ISSUES>` | Specific issue IDs to create worktrees for (comma-separated)       |

#### `tk worktree sync`

Sync all worktrees with trunk (rebase onto master/main)

```bash theme={null}
tk worktree sync [OPTIONS]
```

**Options:**

| Option                | Description                                                                       |
| --------------------- | --------------------------------------------------------------------------------- |
| `--dry-run`           | Show what would be synced without actually syncing                                |
| `--continue-on-error` | Continue on error (don't stop at first failed rebase)                             |
| `--trunk <TRUNK>`     | Trunk branch to sync with (default: main or master, or current non-ticket branch) |

#### `tk worktree merge`

Merge worktrees back to trunk via merge queue

```bash theme={null}
tk worktree merge [OPTIONS]
```

**Options:**

| Option            | Description                                                                        |
| ----------------- | ---------------------------------------------------------------------------------- |
| `--dry-run`       | Show merge queue without executing                                                 |
| `--issue <ISSUE>` | Specific issue ID to merge (otherwise merges all ready)                            |
| `--trunk <TRUNK>` | Trunk branch to merge into (default: main or master, or current non-ticket branch) |

#### `tk worktree list`

List all worktrees with status

```bash theme={null}
tk worktree list
```

#### `tk worktree queue`

Show merge queue status

```bash theme={null}
tk worktree queue [OPTIONS]
```

**Options:**

| Option            | Description                                                          |
| ----------------- | -------------------------------------------------------------------- |
| `--trunk <TRUNK>` | Trunk branch (default: main or master, or current non-ticket branch) |
| `--process`       | Process the queue (actually merge pending items)                     |

#### `tk worktree remove`

Remove a worktree

```bash theme={null}
tk worktree remove <ID> [OPTIONS]
```

**Arguments:**

| Argument | Description                              |
| -------- | ---------------------------------------- |
| `<ID>`   | Issue ID or worktree path. **Required.** |

**Options:**

| Option    | Description                 |
| --------- | --------------------------- |
| `--force` | Force removal even if dirty |

#### `tk worktree prune`

Clean up worktrees for closed issues

```bash theme={null}
tk worktree prune [OPTIONS]
```

**Options:**

| Option      | Description                                          |
| ----------- | ---------------------------------------------------- |
| `--dry-run` | Show what would be removed without actually removing |

***

### `tk diff`

Show ticket differences between branches or time periods

```bash theme={null}
tk diff [OPTIONS]
```

**Options:**

| Option            | Description                                                                  |
| ----------------- | ---------------------------------------------------------------------------- |
| `--base <BASE>`   | Base branch or ref to compare against (default: main/master)                 |
| `--since <SINCE>` | Compare against a point in time (days ago or date, e.g. "7" or "2025-01-15") |
| `--pretty`        | Human-readable pretty output instead of git-diff style                       |

***

## Misc Commands

### `tk version`

Print version information

```bash theme={null}
tk version
```

***

### `tk hello`

Interactive onboarding and preferences setup

```bash theme={null}
tk hello [OPTIONS]
```

**Options:**

| Option     | Description                             |
| ---------- | --------------------------------------- |
| `--setup`  | Run the interactive setup wizard        |
| `--prompt` | Output the steering prompt for AGENT.md |

***

## Global Options

These options are available on every subcommand:

| Option                  | Description                                                                    |
| ----------------------- | ------------------------------------------------------------------------------ |
| `-C, --dir <DIR>`       | Working directory (default: current)                                           |
| `-f, --format <FORMAT>` | Output format. Possible values: `compact`, `table`, `json`. Default: `compact` |
| `--json`                | Output as JSON (shorthand for --format json)                                   |
| `--strict`              | Fail on parse errors instead of skipping malformed ticket files                |

***

## See Also

* [Quickstart Guide](/quickstart) — Get started with `tk`
* [Dependencies](/concepts/dependencies) — Managing issue dependencies
* [Graph Analytics](/concepts/graph-analytics) — PageRank, critical path, and more
* [Stacks](/concepts/stacks) — Linear dependency chains
* [GitHub Integration](/integrations/github) — Sync with GitHub Issues
* [Linear Integration](/integrations/linear) — Sync with Linear
* [MCP Integration](/integrations/mcp) — Use with Claude AI