Commands - Ticket

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

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

Core Commands

`tk init`

Initialize ticket tracking in a directory

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

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

tk show <ID>

Arguments:

Argument	Description
`<ID>`	Issue ID to display. Required.

`tk list`

List issues Aliases: ls

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

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

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

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

tk dep [SUBCOMMAND]

`tk dep add`

Add a dependency (blocked depends on blocker)

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

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

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

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

tk dep cycles

`tk edit`

Open an issue in your editor

tk edit <ID>

Arguments:

Argument	Description
`<ID>`	Issue ID to edit. Required.

`tk board`

Interactive kanban board (TUI)

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)

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

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)

tk start <ID>

Arguments:

Argument	Description
`<ID>`	Issue ID to start. Required.

`tk ready`

Show ready work (no open blockers)

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

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)

tk next [OPTIONS]

Options:

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

`tk priority`

Get AI-optimized priority recommendations

tk priority [OPTIONS]

Options:

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

`tk plan`

Get parallel execution plan

tk plan [OPTIONS]

Options:

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

`tk stacks`

Detect linear dependency stacks (Graphite-style)

tk stacks [SUBCOMMAND]

`tk stacks list`

List detected stacks (default) Aliases: ls

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

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

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)

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)

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

tk stacks worktree [SUBCOMMAND]

`tk stacks worktree create`

Create a worktree for a specific stack

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

tk stacks worktree list

`tk stacks worktree remove`

Remove a stack worktree Aliases: rm

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

tk insights [OPTIONS]

Options:

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

`tk stats`

Show statistics Aliases: st

tk stats [OPTIONS]

Options:

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

`tk prime`

Output AI-optimized workflow context for Claude Code hooks

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

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

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

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

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

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)

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

tk linear [SUBCOMMAND]

`tk linear sync`

Sync issues with Linear

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

tk linear status

`tk linear teams`

List available Linear teams

tk linear teams

`tk github`

GitHub integration

tk github [SUBCOMMAND]

`tk github sync`

Sync issues with GitHub

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

tk github status

`tk claude`

Claude Code Tasks integration

tk claude [SUBCOMMAND]

`tk claude sync`

Sync issues with Claude Code tasks

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

tk claude status

`tk trello`

Trello integration

tk trello [SUBCOMMAND]

`tk trello sync`

Sync issues with Trello

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

tk trello status

`tk trello boards`

List available Trello boards

tk trello boards

`tk trello lists`

Show the inferred list_id -> status mapping for the configured board

tk trello lists

Admin Commands

`tk config`

Manage configuration

tk config [SUBCOMMAND]

`tk config get`

Get a config value

tk config get <KEY>

Arguments:

Argument	Description
`<KEY>`	Config key (e.g., linear.api_key). Required.

`tk config set`

Set a config value

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

tk config list

`tk config unset`

Unset a config value

tk config unset <KEY>

Arguments:

Argument	Description
`<KEY>`	Config key. Required.

`tk setup`

Set up integrations (claude, etc.)

tk setup [SUBCOMMAND]

`tk setup claude`

Set up Claude Code integration (hooks for tk prime)

tk setup claude [OPTIONS]

Options:

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

`tk hooks`

Manage git hooks

tk hooks [SUBCOMMAND]

`tk hooks install`

Install tk git hooks

tk hooks install [OPTIONS]

Options:

Option	Description
`--force`	Force overwrite existing hooks

`tk hooks check`

Check if hooks are installed

tk hooks check

`tk hooks remove`

Remove tk git hooks

tk hooks remove

`tk doctor`

Check installation health and fix issues

tk doctor [OPTIONS]

Options:

Option	Description
`--fix`	Automatically fix detected issues

`tk validate`

Validate issue database integrity

tk validate

`tk lint`

Lint all ticket files (validate frontmatter syntax)

tk lint [OPTIONS]

Options:

Option	Description
`--fix`	Automatically fix linting issues

`tk rules`

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

tk rules [OPTIONS]

Options:

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

`tk serve`

Start a local HTTP server with a kanban board view

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

tk cache [SUBCOMMAND]

`tk cache info`

Show cache statistics and status

tk cache info

`tk cache clear`

Delete all cached data

tk cache clear

`tk cache rebuild`

Force rebuild the cache

tk cache rebuild

Git Commands

`tk worktree`

Manage git worktrees with shared tickets

tk worktree [SUBCOMMAND]

`tk worktree ready`

Create worktrees for all ready issues

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)

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

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

tk worktree list

`tk worktree queue`

Show merge queue status

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

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

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

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

tk version

`tk hello`

Interactive onboarding and preferences setup

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

​Core Commands

​tk init

​tk create

​tk show

​tk list

​tk update

​tk close

​tk delete

​tk dep

​tk dep add

​tk dep remove

​tk dep tree

​tk dep list

​tk dep cycles

​tk edit

​tk board

​Workflow Commands

​tk claim

​tk resolve

​tk start

​tk ready

​AI & Analytics Commands

​tk triage

​tk next

​tk priority

​tk plan

​tk stacks

​tk stacks list

​tk stacks show

​tk stacks create

​tk stacks validate

​tk stacks merge

​tk stacks worktree

tk stacks worktree create

tk stacks worktree list

tk stacks worktree remove

​tk insights

​tk stats

​tk prime

​tk graph

​tk standup

​Search Commands

​tk search

​tk similar

​tk duplicates

​tk grep

​Integration Commands

​tk linear

​tk linear sync

​tk linear status

​tk linear teams

​tk github

​tk github sync

​tk github status

​tk claude

​tk claude sync

​tk claude status

​tk trello

​tk trello sync

​tk trello status

​tk trello boards

​tk trello lists

​Admin Commands

​tk config

​tk config get

​tk config set

​tk config list

​tk config unset

​tk setup

​tk setup claude

​tk hooks

​tk hooks install

​tk hooks check

​tk hooks remove

​tk doctor

​tk validate

​tk lint

​tk rules

​tk serve

​tk cache

Core Commands

`tk init`

`tk create`

`tk show`

`tk list`

`tk update`

`tk close`

`tk delete`

`tk dep`

`tk dep add`

`tk dep remove`

`tk dep tree`

`tk dep list`

`tk dep cycles`

`tk edit`

`tk board`

Workflow Commands

`tk claim`

`tk resolve`

`tk start`

`tk ready`

AI & Analytics Commands

`tk triage`

`tk next`

`tk priority`

`tk plan`

`tk stacks`

`tk stacks list`

`tk stacks show`

`tk stacks create`

`tk stacks validate`

`tk stacks merge`

`tk stacks worktree`

`tk stacks worktree create`

`tk stacks worktree list`

`tk stacks worktree remove`

`tk insights`

`tk stats`

`tk prime`

`tk graph`

`tk standup`

Search Commands

`tk search`

`tk similar`

`tk duplicates`

`tk grep`

Integration Commands

`tk linear`

`tk linear sync`

`tk linear status`

`tk linear teams`

`tk github`

`tk github sync`

`tk github status`

`tk claude`

`tk claude sync`

`tk claude status`

`tk trello`

`tk trello sync`

`tk trello status`

`tk trello boards`

`tk trello lists`

Admin Commands

`tk config`

`tk config get`

`tk config set`

`tk config list`

`tk config unset`

`tk setup`

`tk setup claude`

`tk hooks`

`tk hooks install`

`tk hooks check`

`tk hooks remove`

`tk doctor`

`tk validate`

`tk lint`

`tk rules`

`tk serve`

`tk cache`