taskcli

Local-first project/issue tracker for the terminal — Linear/Jira-lite, backed by SQLite.

Work is organized as projects that own issues with keys like ENG-12. Issues have status, priority, labels, due dates, a description, and a chronological comment work log.

Install

go install github.com/timjonez/task-cli/cmd/taskcli@latest
# or from a checkout:
make install

Requires Go 1.24+.

Data location

Default database:

$XDG_DATA_HOME/taskcli/taskcli.db
# or ~/.local/share/taskcli/taskcli.db

Override with --db /path/to.db or TASKCLI_DB.

taskcli db path

Quick start

taskcli project create ENG Engineering
taskcli issue create ENG "Wire up OAuth callback" --priority high --due today -l backend
# shorthand:
taskcli create ENG "Wire up OAuth callback" --priority high --due today -l backend

taskcli list ENG
taskcli start ENG-1
taskcli comment add ENG-1 -d "Need PKCE; checked provider docs"
taskcli show ENG-1
taskcli done ENG-1
taskcli list ENG --all

Concepts

Concept	Meaning
Project	Container of work with a short immutable KEY (ENG, HOME)
Issue	Unit of work, public id KEY-N (ENG-12)
Status	backlog → todo → in_progress → done / cancelled
Label	Freeform tag (many-to-many)
Comment	Chronological work log on an issue (not a replacement for description)

Description = stable problem statement. Comments = what you learned while working it.

Commands

Projects

taskcli project create <KEY> <name> [-d description]
taskcli project list [--all]
taskcli project show <KEY>
taskcli project rename <KEY> <new-name>
taskcli project archive|unarchive <KEY>
taskcli project rm <KEY> [--force]

Issues

taskcli issue create <KEY> <title> [--status ...] [--priority ...] [--due ...] [-l label] [-d desc]
taskcli issue list [KEY] [--status open|all|...] [--priority ...] [-l label] [--overdue] [--due today|week] [--all]
taskcli issue show <ISSUE> [--no-comments]
taskcli issue edit <ISSUE> [--title ...] [-d ...] [--priority ...] [--due ...|none] [--add-label ...] [--rm-label ...]
taskcli issue status <ISSUE> <status>
taskcli issue start|done|cancel|reopen <ISSUE>
taskcli issue rm <ISSUE>

Top-level aliases: create, list, show, start, done, cancel, reopen.

Comments

taskcli comment add <ISSUE> -d "body"
taskcli comment add <ISSUE> -F notes.md
taskcli comment list <ISSUE>
taskcli comment edit <id> -d "body"
taskcli comment rm <id>

Labels

taskcli label list
taskcli label rm <name> [--force]

Meta

taskcli version
taskcli db path
taskcli completion bash|zsh|fish

JSON mode

Global --json emits machine-readable JSON on stdout. Human tables are the default.

• Lists → JSON arrays; show/create/update → single objects
• due_on is always YYYY-MM-DD or null (never relative text)
• Empty lists are [], not omitted nulls
• Errors → JSON on stderr: {"error":"...","code":"not_found|conflict|invalid|not_empty|archived|error"} with non-zero exit
• Deletes → {"deleted":"ENG-1"} (or project key / label name / #id for comments)

taskcli --json list ENG
taskcli --json create ENG "Ship OAuth" --priority high -l backend
taskcli --json show ENG-1
taskcli --json start ENG-1

Example create response:

{
  "key": "ENG-1",
  "project_key": "ENG",
  "number": 1,
  "title": "Ship OAuth",
  "description": "",
  "status": "todo",
  "priority": "high",
  "due_on": null,
  "completed_at": null,
  "labels": ["backend"],
  "created_at": "2026-08-08T19:00:00Z",
  "updated_at": "2026-08-08T19:00:00Z"
}

Due dates

--due accepts:

• YYYY-MM-DD
• today / tomorrow
• +Nd (e.g. +3d)

List filters: --overdue, --due today, --due week.

Development

make test
make build   # → bin/taskcli

Agent skill

An agent skill (tool-agnostic) lives at:

skills/taskcli/SKILL.md

It teaches coding agents how to drive taskcli (model, rules, commands). Copy or symlink it into your agent’s skills directory as needed (e.g. ~/.grok/skills/, ~/.claude/skills/, .agents/skills/).

Non-goals (v1)

No sync, multi-user, assignees, sprints/cycles, estimates, sub-issues, or import from Linear/Jira.