tkr

Task management CLI built with Bun and SQLite.

Install

# Requires Bun runtime
npm i -g @zakiego/tkr

Quick Start

tkr init                                    # Set up your first project
tkr issue create -t "Fix login bug" -p high # Create an issue
tkr issue list                              # List issues
tkr status                                  # Dashboard overview

Features

• Projects with prefixed issue IDs (e.g. WEB-1, API-42)
• Customizable workflow states — default: Backlog → Todo → In Progress → Done → Cancelled
• Priority levels — None, Low, Medium, High, Urgent
• Labels with colors for categorization
• Due dates with overdue tracking
• Comments on issues
• Activity log — auto-tracked state changes, priority updates, etc.
• Issue relations — blocks, blocked-by, relates-to, duplicate-of
• Dashboard (tkr status) and analytics (tkr stats)
• Export to JSON, CSV, or Markdown
• Import from JSON
• Reminders via macOS notifications (launchd)
• Shell completions for bash, zsh, and fish
• Rich colored table output + --json and --csv flags for scripting

Commands

tkr init                              # Guided first-time setup
tkr project create/list/use/delete    # Manage projects
tkr issue create                      # Create an issue
tkr issue list                        # List issues (filters: --state, --priority, --label, --overdue)
tkr issue view WEB-1                  # View issue details
tkr issue update WEB-1 --priority high
tkr issue move WEB-1 "In Progress"   # Quick state transition
tkr issue comment WEB-1 -m "note"    # Add a comment
tkr issue link WEB-1 blocks WEB-3    # Link issues
tkr issue activity WEB-1             # View activity log
tkr label create bug --color red      # Create a label
tkr state create "In Review" -t started  # Custom workflow state
tkr status                            # Dashboard overview
tkr stats                             # Analytics
tkr config set editor vim             # Configuration
tkr export --format md                # Export as Markdown
tkr remind add WEB-1 --before 1d     # Set a reminder
tkr completion zsh                    # Shell completions

Filtering & Sorting

tkr issue list --state todo --priority high --label bug
tkr issue list --overdue
tkr issue list --due-this-week
tkr issue list --sort priority
tkr issue list --all                  # Include Done/Cancelled

Output Formats

tkr issue list                # Colored table (default)
tkr issue list --json         # JSON for scripting
tkr issue list --csv          # CSV for spreadsheets

Shell Completions

# Bash
tkr completion bash >> ~/.bashrc

# Zsh
tkr completion zsh >> ~/.zshrc

# Fish
tkr completion fish > ~/.config/fish/completions/tkr.fish

Data

All data is stored locally in ~/.config/tkr/tkr.db (SQLite).

License

MIT