TickTick CLI Skill

manage tasks and projects in ticktick (dida365) via oauth2-authenticated cli. create, update, complete, abandon tasks with priorities, tags, due dates, and file attachments. list and manage projects. supports batch operations and automatic token refresh.

intent

use this skill to programmatically interact with ticktick task management. run this when you need to create tasks, mark tasks complete or abandoned, update task metadata (priority, due date, tags, descriptions), list tasks filtered by project or status, manage projects, or upload file attachments. typical use cases: agent workflows that generate or track tasks, syncing external data into ticktick, bulk task operations, periodic task status reports.

inputs

external connection: ticktick oauth2

• register app at ticktick developer center
• set redirect uri to http://localhost:8080
• obtain client id and client secret

credentials storage location

• ~/.clawdbot/credentials/ticktick-cli/config.json
• stores client id, client secret, access token, refresh token, token expiry, session cookie
• file permissions should be 600 (owner read/write only)

environment / context

• python 3.7+ with requests library installed
• local http server on port 8080 available for oauth callback (or use manual auth mode)
• access to ticktick.com in browser for interactive auth (or manual mode if headless)

rate limits to track

• 100 requests/minute
• 300 requests/5 minutes
• cli auto-waits and retries up to 4 times on rate limit; do not attempt manual retry loops

procedure

1. authenticate (one-time or refresh)

input: client id, client secret (from developer center)

output: access token, refresh token, expiry timestamp written to ~/.clawdbot/credentials/ticktick-cli/config.json

steps:

• run python -m ticktick.cli auth --client-id <ID> --client-secret <SECRET>
• browser opens automatically; user grants permission; cli captures auth code from redirect
• cli exchanges code for access token and refresh token
• tokens stored to disk
• status check: python -m ticktick.cli auth --status prints current auth state
• logout (revoke token, keep credentials): python -m ticktick.cli auth --logout

2. list projects

input: none (uses stored credentials)

output: json array of project objects with fields: id (24-char hex), name (string), color (hex string)

steps:

• run python -m ticktick.cli lists --json
• parse json output to extract project ids and names
• use project id or name in subsequent task operations

3. create task

input:

• task title (required, string)
• project name or id (optional, default to inbox)
• priority (optional, one of: none, low, medium, high)
• due date (optional, formats: today, tomorrow, in N days, next monday, YYYY-MM-DD, YYYY-MM-DDTHH:MM)
• start time (optional, iso format with timezone, e.g., 2026-04-20T09:00:00+08:00)
• description/content (optional, string)
• tags (optional, list of strings)

output: task object json with fields: id, title, priority, dueDate, startDate, tags, projectId

steps:

• run python -m ticktick.cli task "<TITLE>" --list "<PROJECT>" --priority <PRIORITY> --due "<DATE>" --content "<DESC>" --tag "<TAG1>" --tag "<TAG2>" --json
• cli looks up project by name or id
• cli sends task create request to ticktick api with supplied fields
• cli returns created task object as json

4. update task

input:

• task identifier: title (string, case-insensitive) or id (24-char hex)
• project name or id (optional, narrows search)
• new title (optional)
• new priority (optional)
• new due date (optional)
• new start time (optional)
• new description (optional)
• --update flag (required to signal update mode)

output: updated task object json

steps:

• run python -m ticktick.cli task "<IDENTIFIER>" --update --list "<PROJECT>" --new-title "<NEW>" --priority <P> --due "<D>" --content "<DESC>" --json
• cli looks up task by name or id (within project if specified)
• cli sends patch request to ticktick api with supplied fields
• cli returns updated task object as json

5. list tasks

input:

• project name or id (optional, filters to that project)
• status (optional, one of: pending, completed)

output: json array of task objects with fields: id, title, priority, dueDate, startDate, status, projectId, tags

steps:

• run python -m ticktick.cli tasks --list "<PROJECT>" --status <STATUS> --json
• if project specified, cli looks up project id first
• cli fetches all tasks with optional status filter
• cli returns array as json

6. complete task

input:

• task identifier: title (string, case-insensitive) or id (24-char hex)
• project name or id (optional, narrows search)

output: success message or updated task object

steps:

• run python -m ticktick.cli complete "<IDENTIFIER>" --list "<PROJECT>" --json
• cli looks up task by name or id (within project if specified)
• cli sends completion request to ticktick api (marks task status as completed)
• cli returns confirmation as json

7. abandon task

input:

• task identifier: title (string, case-insensitive) or id (24-char hex)
• project name or id (optional, narrows search)

output: success message or updated task object

steps:

• run python -m ticktick.cli abandon "<IDENTIFIER>" --list "<PROJECT>" --json
• cli looks up task by name or id (within project if specified)
• cli sends abandon request to ticktick api (marks task status as canceled/abandoned)
• cli returns confirmation as json

8. batch abandon tasks

input:

• list of task ids (24-char hex strings, space or comma-separated)

output: success message with count of abandoned tasks

steps:

• run python -m ticktick.cli batch-abandon <ID1> <ID2> <ID3> --json
• cli sends single batch request to ticktick api with all task ids
• cli returns confirmation with count of successfully abandoned tasks
• note: more efficient than abandoning one-by-one if rate limited

9. create project

input:

• project name (required, string)
• color (optional, hex string like #FF5733)

output: project object json with fields: id, name, color

steps:

• run python -m ticktick.cli list "<NAME>" --color "<HEXCOLOR>" --json
• cli sends project create request to ticktick api
• cli returns created project object as json

10. update project

input:

• project identifier: name (string, case-insensitive) or id (24-char hex)
• new name (optional)
• new color (optional, hex string)
• --update flag (required to signal update mode)

output: updated project object json

steps:

• run python -m ticktick.cli list "<IDENTIFIER>" --update --new-name "<NEWNAME>" --color "<HEXCOLOR>" --json
• cli looks up project by name or id
• cli sends patch request to ticktick api with supplied fields
• cli returns updated project object as json

11. upload file attachment

input:

• task identifier: title (string, case-insensitive) or id (24-char hex)
• file path (required, local filesystem path)
• project name or id (optional, narrows task search)

output: success message with attachment metadata (attachment id, filename, size)

steps:

• run python -m ticktick.cli attach "<IDENTIFIER>" /path/to/file --list "<PROJECT>" --json
• cli looks up task by name or id (within project if specified)
• cli reads file from disk
• cli uploads file via ticktick web session api (requires valid session cookie in config)
• cli returns attachment metadata as json
• note: uses web session cookie (not oauth), see decision point below

decision points

if user not authenticated: cli returns "not authenticated" error. user must run auth flow (step 1) before any task operations.

if project name not found: cli returns "project not found" error. user should run lists --json to verify correct project name and then use returned project id instead of name.

if task name not found: cli tries case-insensitive match on task title. if still no match, cli returns "task not found". user should try tasks --list <PROJECT> --json to list all tasks and find exact title or id.

if task id provided instead of name: cli uses id directly without lookup, skipping name-based search entirely. id is 24-character hexadecimal string.

if access token expired: cli detects expiry via api 401 response, automatically calls refresh endpoint with refresh token, stores new access token to disk, and retries original request. if refresh token also expired, user must re-run auth flow.

if rate limit hit (429 response): cli pauses, waits with exponential backoff (1s, 2s, 4s, 8s), and retries up to 4 times. if still failing after 4 retries, cli returns rate limit error. user should wait 1-5 minutes before retrying.

if attachment upload fails with 401/403: session cookie (web api, not oauth) has expired. user must manually obtain fresh session cookie from browser (open ticktick.com, f12 dev tools, application tab, cookies, copy t cookie value) and update sessionCookie field in config.json. do not provide password.

if no browser available (headless server): user can run auth with --manual flag: python -m ticktick.cli auth --client-id <ID> --client-secret <SECRET> --manual. cli prints auth url; user visits url in any browser, grants permission, and copy-pastes auth code back to cli prompt.

if due date string is ambiguous (e.g., "04-20"): cli assumes YYYY-MM-DD format. always provide full 4-digit year or use unambiguous strings (today, tomorrow, in N days, next monday) to avoid parsing errors.

if task has no due date set: due date fields in json output will be null or omitted. update operations should not include --due if no change desired.

if multiple tasks match name in same project: cli returns first match (oldest created first, typically). to avoid ambiguity, use task id (24-char hex) instead of name.

output contract

all commands support --json flag for machine-readable output.

task object schema:

{
  "id": "6f52a3d1c2b4e8f9a1d3c5e7",
  "title": "Buy coffee",
  "content": "Optional description here",
  "priority": "high",
  "status": "pending",
  "dueDate": "2026-04-20T23:59:59+08:00",
  "startDate": "2026-04-20T09:00:00+08:00",
  "tags": ["shopping", "urgent"],
  "projectId": "6f52a3d1c2b4e8f9a1d3c5e7",
  "createdTime": "2026-04-18T10:30:00+08:00",
  "modifiedTime": "2026-04-18T11:45:00+08:00"
}

project object schema:

{
  "id": "6f52a3d1c2b4e8f9a1d3c5e7",
  "name": "Work",
  "color": "#FF5733",
  "kind": "LIST",
  "sortOrder": 1
}

list tasks output: json array of task objects

list projects output: json array of project objects

create/update task output: single task object json

create/update project output: single project object json

batch abandon output:

{
  "success": true,
  "abandonedCount": 3,
  "taskIds": ["id1", "id2", "id3"]
}

error output:

{
  "error": "error message here",
  "code": "TASK_NOT_FOUND"
}

credentials file location: ~/.clawdbot/credentials/ticktick-cli/config.json (json format, file perms 600)

outcome signal

authentication success: auth --status returns "authenticated" and shows token expiry timestamp.

task created: cli returns json object with non-null id field. task appears in ticktick app immediately.

task updated: cli returns json object with updated fields reflecting changes (title, priority, due date, etc.).

task completed: task status field in returned json is "completed". task moves to completed section in ticktick app.

task abandoned: task status field in returned json is "canceled". task removed from pending view in ticktick app.

project created: cli returns json object with non-null id and name matching input.

project updated: cli returns json object with updated name or color matching input.

file attachment uploaded: cli returns attachment metadata json with non-null attachment id. file appears in task attachments in ticktick app.

list tasks: cli returns json array with 1+ task objects. if no tasks match filter, returns empty array [].

list projects: cli returns json array with 1+ project objects. if no projects, returns empty array [].

cli operation failure: cli returns error json with "error" and "code" fields. check error message for specific cause (not authenticated, project not found, rate limited, etc.). see troubleshooting section of original docs for remediation.

---

additional reference

date format support:

• natural language: today, tomorrow, in 3 days, next monday (all resolve to 23:59 same day)
• iso 8601: YYYY-MM-DD (resolves to 23:59), YYYY-MM-DDTHH:MM (exact time, must include timezone offset like +08:00 to avoid utc confusion)
• always use explicit timezone offset in iso dates to prevent cross-timezone bugs

priority levels:

• none (default, no indicator)
• low
• medium
• high

task status values:

• pending (not yet done)
• completed (marked done)
• canceled (abandoned)

api rate limits:

• 100 requests/minute
• 300 requests/5 minutes
• cli auto-handles retry with backoff; manual retry not needed

file attachment notes:

• uses ticktick web session api (separate from oauth)
• requires valid t cookie (session cookie) in config, not oauth token
• cookie expires periodically; user must refresh from browser dev tools when 401/403 occurs
• never provide password; only copy session cookie value

github repository: https://github.com/liuboacean/ticktick-cli