TickTick CLI Skill

Manage TickTick tasks and projects from the command line.

Setup

1. Register a TickTick Developer App

Go to TickTick Developer Center
Create a new application
Set the redirect URI to
```
http://localhost:8080
```
Note your
```
Client ID
```
and
```
Client Secret
```

2. Authenticate

# 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

# 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

# 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

# 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

# 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

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

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

# 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

# List all projects
bun run scripts/ticktick.ts lists
JSON output

bun run scripts/ticktick.ts lists --json

Create Project

# 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

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

Always use
--json
flag for machine-readable output
List projects first with
```
lists --json
```
to get valid project IDs
Use project IDs rather than names when possible for reliability
Check task status before completing to avoid errors

Example agent workflow:

# 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

{
  "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.

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

TickTick CLI

AI Skill Market Insights

Be Part of the 0+ Developer Community

TickTick CLI Skill

Setup

1. Register a TickTick Developer App

2. Authenticate

Check authentication status

Logout (clear tokens, keep credentials)

Headless / Manual Authentication

Commands

List Tasks

List tasks from a specific project

Filter by status

JSON output

Create Task

With description and priority

With due date

With tags

Update Task

Limit search to specific project

Complete Task

Complete with project filter

Abandon Task (Won't Do)

Abandon with project filter

Batch Abandon (Multiple Tasks)

With JSON output

List Projects

JSON output

Create Project

With color

Update Project

Change color

Options Reference

Priority Levels

Due Date Formats

Global Options

Agent Usage Tips

2. Create a task in a specific project

3. Later, mark it complete

Configuration

Troubleshooting

"Not authenticated" error

"Project not found" error

"Task not found" error

Token expired errors

API Notes

Rate Limits

Batch Endpoint

Other Limitations

Quick Start

Manual Installation

TEAR & SHARE

Tags

Channels

Learn

Compare

Company