ticktick-cli

A command-line interface for the TickTick task management app, optimized for AI agents.

Installation

Requires Node.js 22.12+ (commander v15 is ESM-only and requires Node ≥22.12 for require(esm)):

npm install -g @crcatala/ticktick-cli

The package provides two equivalent commands: tt and ttcli. tt is used throughout this guide.

Requires Node.js 22.12+ and Bun:

git clone https://github.com/crcatala/ticktick-cli.git
cd ticktick-cli
bun install
bun run build
node dist/index.js --help

Quick Start

1. Authenticate

tt auth login

You'll be prompted for your TickTick username and password. If you have 2FA enabled, provide your TOTP code (automatic generation from a TOTP secret is not supported):

tt auth login --totp-code 123456

By default, your session token is stored securely in your system keyring. If you prefer plaintext storage (not recommended), use:

tt auth login --use-config

2. List Your Tasks

tt task list

3. Add a Task

tt task add "Buy groceries" --priority high --due tomorrow

Common Workflows

Daily Review

# See all active tasks
tt task list

# See tasks in a specific project
tt task list --project Work

# Mark a task as done (task titles are supported when unambiguous)
tt task done "Buy groceries"

Quick Task Entry

# Simple task
tt task add "Call mom"

# Task with all options
tt task add "Prepare presentation" \
  --project Work \
  --priority high \
  --due 2025-01-15 \
  --tag work \
  --tag urgent \
  --content "Q1 sales review slides"

Notes

# Create a dedicated note list
tt project add "Journal" --kind NOTE

# Add a note (the project must be a NOTE list)
tt note add "Daily reflection" --project Journal --content "What went well today"

# Convert between task and note (conversion clears task-only metadata)
tt task convert-to-note "Daily reflection"
tt note convert-to-task NOTE_ID

Project Management

# List all projects
tt project list

# Create a new project
tt project add "Home Renovation" --color "#FF5733"

# Show inbox ID
tt project inbox

Working with Tags

# List all tags
tt tag list

# Create a tag
tt tag add "work"

# Create a child tag
tt tag add "urgent" --parent "work"

# Rename a tag
tt tag rename "old-name" "new-name"

Data Export

# Export all data as JSON
tt sync --json > ticktick-backup.json

# Export just tasks
tt task list --json > tasks.json

Scripting / Automation

All commands support --json output for easy parsing:

# Get task IDs for scripting
tt task list --json | jq '.[].id'

# Check auth status in scripts
if tt auth status --json | jq -e '.authenticated' > /dev/null; then
  echo "Logged in"
fi

Command Reference

| Command | Description | |---------|-------------| | tt auth login | Log in to TickTick | | tt auth logout | Log out and clear credentials | | tt auth status | Show authentication status | | tt auth whoami | Alias for status | | tt task list | List active tasks | | tt task show ID_OR_TITLE | Show task details | | tt task add TITLE | Create a new task | | tt task edit ID_OR_TITLE | Edit an existing task | | tt task done ID_OR_TITLE | Mark task as complete | | tt task abandon ID_OR_TITLE | Mark task as abandoned | | tt task reopen ID_OR_TITLE | Reopen closed task | | tt task delete ID_OR_TITLE | Delete task | | tt task closed | List completed/abandoned tasks | | tt task subtask:add TASK PARENT | Make task a subtask | | tt task subtask:unset TASK | Remove from parent | | tt task convert-to-note ID_OR_TITLE | Convert a task to a note | | tt note add TITLE --project NAME_OR_ID | Create a note in a note list | | tt note convert-to-task ID | Convert a note to a task | | tt project list | List all projects | | tt project show ID_OR_NAME | Show project details | | tt project add NAME | Create a new project | | tt project edit ID_OR_NAME | Edit a project | | tt project delete ID_OR_NAME | Delete project | | tt project inbox | Show inbox project ID | | tt group list | List project groups | | tt group add NAME | Create a project group | | tt group edit ID | Edit a project group | | tt group delete ID | Delete project group | | tt tag list | List all tags | | tt tag add NAME | Create a tag | | tt tag rename OLD NEW | Rename a tag | | tt tag edit NAME | Edit tag color/parent | | tt tag delete NAME | Delete a tag | | tt user profile | Show user profile | | tt user status | Show subscription status | | tt user stats | Show usage statistics | | tt sync | Fetch full state snapshot | | tt trash empty | Permanently delete all trashed items |

Task references accept exact IDs, unambiguous ID prefixes, and case-insensitive exact titles. Project references also accept unambiguous case-insensitive name prefixes. If multiple items match, use a full ID or add --project PROJECT to task lookup commands that support it.

Use tt COMMAND --help for detailed options.

Configuration

Configuration is stored in ~/.config/ticktick-cli/config.json:

{
  "auth": {
    "username": "[email protected]",
    "storage": "keyring"
  },
  "defaults": {
    "project": "inbox_id"
  }
}

Security Note: By default, session tokens are stored in your system keyring (macOS Keychain, Windows Credential Manager, or Linux Secret Service). If you use --use-config, the token is stored in plaintext in the config file with 600 permissions.

Linux headless and SSH sessions

Linux keyring storage requires an active Secret Service/D-Bus session, which is commonly unavailable in headless or SSH shells. If login succeeds but saving credentials fails with an error such as Cannot autolaunch D-Bus without X11 $DISPLAY, log in with the explicit plaintext fallback:

tt auth login --use-config
tt auth status

This stores the session token in ~/.config/ticktick-cli/config.json with 0600 permissions instead of the system keyring. Use this only when a desktop keyring session is unavailable, and protect the file as you would a password.

Web API compatibility

This CLI uses TickTick's unofficial web API. If TickTick updates its web-client version before the CLI is updated, set TICKTICK_WEB_VERSION temporarily when running a command:

TICKTICK_WEB_VERSION=8121 tt auth login

The built-in default is 8121. This setting is only a compatibility escape hatch; do not set it unless you have verified the current web client's X-Device.version.

Known Limitations

Single Task Lookup

The TickTick V2 API does not support fetching a single task by ID directly. Commands like tt task show fetch all tasks and filter client-side. This is efficient for most users but may be slow for accounts with thousands of tasks.

API Stability

This CLI uses TickTick's unofficial V2 API (reverse-engineered from the web app). While more feature-complete than the official V1 API, it may change without notice.

Development

# Install dependencies
bun install

# Run in development mode
bun run dev [command]

# Type check
bun run typecheck

# Run tests
bun run test

# Build JavaScript package output
bun run build

Contributing

This is a personally maintained project and does not accept code contributions, pull requests, or feature requests. Bug reports with a clear reproduction are welcome; see CONTRIBUTING.md for details.

Releasing

See RELEASING.md for the release process and how to publish new versions.

License

MIT