TickTick CLI v1

A TypeScript CLI wrapper for the TickTick Open API documented at:

• https://developer.ticktick.com/
• https://developer.ticktick.com/docs#/openapi

v1 covers the documented OAuth flow plus every documented task and project endpoint.

The CLI is available as both ticktick and the short alias tt.

What it covers

• OAuth authorization code flow
• OAuth authorize URL generation
• Daily commands for today, overdue, and next
• Get, create, update, complete, delete, move, list-completed, and filter task endpoints
• List, get, create, update, delete, and get-data project endpoints
• Raw authenticated request passthrough
• Local config storage for client credentials and access tokens
• ticktick and dida365 service profiles, with manual base URL overrides when needed

Install

Requires Node.js 18+.

Install from the local repo:

npm install
npm run build

Run locally with:

node dist/bin.js --help

Or install the built CLI globally from this directory:

npm install -g .
ticktick --help
tt --help

Once published to npm, install it with:

npm install -g ticktick-cli
ticktick --help
tt --help

All command examples below use ticktick, but tt works the same way.

Configure

The CLI reads config in this order:

1. Command flags
2. Environment variables
3. Local config file
4. Built-in defaults

Useful environment variables:

TICKTICK_SERVICE=ticktick
TICKTICK_CLIENT_ID=...
TICKTICK_CLIENT_SECRET=...
TICKTICK_REDIRECT_URI=http://127.0.0.1:18463/callback
TICKTICK_SCOPES="tasks:read tasks:write"
TICKTICK_ACCESS_TOKEN=...
TICKTICK_API_BASE_URL=https://api.ticktick.com
TICKTICK_AUTH_BASE_URL=https://ticktick.com
TICKTICK_CONFIG_FILE=/custom/path/config.json

Default local redirect URI:

http://127.0.0.1:18463/callback

You can also persist config values:

ticktick config set clientId YOUR_CLIENT_ID
ticktick config set clientSecret YOUR_CLIENT_SECRET
ticktick config set redirectUri http://127.0.0.1:18463/callback
ticktick config show

Auth

Interactive login:

ticktick auth login

Successful auth stores the token in your local config file and masks secrets in the terminal output by default.

If you already have an authorization code:

ticktick auth exchange YOUR_CODE

Print the authorize URL without starting the callback server:

ticktick auth url

Check current auth state:

ticktick auth status

If you need the raw token values in the terminal, add --show-secrets to auth login, auth exchange, or auth status.

Clear the stored access token:

ticktick auth logout

Examples

Daily task views:

ticktick today
tt today
ticktick overdue
ticktick next
ticktick task today --json

today includes both overdue tasks and tasks due today, with overdue shown first.

List projects:

ticktick project list

Get project details:

ticktick project get 6226ff9877acee87727f6bca
ticktick project data 6226ff9877acee87727f6bca

Create a project:

ticktick project create --name "Inbox" --color "#F18181" --view-mode list --kind TASK

Create a task:

ticktick task create --project-id 6226ff9877acee87727f6bca --title "Ship CLI"

Update a task:

ticktick task update 63b7bebb91c0a5474805fcd4 --project-id 6226ff9877acee87727f6bca --priority 3

Move one task:

ticktick task move \
  --from-project-id 69a850ef1c20d2030e148fdd \
  --to-project-id 69a850f41c20d2030e148fdf \
  --task-id 69a850f8b9061f374d54a046

Filter tasks using JSON:

ticktick task filter --json '{
  "projectIds": ["69a850f41c20d2030e148fdf"],
  "startDate": "2026-03-01T00:58:20.000+0000",
  "endDate": "2026-03-06T10:58:20.000+0000",
  "priority": [0],
  "tag": ["urgent"],
  "status": [0]
}'

Move multiple tasks from a file:

ticktick task move --json-file ./moves.json

Pipe JSON into a command:

echo '{"name":"Planning","kind":"TASK"}' | ticktick project create

Send a raw authenticated request:

ticktick request GET /open/v1/project

Send a raw request to a full URL without bearer auth:

ticktick request POST https://httpbin.org/post --no-auth --json '{"hello":"world"}'

Development

Build the CLI:

npm run build

Notes

• The docs currently show api.ticktick.com for most endpoints, but api.dida365.com in the examples for task/move, task/completed, and task/filter. This CLI defaults to the selected service profile and lets you override base URLs explicitly if your account needs something different.
• The CLI writes config to a local JSON file under the OS-specific app config directory unless --config-file or TICKTICK_CONFIG_FILE is set.
• Access tokens and client secrets are stored as plain text in that config file. That keeps the wrapper simple, but it is not a secure keychain integration.