TickTick API CLI

Lightweight CLI for the official TickTick / Dida365 Open API.

This project is designed for developers who want a small local tool that can:

• authenticate with OAuth 2.0
• manage projects and tasks from the terminal
• fit into scripts and agent workflows
• avoid storing secrets inside the repository

What It Does

• OAuth 2.0 login against the official developer platform
• list, create, and delete projects
• create, filter, complete, move, and delete tasks
• print human-readable output or raw JSON
• expose a reusable AI Skill for agent-based workflows

Why This Repo Exists

Most TickTick / Dida365 integrations either focus on a larger app surface area or leave the OAuth and host configuration details to the user. This repo stays intentionally small and opinionated:

• official API only
• terminal-first workflow
• easy to inspect and modify
• safe-by-default repository layout with no checked-in credentials

Verified Host Pair

The current verified default host pair is:

• Auth Base: https://ticktick.com
• API Base: https://api.ticktick.com

That combination has been tested end-to-end with a real account in this codebase.

Requirements

• Python 3.9+
• a TickTick / Dida365 developer app from https://developer.ticktick.com/manage
• a redirect URI configured in that app, recommended:

http://127.0.0.1:14565/callback

Installation

Option A: Run from the repository

git clone <your-repo-url>
cd ticktick-api-cli
python3 -m pip install -e .
./ticktick --help

Option B: Use the package entry point

git clone <your-repo-url>
cd ticktick-api-cli
python3 -m pip install -e .
ticktick-api --help

Secret Hygiene

This repository is meant to stay shareable.

Do not commit:

• real client_id
• real client_secret
• access tokens
• copied local config files

Use one of these two approaches instead:

Approach 1: Environment variables

Copy .env.example into your own local .env or export values in your shell:

export TICKTICK_REGION=cn
export TICKTICK_AUTH_BASE=https://ticktick.com
export TICKTICK_API_BASE=https://api.ticktick.com
export TICKTICK_REDIRECT_URI=http://127.0.0.1:14565/callback
export TICKTICK_CLIENT_ID=your_client_id
export TICKTICK_CLIENT_SECRET=your_client_secret

Approach 2: Home-directory config

Use the built-in config command. Credentials are stored outside the repo at:

~/.config/codex-ticktick-api/config.json

Example:

./ticktick config set \
  --region cn \
  --client-id 'your_client_id' \
  --client-secret 'your_client_secret' \
  --redirect-uri 'http://127.0.0.1:14565/callback'

Quick Start

1. Create a developer app

Go to https://developer.ticktick.com/manage and create an app.

You will need:

• client_id
• client_secret
• the same redirect URI you will use locally

2. Check config

./ticktick config show

3. Start OAuth login

./ticktick auth login

This command:

• starts a local callback server
• opens the browser
• exchanges the authorization code
• stores the token outside the repository

4. Verify access

./ticktick auth status
./ticktick project list

Common Commands

./ticktick auth status
./ticktick auth url

./ticktick project list
./ticktick project create --name "Inbox"
./ticktick project delete --project-id "<project_id>"

./ticktick task create --project-id "<project_id>" --title "Buy milk"
./ticktick task list --project-id "<project_id>"
./ticktick task completed --project-id "<project_id>"
./ticktick task complete --project-id "<project_id>" --task-id "<task_id>"
./ticktick task move --from-project-id "<source_id>" --to-project-id "<target_id>" --task-id "<task_id>"
./ticktick task delete --project-id "<project_id>" --task-id "<task_id>"

Add --json when you want raw API output:

./ticktick project list --json

Repository Guide

• Human onboarding: docs/ONBOARDING.md
• Lightweight publishing checklist: docs/PUBLISHING_CHECKLIST.md
• Reusable agent skill: skills/ticktick-openapi/SKILL.md

AI Skill

This repository includes a reusable Skill under skills/ticktick-openapi.

Use it when an AI agent needs to:

• operate this CLI
• handle TickTick OAuth setup
• troubleshoot auth or host mismatches
• automate project / task workflows safely

The Skill is generic and does not contain any local credentials.

Known Limitations

• token refresh is not implemented yet
• task list currently relies on the official task/filter endpoint
• the default workflow is optimized for local machine usage, not multi-user server deployment

Official References

• Developer Center: https://developer.ticktick.com/manage
• Open API Docs: https://developer.ticktick.com/docs/#/openapi

License

MIT. See LICENSE.