ticktick

# TickTick CLI Skill Manage TickTick tasks and projects from the command line. ## Setup ### 1. Register a TickTick Developer App 1. Go to [TickTick Developer Center](https://developer.ticktick.com/manage) 2. Create a new application 3. Set the redirect URI to `http://localhost:8080` 4. Note your `Client ID` and `Client Secret` ### 2. Authenticate ```bash # Set credentials and start OAuth flow bun run scripts/ticktick.ts auth --client-id YOUR_CLIENT_ID --client-secret YOUR_CLIENT_SECRET # Check authentication status bun run scripts/ticktick.ts auth --status # Logout (clear tokens, keep credentials) bun run scripts/ticktick.ts auth --logout ``` ### Headless / Manual Authentication ```bash # Use manual mode on headless servers bun run scripts/ticktick.ts auth --client-id YOUR_CLIENT_ID --client-secret YOUR_CLIENT_SECRET --manual ``` This prints an authorization URL. Open it in a browser, approve access, then copy the full redirect URL (it looks like `http://localhost:8080/?code=XXXXX&state=STATE`) and paste it back into the CLI. The CLI will open your browser to authorize access. After approving, tokens are stored in `~/.clawdbot/credentials/ticktick-cli/config.json`. ## Commands ### List Tasks ```bash # List all tasks bun run scripts/ticktick.ts tasks # List tasks from a specific project bun run scripts/ticktick.ts tasks --list "Work" # Filter by status bun run scripts/ticktick.ts tasks --status pending bun run scripts/ticktick.ts tasks --status completed # JSON output bun run scripts/ticktick.ts tasks --json ``` ### Create Task ```bash # Basic task creation bun run scripts/ticktick.ts task "Buy groceries" --list "Personal" # With description and priority bun run scripts/ticktick.ts task "Review PR" --list "Work" --content "Check the new auth changes" --priority high # With due date bun run scripts/ticktick.ts task "Submit report" --list "Work" --due tomorrow bun run scripts/ticktick.ts task "Plan vacation" --list "Personal" --due "in 7 days" bun run scripts/ticktick.ts task "Meeting" --list "Work" --due "2024-12-25" # With tags bun run scripts/ticktick.ts task "Research" --list "Work" --tag research important ``` ### Update Task ```bash # Update by task name or ID bun run scripts/ticktick.ts task "Buy groceries" --update --priority medium bun run scripts/ticktick.ts task "abc123" --update --due tomorrow --content "Updated notes" # Limit search to specific project bun run scripts/ticktick.ts task "Review PR" --update --list "Work" --priority low ``` ### Complete Task ```bash # Mark task as complete bun run scripts/ticktick.ts complete "Buy groceries" # Complete with project filter bun run scripts/ticktick.ts complete "Review PR" --list "Work" ``` ### Abandon Task (Won't Do) ```bash # Mark task as won't do bun run scripts/ticktick.ts abandon "Old task" # Abandon with project filter bun run scripts/ticktick.ts abandon "Obsolete item" --list "Do" ``` ### Batch Abandon (Multiple Tasks) ```bash # Abandon multiple tasks in a single API call bun run scripts/ticktick.ts batch-abandon <taskId1> <taskId2> <taskId3> # With JSON output bun run scripts/ticktick.ts batch-abandon abc123def456... xyz789... --json ``` Note: `batch-abandon` requires task IDs (24-character hex strings), not task names. Use `tasks --json` to get task IDs first. ### List Projects ```bash # List all projects bun run scripts/ticktick.ts lists # JSON output bun run scripts/ticktick.ts lists --json ``` ### Create Project ```bash # Create new project bun run scripts/ticktick.ts list "New Project" # With color bun run scripts/ticktick.ts list "Work Tasks" --color "#FF5733" ``` ### Update Project ```bash # Rename project bun run scripts/ticktick.ts list "Old Name" --update --name "New Name" # Change color bun run scripts/ticktick.ts list "Work" --update --color "#00FF00" ``` ## Options Reference ### Priority Levels - `none` - No priority (default) - `low` - Low priority - `medium` - Medium priority - `high` - High priority ### Due Date Formats - `today` - Due today - `tomorrow` - Due tomorrow - `in N days` - Due in N days (e.g., "in 3 days") - `next monday` - Next occurrence of weekday - ISO date - `YYYY-MM-DD` or full ISO format ### Global Options - `--json` - Output results in JSON format (useful for scripting) - `--help` - Show help for any command ## Agent Usage Tips When using this skill as an AI agent: 1. **Always use `--json` flag** for machine-readable output 2. **List projects first** with `lists --json` to get valid project IDs 3. **Use project IDs** rather than names when possible for reliability 4. **Check task status** before completing to avoid errors Example agent workflow: ```bash # 1. Get available projects bun run scripts/ticktick.ts lists --json # 2. Create a task in a specific project bun run scripts/ticktick.ts task "Agent task" --list "PROJECT_ID" --priority high --json # 3. Later, mark it complete bun run scripts/ticktick.ts complete "Agent task" --list "PROJECT_ID" --json ``` ## Configuration Tokens are stored in `~/.clawdbot/credentials/ticktick-cli/config.json`: ```json { "clientId": "YOUR_CLIENT_ID", "clientSecret": "YOUR_CLIENT_SECRET", "accessToken": "...", "refreshToken": "...", "tokenExpiry": 1234567890000, "redirectUri": "http://localhost:8080" } ``` Note: Credentials are stored in plaintext. The CLI attempts to set file permissions to 700/600; treat this file as sensitive. The CLI automatically refreshes tokens when they expire. ## Troubleshooting ### "Not authenticated" error Run `bun run scripts/ticktick.ts auth` to authenticate. ### "Project not found" error Use `bun run scripts/ticktick.ts lists` to see available projects and their IDs. ### "Task not found" error - Check the task title matches exactly (case-insensitive) - Try using the task ID instead - Use `--list` to narrow the search to a specific project ### Token expired errors The CLI should auto-refresh tokens. If issues persist, run `bun run scripts/ticktick.ts auth` again. ## API Notes This CLI uses the [TickTick Open API v1](https://developer.ticktick.com/api). ### Rate Limits - **100 requests per minute** - **300 requests per 5 minutes** The CLI makes multiple API calls per operation (listing projects to find task), so bulk operations can hit limits quickly. ### Batch Endpoint The CLI supports TickTick's batch endpoint for bulk operations: ``` POST https://api.ticktick.com/open/v1/batch/task { "add": [...], // CreateTaskInput[] "update": [...], // UpdateTaskInput[] "delete": [...] // { taskId, projectId }[] } ``` Use `batch-abandon` to abandon multiple tasks in one API call. The batch API method is also exposed for programmatic use. ### Other Limitations - Maximum 500 tasks per project - Some advanced features (focus time, habits) not supported by the API