Call the TickTick / Dida365 Open API through this skill. Defaults to Dida365 for China; the international version is only selected explicitly at login.
Execution conventions
- Output intended for Agent parsing is always appended with
--json, and global parameters must be placed before the subcommand. - Confirm the user's intent before deleting a project or task;
deletewill actually delete remote data. - When unsure about parameters, first check
./scripts/ticktick_cli.py <command> --help。
Authentication
By default, assume the local token is valid and directly perform the operation requested by the user; do not run auth doctor。
Only when a command fails and the error points to authentication, token, permission, region, or API base URL issues, then diagnose the current local token:
./scripts/ticktick_cli.py --json auth doctor
Log in only when there is really no token, the token has expired, or the user asks to log in again:
./scripts/ticktick_cli.py auth login
- For international version login use
./scripts/ticktick_cli.py auth login --region ticktick。 - By default only the authorization link is output, and the browser is not opened automatically; add
--open。 - Login will start a localhost callback and wait 5 minutes by default; after seeing the link, complete authorization as soon as possible.
- The token is saved by default to
~/.config/ticktick-cli/token.json, and can be overridden withTICKTICK_TOKEN_FILE. - Subsequent commands only read the local token file and infer the region and API base URL from the token metadata.
- In remote SSH scenarios, the browser callback must be able to reach the machine running the CLI; if necessary, log in locally on the target machine, or set up port forwarding yourself.
Daily operations
Common command families:
auth login|doctor|logoutproject list|get|data|create|update|deletetask get|create|update|complete|delete|move|completed|filterfocus get|list|deletehabit list|get|create|update|checkin|checkins
Common entry points:
./scripts/ticktick_cli.py --json project list
./scripts/ticktick_cli.py --json project data --project-id <project-id>
./scripts/ticktick_cli.py --json task get --project-id <project-id> --task-id <task-id>
./scripts/ticktick_cli.py --json task filter --project-id <project-id> --status 0
Create or update a checklist subtask:
- Simple title: pass repeatedly
--item。 - Complex fields: use
--item-jsonto pass a JSON array, or pass@pathto read a file. - Task tags: when creating/updating a task, pass repeatedly
--tag。 - Complex habit payload: use
--payload-jsonto pass a JSON object, or pass@pathto read a file.
If a JSON file is temporarily created by the Agent for the current single write operation and will not be reused after success, in the same shell
call run the write operation and rm -- <明确路径> serially with && . If the write operation fails, keep the file and do not
use ; to delete unconditionally, and do not use variables, wildcards, or directories as cleanup targets. JSON provided by the user and
files that still need to be reused for subsequent updates or validation must not be cleaned up automatically. For example:
./scripts/ticktick_cli.py --json task create \
--project-id <project-id> \
--title "任务标题" \
--item-json @/tmp/ticktick-items.json \
&& rm -- /tmp/ticktick-items.json
Data model
- Project: a task container, supporting views such as list / kanban / timeline.
- Task: belongs to a Project, and can include time, reminders, priority, recurrence rules, tags, and subtasks.
- ChecklistItem: a subtask item under a Task.
- Column: a kanban column, commonly used only in kanban scenarios.
- ProjectData: aggregated project details, including the project, incomplete tasks, and column information.
- Focus: focus/pomodoro records.
- Habit: habits and check-in records.