Agent-first Todoist CLI. HATEOAS JSON responses, agent-secrets auth, ref resolution by name/URL/ID.
Todoist ships an official CLI (td) — it's excellent for humans at a terminal. Colored output, interactive prompts, shell completions, markdown rendering.
This CLI is for agents. Every response is structured JSON with next_actions hints (HATEOAS), so an LLM knows what it can do next without reading a man page. Auth flows through agent-secrets with TTL-scoped leases. No chalk, no spinners, no prompts — just parseable output.
td (Doist/todoist-cli) |
todoist-cli (this) |
|
|---|---|---|
| Audience | Humans in a terminal | AI agents, gateway daemons, tool calls |
| Output | Colored text, markdown | HATEOAS JSON with next_actions |
| Auth | OAuth PKCE browser flow | TODOIST_API_TOKEN env var or agent-secrets lease |
| Ref resolution | ✅ Name, URL, id:, fuzzy |
✅ Same (ported from Doist CLI, MIT) |
| Comments | ✅ Full CRUD | ✅ Full CRUD |
| Reminders | ✅ via REST API | ✅ via Sync API |
| Activity | ✅ | ✅ |
| Shell completions | ✅ bash/zsh/fish | ❌ (agents don't tab-complete) |
| Skill installer | ✅ td skill install claude-code |
❌ (agents read the JSON help output) |
| Workspaces | ✅ | ❌ (single-user) |
| Dependencies | Commander, chalk, ora, tabtab | Just @doist/todoist-api-typescript |
| Runtime | Node.js | Bun |
Use the official CLI if you're a human typing in a terminal.
Use this CLI if you're an agent calling tools in a pipeline.
Ref resolution pattern credit: Doist/todoist-cli src/lib/refs.ts (MIT license).
The official CLI also ships agent skills via td skill install claude-code — but those skills describe td's human-oriented output. This repo ships a skill (skills/todoist/SKILL.md) that describes the HATEOAS JSON contract agents actually parse.
One-liner (downloads prebuilt binary from GitHub Releases):
curl -fsSL https://raw.githubusercontent.com/joelhooks/todoist-cli/main/install.sh | bashDetects OS/arch, installs to /usr/local/bin. Override with TODOIST_CLI_DIR:
curl -fsSL https://raw.githubusercontent.com/joelhooks/todoist-cli/main/install.sh | TODOIST_CLI_DIR=~/.local/bin bashAgent skill (for Claude Code, pi, or any npx skills compatible agent):
npx skills add joelhooks/todoist-cli --skill todoist --yes --globalFrom source (requires Bun):
git clone https://github.com/joelhooks/todoist-cli.git
cd todoist-cli
bun install
bun linkBuild standalone binary:
bun build --compile src/cli.ts --outfile todoist-cli# Option 1: env var
export TODOIST_API_TOKEN="your-token"
# Option 2: agent-secrets (auto-leased with TTL)
secrets add todoist_api_token
# Get your token: https://app.todoist.com/app/settings/integrations/developerAll <ref> args accept: task name, Todoist URL, id:xxx, or raw ID.
# Tasks
todoist-cli today # due today + overdue
todoist-cli inbox # inbox (needs triage)
todoist-cli search "deploy pipeline" # full-text search
todoist-cli list --project "Agent Work" # tasks in project (by name!)
todoist-cli list --filter "priority 1 & today" # Todoist filter query
todoist-cli show "Qdrant upsert" # task detail + comments
todoist-cli add "Ship the media pipeline" --due tomorrow --project "Agent Work" --priority 2
todoist-cli complete "Ship the media pipeline" # by name
todoist-cli update "Ship the media pipeline" --due "next monday"
todoist-cli move "Ship the media pipeline" --project "Joel's Tasks"
todoist-cli delete "Ship the media pipeline"
todoist-cli reopen <ref>
# Comments (critical for async agent conversations — ADR-0047)
todoist-cli comments "Qdrant upsert" # list comments on task
todoist-cli comment-add "Qdrant upsert" --content "Started implementation"
todoist-cli comment-update <commentId> --content "Updated note"
todoist-cli comment-delete <commentId>
# Reminders
todoist-cli reminders "Deploy pipeline" # list reminders
todoist-cli reminder-add "Deploy pipeline" --before 30m
todoist-cli reminder-add "Deploy pipeline" --at 2026-02-20T10:00
todoist-cli reminder-delete <reminderId>
# Activity
todoist-cli activity --since 2026-02-18 --event completed
todoist-cli activity --project "Agent Work" --limit 10
todoist-cli completed --since 2026-02-17 # completed tasks
# Organization
todoist-cli review # daily dashboard
todoist-cli projects # list all projects
todoist-cli sections --project "Agent Work" # sections by project name
todoist-cli labels
todoist-cli add-project "New Project" --color blue
todoist-cli add-section "Backlog" --project "Agent Work"Every response is JSON:
{
"ok": true,
"command": "todoist-cli complete",
"result": {
"completed": {
"id": "6g3VHV5HJGvJmPhw",
"content": "Ship the media pipeline",
"priority": 2
}
},
"next_actions": [
{ "command": "todoist-cli today", "description": "View remaining today tasks" }
]
}Errors:
{
"ok": false,
"error": "Ambiguous task \"deploy\". Matches:\n \"Deploy pipeline\" (id:abc)\n \"Deploy worker\" (id:def)"
}