Ticktick Cli

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

Security Scan

The skill appears to implement a legitimate TickTick CLI, but there are packaging and disclosure inconsistencies (notably the runtime requirement for Bun is not declared and credentials are stored in plaintext), so you should review and trust the source before installing.

Purpose & Capability

The code and SKILL.md match the stated purpose (TickTick task/project management via OAuth). However the skill's metadata declares no required binaries while the instructions and scripts use the Bun runtime (commands like 'bun run scripts/ticktick.ts' and a #!/usr/bin/env bun shebang). The absence of a declared required binary for Bun is an inconsistency that could cause confusion or unexpected behavior.

Instruction Scope

Runtime instructions and included code stay within the stated purpose: initiating OAuth with TickTick, calling TickTick API endpoints (api.ticktick.com), and providing task/project CRUD operations. The SKILL.md and code explicitly document where tokens are stored and how auth flows work. No instructions attempt to read unrelated system files or send data to external endpoints other than TickTick's OAuth/API hosts.

Install Mechanism

There is no install spec (instruction-only), but the package actually includes runnable source files and a package.json. The runtime assumes Bun is available; dependencies (commander, open) are standard Node-style deps. Nothing is downloaded from unknown URLs and no archive extraction occurs. Still, packaging as 'no install' while providing code that requires Bun is a packaging mismatch to be aware of.

Credentials

The skill asks for no environment variables and the only secrets required are the TickTick OAuth client ID/secret provided interactively or via CLI flags — which is appropriate for an OAuth-based CLI. There are not multiple unrelated credentials requested.

Persistence & Privilege

The CLI writes its own credentials to ~/.clawdbot/credentials/ticktick-cli/config.json and attempts to set restrictive permissions. It does not modify other skills or system-wide configuration. always:false and normal agent invocation are used.

What to consider before installing

This skill is functionally coherent with a TickTick CLI, but note two things before installing: (1) the skill and SKILL.md assume the Bun runtime (commands use 'bun run' and the main script has a bun shebang), yet the metadata does not list Bun as a required binary — make sure Bun is installed and that you trust running Bun scripts from this source. (2) OAuth tokens and your client secret are stored in plaintext at ~/.clawdbot/credentials/ticktick-cli/config.json (the code tries to set 700/600 perms but the file is still plaintext); treat this file as sensitive or consider storing credentials in a secure vault instead. Verify the skill's source/owner, and if you need stronger guarantees, inspect the included scripts locally before running them.

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