ticktick-cli

name	ticktick-cli
description	Manage tasks and projects in TickTick. Use when user asks for tasks, to-dos, reminders, or event.
homepage	https://ticktick.com

TickTick CLI — How Agents Should Install, Login, and Use

This skill describes how an agent should reliably use @ticktick/ticktick-cli to help the user install the CLI, log in with OAuth (PKCE), and perform common task/project operations.

Use this skill whenever the user wants to manage TickTick via CLI (e.g. "use ticktick-cli to create a task").

---

1. Scope & Intent

• This skill focuses on:
  • Installing @ticktick/ticktick-cli
  • Logging in via OAuth PKCE
  • Common project and task workflows (list, create, update, complete, delete, move)
• This skill does not cover:
  • Rare/advanced or extremely destructive operations
  • Internal development commands or debugging-only flows

When in doubt, prefer safe, narrow actions and ask the user to clarify ambiguous intent.

---

2. Prerequisites & Environment

• The user should have:
  • Node.js + npm (preferably latest LTS)
• The CLI is expected to be installed globally.

Always follow this order:

1. Check if the CLI already exists:

   ticktick --version
   

   • If this succeeds, the CLI is installed and usable.
   • If this fails (command not found or similar), proceed to install.

2. Install the CLI globally (if needed):

   npm install -g @ticktick/ticktick-cli
   

3. Verify installation:

   ticktick --help
   ticktick --version
   

If installation fails due to environment issues (e.g. missing Node, permissions), explain the error to the user and suggest they fix their Node/npm setup first.

---

3. Authentication

The CLI supports two authentication methods: OAuth PKCE (recommended) and manual Token.

3.1 OAuth PKCE (Recommended)

The CLI uses OAuth PKCE in a browser to log in. This is the default and recommended way.

Standard login flow:

1. Start login:

   ticktick auth login
   

   • This should open a browser window/tab.
   • The user logs in and authorizes the app.

2. Confirm login status:

   ticktick auth status
   

   • If logged in, you can proceed with project/task operations.
   • If not logged in, clearly tell the user and suggest retrying ticktick auth login.

3. Logout (only when explicitly requested):

   ticktick auth logout
   

Guidelines:

• Do not log the user out unless they explicitly ask for it.
• If login fails (e.g. browser blocked, network error), inform the user and suggest:
  • Checking that the browser window actually opened.
  • Making sure pop-up blockers or firewalls are not blocking the OAuth page.
  • Trying again later if the API seems temporarily unavailable.

3.2 Token (Headless Environments)

If the environment is headless (no browser available) or the user cannot use browser-based OAuth, they can log in via an access token directly.

When to use:

• Running inside an AI agent environment without a web browser interface.
• SSH sessions, CI/CD pipelines, or remote servers.

How to instruct the user: Ask the user to generate an API Token and provide it to you or run the command themselves.

• Tell the user to: Log in to the TickTick web app, click their avatar in the top-left corner, and go to Settings > Account > API Token to create and copy a token.

How to apply the token: Once the user provides the token, run:

ticktick auth token <token>

---

4. Using Projects and Tasks — Typical Workflows

4.1 Listing Projects

To list all projects:

ticktick project list

For structured data suitable for filtering:

ticktick project list --json

Agent rule:

• When you need to select a project programmatically (by name or other fields), always prefer the --json variant.

4.2 Selecting a Project by Name

When the user refers to a project by name (e.g. "Inbox", "Work"):

1. Fetch projects with JSON:

   ticktick project list --json
   

2. Find the project with a matching name field.

   • If no project matches, tell the user and ask them to confirm the name.
   • If multiple projects share the same name, show them to the user and ask which one to use.
   • Once a single project is selected, use its id in subsequent commands.

Rule:

• Never guess or invent project IDs.
• Always derive them from actual project list --json output or from explicit user input.

4.3 Creating a Task in a Project

When the user says "create a task in project X":

1. Resolve X to a project id (see 4.2).

2. Use:

   ticktick task create --title "<task title>" --project <projectId>
   

Optional recommended flags (only if supported by the CLI and relevant to the request):

• --content "<detailed description>"
• --dueDate "<ISO 8601 date/time>"
• --tags "<comma-separated tags>"
• Other fields as documented in the CLI/README.

After creation, you may run (if needed):

ticktick project list --json
# or a specific command to fetch the created task if available

and summarize the created task (id, title, project, due date) to the user.

4.4 Getting / Updating / Completing / Deleting a Task

Get a task (when you know both projectId and taskId):

ticktick task get <projectId> <taskId>

Update a task:

ticktick task update <taskId> \
  --id <taskId> \
  --project <projectId> \
  --title "New title"

Add more flags as needed (content, due date, tags, etc.), based on the user’s request.

Complete a task:

ticktick task complete <projectId> <taskId>

Delete a task (destructive):

ticktick task delete <projectId> <taskId>

Safety rules:

• For delete and other destructive operations, the user must clearly ask for it.
• If the instruction is vague (e.g. "clean up old tasks"), first:
  • Show a short list of candidate tasks (titles, due dates, ids).
  • Ask the user to confirm which ones to complete/delete.

4.5 Moving a Task Between Projects

To move a task from one project to another:

ticktick task move \
  --from <sourceProjectId> \
  --to <destProjectId> \
  --task <taskId>

Workflow:

1. Resolve both projects by name (if supplied as names).
2. Confirm the taskId (either from user or by listing/searching).
3. Execute the move command.
4. Optionally confirm the move by fetching the task and summarizing the result.

---

5. JSON Mode and Structured Handling

Most commands support a --json flag.

When to use --json:

• Any time you need to:
  • Filter by name.
  • Select from multiple candidates.
  • Chain commands based on id or other fields.

Examples:

ticktick project list --json
ticktick task get <projectId> <taskId> --json

Agent behavior:

• Use --json for internal decision-making and selection.
• Convert JSON results into a short, human-readable summary when responding to the user:
  • E.g. "Found project: id=…, name=…, color=…".

---

6. ID and Selection Rules

• Projects

  • Prefer matching by name from project list --json.
  • If more than one project matches, present options to the user.
  • Once a project is chosen, use its id and keep it consistent for this operation.

• Tasks

  • If the user gives a concrete taskId, use it directly.
  • If the user describes a task (e.g. by title or due date) and multiple tasks may match:
    • Fetch candidate tasks (via appropriate list/get operations).
    • Show a small selection (id, title, due date).
    • Ask the user to choose which one(s) to act on.

• Never fabricate IDs and never assume "the first one" is correct unless:

  • You transparently explain what "first" means (e.g. "sorted by creation time, using the most recent one"),
  • And the user implicitly or explicitly accepts this.

---

7. Safety & Destructive Operations

• Treat the following as destructive and require explicit, unambiguous user confirmation:
  • task delete
  • Bulk completion or deletion (if supported)
  • Any operation that may remove or irreversibly change multiple tasks

Guidelines:

• If the user uses vague terms like "remove useless tasks", ask:
  • What criteria define "useless"?
  • Whether they want to see a preview list first.
• Prefer showing a preview (ids, titles, due dates) before executing bulk changes.

Do not:

• Log the user out spontaneously (auth logout) without a request.
• Perform repeated, aggressive retries on failing API calls.

---

8. Error Handling & Recovery

Common error categories and recommended behavior:

• Authentication errors (e.g. 401, invalid token):

  • Explain that authentication may have expired.

  • Suggest rerunning:

    ticktick auth login
    ticktick auth status
    

• Network / connectivity errors:

  • Tell the user that the error may be temporary or network-related.
  • Suggest they check their connection and try again later.

• Not found / invalid IDs:

  • Inform the user that the project or task could not be found.
  • Show any relevant context (e.g. available projects) and ask them to re-check the ID or name.

• Ambiguous selections:

  • If multiple matching items are found (project or task), show them and ask the user which one they intend.

In all cases, prefer clear explanations and minimal retries over silent failure.

---

9. OpenAPI model fields (reference)

When interpreting JSON from the TickTick Open API (or MCP tools that mirror these shapes), use the following field meanings. Names are shown in camelCase as in API payloads where applicable; Python models may use snake_case with aliases.

Auth

• TickTickAccessToken.user_id: User id from token introspection (if present).

OpenChecklistItem (checklist row under a task)

• id: Checklist item id (hex ObjectId string).
• status: 0 = not completed, 1 = completed.
• title: Item title.
• sortOrder: Display order among checklist items.
• startDate: Start time for the item.
• isAllDay: Whether the item is all-day.
• timeZone: Time zone for the item’s times.
• completedTime: When the item was marked completed.

OpenColumn (Kanban column)

• id: Column id (hex ObjectId string).
• projectId: Project this column belongs to.
• name: Column name.
• sortOrder: Order among columns.

OpenProjectProfile (project metadata)

• id: Project id (hex ObjectId string).
• name: Project name.
• color: Project color (as returned by API).
• sortOrder: Order among projects.
• closed: Whether the project is closed.
• groupId: Project group id (if any).
• viewMode: list | kanban | timeline.
• permission: read | comment | write.
• kind: TASK | NOTE (project type).

OpenTask (task)

• id: Task id (hex ObjectId string).
• projectId: Owning project id.
• sortOrder: Order within the project/list.
• title: Short title; use content for longer body text when kind is task/note.
• content: Main body; relevant when kind is task-like or note (per API).
• desc: Description; relevant when kind is CHECKLIST.
• startDate: Start date/time.
• dueDate: Due date/time; if different from start, API treats it as a duration (end vs start).
• timeZone: Task time zone.
• isAllDay: All-day task flag.
• priority: 0 none, 1 low, 3 medium, 5 high.
• reminders: Reminder definitions (strings as API returns them).
• repeatFlag: Recurrence / repeat rule string.
• completedTime: Completion timestamp (when completed).
• status: 0 not completed, -1 abandoned, 2 completed.
• items: Checklist sub-items when kind is CHECKLIST.
• tags: Tag names.
• columnId / columnName: Kanban column placement.
• parentId: Parent task id for subtasks.
• childIds: Child task ids.
• assignor: Assignor identifier (as API provides).
• etag: ETag for optimistic concurrency when updating.
• kind: Task shape: TEXT | NOTE | CHECKLIST (see content vs desc above).

OpenProjectData

• project: OpenProjectProfile for the project.
• tasks: Incomplete tasks under that project.
• columns: Kanban columns under that project.

CompletedTaskSearchOpenapi

• projectIds: Limit search to these projects.
• startDate / endDate: Completed-task time range (ISO 8601).

UndoneTaskSearchOpenapi

• projectIds: Limit to these projects (set semantics in model).
• startDate / endDate: Filter range for dates (ISO 8601).

TaskSearchOpenapi

• keywords: Free-text search.
• projectIds: Scope to projects.
• tags: Filter by tags.
• status: Filter by task status codes.
• dueFrom / dueTo: Due date range (ISO 8601 strings).

TaskFilterOpenapi

• startDate / endDate: Date filter (ISO 8601).
• projectIds: Project scope.
• priority: Allowed values typically 0, 1, 3, 5.
• tag: Tags to filter.
• kind: TASK, NOTE, CHECKLIST.
• status: Status codes to include.

OpenMoveProject (move task between projects)

• fromProjectId: Source project.
• toProjectId: Destination project.
• taskId: Task to move.
• sortOrder: Position in destination; omit to leave order unchanged.

SyncTaskDto (batch sync request)

• update: Tasks to update.
• add: Tasks to create.

SyncTaskResultDto (batch sync response)

• id2etag: Map of task id → new ETag for successes.
• id2error: Map of task id → error message for failures.

UserPreferenceDto

• timeZone: User’s preferred time zone string.

---

10. Style Notes for Agents

• Use commands from this skill as your primary reference for TickTick CLI usage.
• When the user asks for "what happened" or "what did you do", respond with:
  • A short description of the commands you ran (in natural language).
  • A short summary of their effects (e.g. "Created task 'Buy milk' in project 'Inbox'").

If existing documentation (such as the package README) disagrees with this skill, follow this skill’s safer, more conservative interpretation unless the user explicitly asks otherwise.

Field semantics for API-shaped JSON are summarized in section 9 (OpenAPI model fields).