Introduction
# 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