TickTick CLI

Manage TickTick tasks and projects from the command line with OAuth2 auth, batch operations, and rate limit handling.

Security Scan

The TickTick CLI skill is internally consistent with its stated purpose (a local CLI that uses OAuth2 to manage TickTick tasks); code and instructions align with the description and there are no signs of data exfiltration or unrelated privileges — but note a few small inconsistencies and operational cautions.

Purpose & Capability

The code, commands, and SKILL.md all implement a TickTick CLI using OAuth2 and the TickTick API as claimed. One minor mismatch: the runtime commands in SKILL.md use 'bun run', but the skill metadata does not declare bun (or any required binary). Requiring Bun is reasonable for this project, but it should have been listed as a required binary.

Instruction Scope

Runtime instructions in SKILL.md match the code: register a TickTick developer app, run the OAuth flow, and use the provided commands. The instructions only read/write the skill's credential file (~/.clawdbot/credentials/ticktick-cli/config.json) and call TickTick endpoints; they do not ask the agent to read unrelated system files or transmit data to unexpected endpoints.

Install Mechanism

There is no install spec (instruction-only), which is low risk. The package includes source files (TypeScript) and expects Bun to run them; the absence of an install step is acceptable but the skill should declare 'bun' as a required runtime. Dependencies are standard (commander, open) and are not fetched via an untrusted URL.

Credentials

The skill requests no environment variables and stores OAuth client ID/secret and tokens in a local config file under the skill's own directory. This is proportionate to its purpose. Note: tokens/credentials are stored in plaintext JSON (the code attempts to set restrictive file perms 700/600) — treat that file as sensitive.

Persistence & Privilege

The skill does not request permanent/global privileges and 'always' is false. It stores credentials in its own directory and does not modify other skills or system-wide agent settings.

Assessment

This skill appears to do what it says: a local TickTick CLI that uses OAuth2 and stores tokens locally. Before installing, consider: 1) The CLI expects the Bun runtime (SKILL.md uses 'bun run') but the metadata didn't declare it — ensure you have Bun or adapt commands to your environment (node/ts-node) if needed. 2) You will need to register a TickTick developer app and provide Client ID and Client Secret; those credentials and the resulting access/refresh tokens are stored in plaintext JSON at ~/.clawdbot/credentials/ticktick-cli/config.json (the code sets restrictive file perms but the file contents are not encrypted). Keep that file secure and don't share it. 3) The skill's source is 'unknown' and no homepage is provided — if you don't trust the publisher, review the included source files yourself or run the CLI in an isolated environment. 4) If you plan to let an autonomous agent use this skill, be aware the agent will have access to perform actions (create/update/complete/delete/abandon tasks) on your TickTick account — grant only the client permissions you intend and monitor activity.

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
2. Create a new application
3. Set the redirect URI to http://localhost:8080
4. 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:

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:

# 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