ticktick-cli
Agent-native command-line interface for TickTick
Full API coverage · JSON-first · Built for AI agents and humans alike
I was frustrated that no proper TickTick CLI existed. The official API covers only tasks and projects, third-party SDKs are incomplete, MCP servers add unnecessary context overhead, and none of these approaches are designed for the way modern AI agents actually work. So I built ticktick-cli -- a CLI that covers 100% of TickTick's API surface (including the unofficial V2 endpoints), outputs structured JSON by default, and works equally well when invoked by a human or by Claude Code via Bash.
Why CLI, not MCP or SDK?
The emerging consensus from practitioners like Peter Steinberger and Armin Ronacher is clear: CLI-first, MCP only when necessary. AI coding agents (Claude Code, Codex, Cursor) already invoke tools via shell -- that's their native interface. Adding an MCP server is an extra process, an extra protocol, and extra context pollution that doesn't add value when a CLI already outputs structured JSON. Benchmarks show CLI achieves higher task completion at equivalent token cost. The Unix philosophy was accidentally designed for AI agents decades before they existed.
Highlights
- JSON output by default -- structured
{"ok": true, "data": [...]} responses, parseable by any agent or script
--human flag -- switch to rich terminal tables with a single flag- 100% API coverage -- tasks, subtasks, projects, folders, tags, kanban columns, habits, focus/pomodoro (including live timer), filters, templates, user profile
- Dual API support -- V1 (official OAuth 2.0) + V2 (unofficial session-based) for full feature access
- Focus timer control -- start, stop, log, and delete pomodoro sessions directly from CLI
- Multiple output formats -- JSON (default), CSV, YAML, or rich terminal tables (
--human)
- Natural language dates --
--due tomorrow, --start "next monday", --due "in 3 days"
- Agent-friendly design -- no interactive prompts,
--yes flags, --dry-run, deterministic exit codes (0/1/2)
- Field selection --
--fields id,title,priority to return only what you need
- Multiple profiles --
--profile work / --profile personal for separate accounts
- Security-first -- OAuth CSRF protection, encrypted credential storage (600 permissions), env var support for secrets
- Shell completions -- bash, zsh, fish auto-complete out of the box
- Retry with backoff -- automatic retries for transient API errors, V1 token auto-refresh
Table of Contents
Installation
From source (development)
git clone https://github.com/MakotoUwu/ticktick-cli.git
cd ticktick-cli
python -m venv .venv && source .venv/bin/activate
pip install -e .
pip
pip install ticktick-agent-cli
pipx (isolated install)
pipx install ticktick-agent-cli
The published package name is ticktick-agent-cli; the installed command remains ticktick.
Claude Code plugin
This repository now includes a marketplace-ready Claude Code plugin bundle under claude-plugin/ticktick-cli.
For local development and testing: