ticktick-api

name	ticktick-api
description	Use this skill when you need to interact with the TickTick Open API, automate task or project operations, or run the bundled Python CLI with `uv run`.
metadata	{"author":"Copilot","version":"1.1.0"}

TickTick API

Use this skill for TickTick Open API work. The bundled CLI is the default way to call the API.

Workflow

1. Run the CLI from the skill root with uv run scripts/ticktick.py --help.
2. Store OAuth app settings once with auth client set (client ID, client secret, redirect_uri).
3. Use auth login as the primary authentication path. It captures the callback, exchanges the token, and stores it in the keyring.
4. Lazy Authentication: Do NOT check auth status before every command. Simply run your intended command. If it fails with a 401 Unauthorized error, then run auth login.
5. Project Resolution: Most commands accept a Project Name (e.g., "Compras"), a partial name, or a 24-char hex ID. The CLI caches these mappings locally.
6. Inbox Default: If you create a task without specifying a project, it defaults to your Inbox.

CLI Conventions

• The CLI lives in scripts/ticktick.py.
• It uses inline script metadata and should be executed with uv run scripts/ticktick.py.
• Dependencies are resolved from the script metadata automatically.

Efficient Workflows

• Creating Tasks:
  • uv run scripts/ticktick.py tasks create "comprar panos de prato" (Inbox)
  • uv run scripts/ticktick.py tasks create "lavar o carro" -p "Pessoal" (Specific Project)
• Listing Active Tasks: Use uv run scripts/ticktick.py tasks filter --active for all uncompleted tasks.
• Filtering by Project: Use -p "Project Name" with tasks filter, tasks completed, etc.
• Status Aliases: Use active (0), completed (2), or deleted (-1).

Supported Commands

• auth login: Re-authenticate if you get a 401 error.
• projects list, projects get, projects create, projects update, projects delete.
• tasks get, tasks create, tasks update, tasks complete, tasks delete, tasks move.
• tasks completed and tasks filter.

Output Rules

• Show a compact summary for single-item responses.
• Render lists as tables unless --json is requested.
• Proactive Name Usage: If the user mentions a category or project by name, use it directly with the -p flag. Do NOT call projects list first unless the name resolution fails.

Notes

• Date strings should follow TickTick's format: yyyy-MM-dd'T'HH:mm:ssZ.
• The CLI automatically handles token storage via the system keyring.
• If a request fails with 401, instruct the user to run auth login.