ticktick-cli

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
• Quick Start
• Commands
• Output Format
• Agent Integration
• Authentication
• Configuration
• Security
• Contributing
• License

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: