Skip to main content
Complete reference for all tk commands with all options.
Use tk help <command> to get detailed help for any command.

Core Commands

tk init

Initialize ticket tracking in a directory.
tk init [OPTIONS]
Options:
OptionDescription
-p, --prefix <PREFIX>Custom prefix for issue IDs (default: tk)
Creates a .tickets/ directory for storing issues.

tk create

Create a new issue.
tk create <TITLE> [OPTIONS]
Options:
OptionDescription
-t, --issue-type <TYPE>Issue type: task, feature, bug, epic, spike, chore (default: task)
-p, --priority <LEVEL>Priority: 0 (critical) to 4 (lowest) (default: 2)
-D, --description <TEXT>Issue description/body
-d, --deps <IDS>Comma-separated blocking dependencies
--parent <ID>Parent issue ID (for epics)
-l, --labels <LABELS>Comma-separated labels
-c, --close <REASON>Create as already closed (for post-hoc tracking)
Examples:
# Simple task
tk create "Fix login bug" -t bug -p 0

# Feature with description
tk create "Add dark mode" -t feature -d "Support system preference detection"

# Task with dependencies
tk create "Deploy to production" --deps tk-abc123,tk-def456

# Epic with labels
tk create "User authentication" -t epic -l backend,security

tk show

Show issue details.
tk show <ID>
Displays full issue details including:
  • Issue metadata (status, priority, type, labels)
  • Dependencies and what this issue blocks
  • Stack context if the issue is part of a linear dependency chain
  • Navigation hints to adjacent stack issues

tk list

List issues with optional filters.
tk list [OPTIONS]
Options:
OptionDescription
-s, --status <STATUS>Filter by status
-t, --issue-type <TYPE>Filter by type
-p, --priority <LEVEL>Filter by priority (max level to show)
--allInclude closed/tombstone issues
--sparseShow only sparse issues (need more context, fewer than 25 tokens)
--denseShow only dense issues (may need splitting, over 2000 tokens)
Examples:
# All open issues
tk list

# Only bugs
tk list -t bug

# High priority only (P0-P1)
tk list -p 1

# In-progress issues
tk list -s in_progress

# Issues needing more context
tk list --sparse

tk update

Update an issue.
tk update <ID> [OPTIONS]
Options:
OptionDescription
-s, --status <STATUS>New status
-p, --priority <LEVEL>New priority
-a, --assignee <ASSIGNEE>New assignee
--add-labels <LABELS>Add labels (comma-separated)
Example:
tk update tk-abc123 -s in_progress -p 0
tk update tk-abc123 -a john --add-labels urgent

tk close

Close an issue.
tk close <ID> [OPTIONS]
Options:
OptionDescription
-r, --reason <REASON>Close reason
Example:
tk close tk-abc123 -r "Completed in PR #42"

Workflow Commands

tk claim

Mark an issue as in_progress and show unblocked work.
tk claim <ID> [OPTIONS]
Options:
OptionDescription
-n, --note <NOTE>Add a note when claiming
Alias: tk start

tk resolve

Close an issue and show what work is now unblocked.
tk resolve <ID> [OPTIONS]
Options:
OptionDescription
-n, --note <NOTE>Resolution note

tk ready

Show issues ready to work on (no open blockers).
tk ready [OPTIONS]
Options:
OptionDescription
-l, --limit <N>Maximum results (default: 20)

Dependency Commands

tk dep add

Add a dependency (blocked depends on blocker).
tk dep add <BLOCKED> <BLOCKER>
Example:
# tk-abc123 is blocked by tk-def456
tk dep add tk-abc123 tk-def456

tk dep remove

Remove a dependency.
tk dep remove <BLOCKED> <BLOCKER>

tk dep tree

Show dependency tree for an issue.
tk dep tree <ID>

tk dep list

List dependencies or dependents of an issue.
tk dep list <ID>

tk dep cycles

Detect dependency cycles in the graph.
tk dep cycles

Search Commands

Search issues using BM25 text search.
tk search <QUERY> [OPTIONS]
Options:
OptionDescription
-l, --limit <N>Maximum results (default: 10)
Example:
tk search "authentication login"

tk similar

Find issues similar to a given issue.
tk similar <ID> [OPTIONS]
Options:
OptionDescription
-l, --limit <N>Maximum results (default: 5)

tk duplicates

Find and manage duplicate issues.
tk duplicates [OPTIONS]
Options:
OptionDescription
--threshold <N>Similarity threshold (default: 5.0)
--auto-mergeAutomatically merge all duplicate groups
--dry-runShow what would be merged without merging
--keep-newestKeep newest issue when merging (default: oldest)

tk grep

Grep issue content using regex (powered by ripgrep).
tk grep <PATTERN> [OPTIONS]
Options:
OptionDescription
-i, --ignore-caseCase insensitive search
--files-onlyShow only issue IDs
--absoluteShow absolute paths instead of relative
Example:
tk grep "TODO|FIXME" -i

AI Commands

tk prime

Output AI-optimized workflow context. Designed for Claude Code SessionStart hooks.
tk prime [OPTIONS]
Options:
OptionDescription
--fullForce full output (ignore MCP detection)
--mcpForce minimal MCP mode
--stealthSkip git operations

tk triage

Unified AI triage: recommendations, quick wins, blockers, stacks, health score.
tk triage
JSON output includes:
  • quick_ref — Summary stats (including stack count)
  • recommendations — Ranked issues with stack context
  • quick_wins — Easy wins to knock out
  • blockers_to_clear — Issues blocking the most work
  • stacks — Detected linear dependency chains
  • project_health — Health metrics including stack analytics

tk priority

Get PageRank-based priority recommendations.
tk priority

tk next

Get single top recommendation (minimal output).
tk next

tk plan

Get parallel execution plan using topological sort.
tk plan

tk stacks

Detect and manage linear dependency stacks (Graphite-style).
tk stacks [SUBCOMMAND]
A stack is a linear chain of issues where each depends on exactly one predecessor. Stacks are useful for:
  • Incremental feature development (layer-by-layer)
  • Coordinated code reviews (review as a unit)
  • Merge queue optimization (validate tip, merge all)
Subcommands:
SubcommandDescription
list (default)List all detected stacks
show <stack-id>Show detailed info about a specific stack
validate <stack-id>Check if a stack is ready for merging
merge <stack-id>Fast-forward merge all branches in a stack
worktree <stack-id>Create git worktree for stack development

tk stacks list

List all detected stacks (default when no subcommand given).
tk stacks
tk stacks list
tk stacks ls
Options:
OptionDescription
--allInclude stacks with closed issues
--readyShow only stacks where all issues are ready
--no-cacheSkip cache and compute fresh
Sample output:
2 stack(s) detected:

○ stack-1 [3 issues] tk-abc → tk-def → tk-ghi
  Chain: tk-abc → tk-def → tk-ghi
○ stack-2 [2 issues] tk-jkl → tk-mno
  Chain: tk-jkl → tk-mno

tk stacks show

Show detailed information about a specific stack.
tk stacks show <stack-id>
tk stacks show tk-abc123  # By root issue ID
Sample output:
Stack: stack-1

  Status: ready
  Depth:  3 issues
  Root:   tk-abc
  Tip:    tk-ghi

  Chain:
      (root) tk-abc - Auth: Base service setup
             tk-def - Auth: Login endpoint
      (tip)  tk-ghi - Auth: Frontend integration

tk stacks validate

Check if a stack is ready for merging. Returns exit code 0 for valid, 1 for invalid.
tk stacks validate <stack-id>
Validation checks:
  • All non-tip issues in the stack are closed
  • Tip issue has no external blockers (outside the stack)
  • All issues in the stack exist
Sample output (valid):
✓ Stack Validation: stack-1

  PASS Stack is ready for merge!
  All 3 issues are in valid state for merging.

  Issues:
    ✓ tk-abc [closed] (root) - Auth: Base service setup
    ✓ tk-def [closed] - Auth: Login endpoint
    ✓ tk-ghi [open] (tip) - Auth: Frontend integration
Sample output (invalid):
✗ Stack Validation: stack-1

  FAIL Stack is NOT ready for merge.

  Issues:
    ✓ tk-abc [closed] (root) - Auth: Base service setup
    ✗ tk-def [open] - Auth: Login endpoint
      → expected closed but is open
    ✓ tk-ghi [open] (tip) - Auth: Frontend integration

  Fix To fix:
    - Close these issues: tk-def

tk stacks merge

Fast-forward merge all branches in a validated stack.
tk stacks merge <stack-id> [OPTIONS]
Options:
OptionDescription
--dry-runPreview merge without making changes
--yesSkip confirmation prompt
--no-cacheSkip cache and compute fresh
Process:
  1. Validates the stack (reuses tk stacks validate)
  2. Merges branches in order (root to tip)
  3. Closes all issues in the stack
  4. Shows merge results
This command modifies git branches. Use --dry-run first to preview changes.

tk stacks worktree

Create a git worktree for working on a stack.
tk stacks worktree <stack-id> [OPTIONS]
tk stacks worktree --list
tk stacks worktree --remove <stack-id>
Options:
OptionDescription
--listList existing stack worktrees
--removeRemove a stack worktree
--no-cacheSkip cache and compute fresh
Features:
  • Creates worktree with the stack’s tip branch
  • Symlinks .tickets/ directory for shared issue tracking
  • Places worktree in configured location (default: ~/.tickets/worktrees/<repo>/<stack-id>)
Stack info is also shown in tk triage, tk show, and tk stats output.

tk insights

Get graph analytics: PageRank, betweenness centrality, critical path.
tk insights

tk stats

Show statistics about the issue database.
tk stats
Displays counts for total, open, in_progress, closed, and ready issues, plus stack count if any stacks are detected.

Export & Maintenance

tk export

Export issues to JSONL format.
tk export [OPTIONS]
Options:
OptionDescription
-o, --output <FILE>Output file (default: stdout)
-s, --status <STATUS>Filter by status
--include-tombstonesInclude tombstone issues

tk compact

Compact closed issues into CHANGELOG.md.
tk compact [OPTIONS]
Options:
OptionDescription
-o, --output <FILE>Output file (default: CHANGELOG.md)
-v, --version <VERSION>Version tag for this release (e.g., “1.0.0”)
--appendAppend to existing changelog instead of overwriting
--keepKeep ticket files (don’t delete after compacting)
--dry-runShow what would be done without making changes

tk orphan

Find open issues mentioned in git history that may be orphaned.
tk orphan [OPTIONS]
Options:
OptionDescription
--closeAuto-close orphaned issues that are still open

Git Worktree Commands

tk worktree

Manage git worktrees with shared tickets.
tk worktree <COMMAND>
Subcommands:
CommandDescription
readyCreate worktrees for all ready issues
syncSync all worktrees with trunk (rebase onto master/main)
mergeMerge worktrees back to trunk via merge queue
listList all worktrees with status
queueShow merge queue status
removeRemove a worktree
pruneClean up worktrees for closed issues

Sync Commands

tk github sync

Sync issues with GitHub Issues.
tk github sync [OPTIONS]
Options:
OptionDescription
--pullPull issues from GitHub
--pushPush issues to GitHub
--dry-runPreview without making changes
--create-onlyOnly create new issues, don’t update existing
--update-refsUpdate external_ref after creating GitHub issues
--state <STATE>Issue state to sync: open, closed, all (default: all)
Example:
tk github sync --pull --state open
tk github sync --push --dry-run

tk github status

Show GitHub sync status.
tk github status

tk claude sync

Sync issues with Claude Code tasks (bidirectional).
tk claude sync [OPTIONS]
Options:
OptionDescription
--pullPull tasks from Claude to tk (one-way)
--pushPush issues from tk to Claude (one-way)
--dry-runPreview changes without syncing
--state <STATE>Only sync issues in this state: open, closed, all (default: open)
Examples:
# Bidirectional sync (default)
tk claude sync

# Preview what would change
tk claude sync --dry-run

# Only push local issues to Claude
tk claude sync --push

# Only pull Claude tasks to local
tk claude sync --pull
Auto-detects current Claude Code session from ~/.claude/tasks/. Maintains claude_task_id field for sync tracking.

tk claude status

Show Claude Code sync status and current session info.
tk claude status
Shows:
  • Current Claude Code session (if found)
  • Number of tk issues with Claude task IDs
  • Sync state summary

tk linear sync

Sync issues with Linear.
tk linear sync [OPTIONS]
Options:
OptionDescription
--pullPull issues from Linear
--pushPush issues to Linear
--dry-runPreview without making changes
--create-onlyOnly create new issues, don’t update existing
--update-refsUpdate external_ref after creating Linear issues
--state <STATE>Issue state to sync: open, closed, all (default: all)

tk linear status

Show Linear sync status.
tk linear status

tk linear teams

List available Linear teams.
tk linear teams

Admin Commands

tk config

Manage configuration.
tk config get <KEY>
tk config set <KEY> <VALUE>
tk config list
tk config unset <KEY>
Example:
tk config set github.token ghp_xxxxx
tk config set linear.api_key lin_api_xxxxx
tk config list

tk setup claude

Set up Claude Code integration hooks.
tk setup claude [OPTIONS]
Options:
OptionDescription
--globalInstall globally instead of project-local
--removeRemove hooks instead of installing

tk hooks

Manage git hooks.
tk hooks <COMMAND>
Subcommands:
CommandDescription
installInstall git hooks (use --force to overwrite)
checkCheck if hooks are installed
removeRemove installed hooks

tk doctor

Check installation health.
tk doctor [OPTIONS]
Options:
OptionDescription
--fixAuto-fix issues where possible
Checks for:
  • Valid .tickets/ directory
  • Issue parse errors
  • Orphaned dependencies
  • Self-referential deps
  • Sparse/dense issues
  • Git hooks status
  • Claude integration status

tk validate

Validate issue database integrity.
tk validate

tk lint

Lint all ticket files for syntax errors.
tk lint [OPTIONS]
Options:
OptionDescription
--fixAttempt to fix issues automatically

tk onboard

Display onboarding snippet for AGENTS.md.
tk onboard

tk demo

Create tutorial-style demo issues that teach tk interactively.
tk demo [OPTIONS]
Options:
OptionDescription
--clearClear existing demo issues first
What it creates: The demo creates 7 tutorial issues that guide you through tk’s core features:
  1. tk-001 — Learn tk list to see all issues
  2. tk-002 — Learn tk ready to find unblocked work
  3. tk-003 — Learn tk claim to start working (P0 priority, start here!)
  4. tk-004 — Learn tk close to complete work (blocked by tk-003)
  5. tk-005 — Learn tk priority for PageRank recommendations
  6. tk-006 — Learn tk triage mega-command (blocked until basics learned)
  7. tk-007 — Learn tk create to add new issues
The dependency graph creates a natural learning progression — complete tk-003 first to unblock tk-004. Example:
# Create demo issues
tk demo

# Output:
# 🎭 Creating demo issues...
#
#   ✓ tk-001 [task] P1 - Run 'tk list' to see all issues
#   ✓ tk-002 [task] P1 - Try 'tk ready' to find unblocked work
#   ✓ tk-003 [task] P0 - Start work with 'tk claim tk-003'
#   ✓ tk-004 [task] P1 - Complete work with 'tk close'
#   ✓ tk-005 [task] P2 - Get recommendations with 'tk priority'
#   ✓ tk-006 [feature] P2 - Use 'tk triage' for full analysis
#   ✓ tk-007 [task] P3 - Create issues with 'tk create'
#
# Follow the tutorial:
#   tk list - See all issues (start here!)
#   tk ready - Find work ready to start
#   tk claim tk-003 - Start working on an issue
#   tk close tk-003 - Complete an issue
#   tk priority - Get PageRank recommendations
#   tk triage - Full AI triage report
#   tk create "My task" - Create a new issue

# Clean up demo issues
tk demo --clear
Each demo issue contains instructions in its description. Use tk show tk-001 to read the full tutorial for any step.

tk cache

Manage analytics cache for faster graph operations.
tk cache <COMMAND>
Subcommands:
CommandDescription
infoShow cache statistics (hits, size, last sync)
clearDelete all cached data
rebuildForce full cache rebuild
Examples:
# Check cache status
tk cache info

# Clear cache (rebuilds automatically on next command)
tk cache clear

# Force rebuild
tk cache rebuild
The cache automatically invalidates when ticket files change. Manual cache management is rarely needed.
Performance:
  • Cache hits: <10ms (instant)
  • Cache rebuilds: <20ms (imperceptible)
  • Automatic invalidation via filesystem mtime

Global Options

These options are available on all commands:
OptionDescription
-C, --dir <DIR>Working directory (default: current)
-f, --format <FORMAT>Output format: compact, table, or json (default: compact)
--no-cacheSkip cache and compute fresh results (analytics commands only)
-h, --helpPrint help
-V, --versionPrint version
The --no-cache flag bypasses the analytics cache on commands like triage, ready, priority, plan, next, and insights. Use this when you want to force fresh computation or debug cache issues.

Output Format Support

Not all commands support the -f, --format flag. Here’s the complete matrix:

Commands Supporting All 3 Formats

Full format support (Compact, Table, JSON):
  • show - Issue details
  • list - Issue listing
  • ready - Ready issues
  • priority - Priority recommendations
  • plan - Execution plan
  • stacks - Linear dependency stacks
  • insights - Graph analytics
  • triage - AI triage
  • next - Top recommendation
  • stats - Statistics
  • search - Text search
  • similar - Similar issues

Commands with Partial Format Support

⚠️ Partial support:
  • create - Compact and JSON only (no Table)

Commands with Text-Only Output

No format support (text output only):
  • init, update, close
  • claim, resolve, prime
  • validate, lint
  • export (JSONL format)
  • dep subcommands (ASCII art trees)
  • duplicates, grep
  • compact, orphan, migrate-beads
  • doctor, demo, onboard
  • All config, setup, hooks commands
For automation, use JSON format: tk -f json list

Testing & Validation

Comprehensive Test Suite

tk v0.0.1 includes extensive testing:
  • 82 unit tests - Core functionality
  • 50+ integration tests - End-to-end CLI
  • 50+ edge case tests - Security, Unicode, boundaries
  • 20+ format tests - All output formats validated

Security Testing

All path traversal and injection attacks tested:
  • ✅ Path traversal blocked (../../../etc/passwd)
  • ✅ Command injection safe
  • ✅ YAML injection safe
  • ✅ Unicode handling correct
  • ✅ Special characters handled

Run Tests Yourself

# Run all tests
cargo test

# Run specific test suite
cargo test --lib              # Unit tests
cargo test --test '*'         # Integration tests
cargo test cli::helpers       # Helper tests

Known Limitations

These limitations are documented for the alpha release:

1. No File Locking

Concurrent writes may corrupt issue files. Tracked in tk-czffka. Workaround: Avoid concurrent operations on same repository.

2. Limited Input Validation

Some validation gaps:
  • Priority not validated (0-4 recommended but any u8 accepted)
  • Invalid issue types default to “task” silently
  • Circular dependencies not prevented at creation
Workaround: Use tk validate and tk lint to check.

Flag Consistency

All flags follow consistent naming conventions:
Flag TypeShortLongCommands
Limit-l--limitready, search, similar
Note-n--noteclaim, resolve
Priority-p--prioritycreate, update, list
Status-s--statusupdate, list, export
Type-t--issue-typecreate, list
Output-o--outputexport, compact
Format-f--formatGlobal (all commands)
Directory-C--dirGlobal (all commands)

Performance

All analytics commands (triage, ready, priority, plan, next, insights, stats) use an intelligent caching system for instant performance:

Cache Behavior

Automatic Invalidation

Cache automatically rebuilds when ticket files change (create, delete, modify)

Instant Hits

Cached results return in <10ms - imperceptibly fast

Fast Rebuilds

Cache rebuilds complete in <20ms even on large repos

Transparent

Caching is invisible - you get fresh results when needed

Performance Metrics

Typical performance on a repository with 68 issues:
CommandCachedRebuildNo Cache
tk ready7ms10ms83ms
tk triage14ms15ms850ms
tk plan7ms10ms820ms
tk priority7ms10ms890ms
tk stats7ms10ms85ms
The cache uses filesystem mtime for instant freshness checks (2 stat calls) instead of computing SHA-256 hashes of all files. This makes cache validation essentially free.

Cache Management

# Check cache status
tk cache info

# Force rebuild if needed
tk cache rebuild

# Or bypass cache for debugging
tk triage --no-cache
Cache invalidation triggers on file creation/deletion, not just content changes. This is by design - most workflows (creating issues, resolving issues) naturally invalidate the cache at the right time.

Best Practices

Issue Creation

# Good: Explicit type and priority
tk create "Add feature" -t feature -p 1

# Avoid: Letting defaults apply
tk create "Something"  # Creates task with P2

Dependency Management

# Always validate after adding deps
tk dep add tk-123 tk-456
tk validate  # Check for cycles

# Use dep tree to visualize
tk dep tree tk-123

Working with Large Repos

# Use filters to reduce output
tk list -p 1 -t bug

# Use ready instead of list for next actions
tk ready -n 5

# Use triage for AI recommendations
tk triage

Automation & Scripts

# Always use JSON format for parsing
tk -f json list | jq '.[] | .id'

# Check exit codes
if tk validate; then
  echo "All valid"
fi

# Use quotes for titles with spaces
tk create "Multi word title"

Getting Help

Command-Specific Help

tk help create
tk create --help

Full Command List

tk help

Version Information

tk --version
tk version

See Also