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
- Create a new application
- Set the redirect URI to INLINECODE0
- Note your
Client ID and INLINECODE2
2. Authenticate
CODEBLOCK0
Headless / Manual Authentication
CODEBLOCK1
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
CODEBLOCK2
Create Task
CODEBLOCK3
Update Task
CODEBLOCK4
Complete Task
CODEBLOCK5
Abandon Task (Won't Do)
CODEBLOCK6
Batch Abandon (Multiple Tasks)
CODEBLOCK7
Note: batch-abandon requires task IDs (24-character hex strings), not task names. Use tasks --json to get task IDs first.
List Projects
CODEBLOCK8
Create Project
CODEBLOCK9
Update Project
CODEBLOCK10
Options Reference
Priority Levels
- -
none - No priority (default) - INLINECODE8 - Low priority
- INLINECODE9 - Medium priority
- INLINECODE10 - High priority
Due Date Formats
- -
today - Due today - INLINECODE12 - Due tomorrow
- INLINECODE13 - Due in N days (e.g., "in 3 days")
- INLINECODE14 - Next occurrence of weekday
- ISO date -
YYYY-MM-DD or full ISO format
Global Options
- -
--json - Output results in JSON format (useful for scripting) - INLINECODE17 - 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 - 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:
CODEBLOCK11
Configuration
Tokens are stored in ~/.clawdbot/credentials/ticktick-cli/config.json:
CODEBLOCK12
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 技能
从命令行管理 TickTick 任务和项目。
设置
1. 注册 TickTick 开发者应用
- 1. 前往 TickTick 开发者中心
- 创建新应用
- 将重定向 URI 设置为 http://localhost:8080
- 记下您的 客户端 ID 和 客户端密钥
2. 身份验证
bash
设置凭据并启动 OAuth 流程
bun run scripts/ticktick.ts auth --client-id 你的客户端ID --client-secret 你的客户端密钥
检查身份验证状态
bun run scripts/ticktick.ts auth --status
登出（清除令牌，保留凭据）
bun run scripts/ticktick.ts auth --logout
无头 / 手动身份验证
bash
在无头服务器上使用手动模式
bun run scripts/ticktick.ts auth --client-id 你的客户端ID --client-secret 你的客户端密钥 --manual
这会打印一个授权 URL。在浏览器中打开它，批准访问，然后复制完整的重定向 URL（看起来像 http://localhost:8080/?code=XXXXX&state=STATE）并粘贴回 CLI。
CLI 将打开您的浏览器以授权访问。批准后，令牌将存储在 ~/.clawdbot/credentials/ticktick-cli/config.json 中。
命令
列出任务
bash
列出所有任务
bun run scripts/ticktick.ts tasks
列出特定项目中的任务
bun run scripts/ticktick.ts tasks --list 工作
按状态筛选
bun run scripts/ticktick.ts tasks --status pending
bun run scripts/ticktick.ts tasks --status completed
JSON 输出
bun run scripts/ticktick.ts tasks --json
创建任务
bash
基本任务创建
bun run scripts/ticktick.ts task 购买杂货 --list 个人
带描述和优先级
bun run scripts/ticktick.ts task 审查 PR --list 工作 --content 检查新的身份验证更改 --priority high
带截止日期
bun run scripts/ticktick.ts task 提交报告 --list 工作 --due tomorrow
bun run scripts/ticktick.ts task 计划假期 --list 个人 --due in 7 days
bun run scripts/ticktick.ts task 会议 --list 工作 --due 2024-12-25
带标签
bun run scripts/ticktick.ts task 研究 --list 工作 --tag research important
更新任务
bash
按任务名称或 ID 更新
bun run scripts/ticktick.ts task 购买杂货 --update --priority medium
bun run scripts/ticktick.ts task abc123 --update --due tomorrow --content 更新后的备注
限制搜索到特定项目
bun run scripts/ticktick.ts task 审查 PR --update --list 工作 --priority low
完成任务
bash
将任务标记为完成
bun run scripts/ticktick.ts complete 购买杂货
带项目筛选的完成
bun run scripts/ticktick.ts complete 审查 PR --list 工作
放弃任务（不做）
bash
将任务标记为不做
bun run scripts/ticktick.ts abandon 旧任务
带项目筛选的放弃
bun run scripts/ticktick.ts abandon 过时项目 --list 待办
批量放弃（多个任务）
bash
在单个 API 调用中放弃多个任务
bun run scripts/ticktick.ts batch-abandon <任务ID1> <任务ID2> <任务ID3>
带 JSON 输出
bun run scripts/ticktick.ts batch-abandon abc123def456... xyz789... --json
注意：batch-abandon 需要任务 ID（24 字符十六进制字符串），而不是任务名称。先使用 tasks --json 获取任务 ID。
列出项目
bash
列出所有项目
bun run scripts/ticktick.ts lists
JSON 输出
bun run scripts/ticktick.ts lists --json
创建项目
bash
创建新项目
bun run scripts/ticktick.ts list 新项目
带颜色
bun run scripts/ticktick.ts list 工作任务 --color #FF5733
更新项目
bash
重命名项目
bun run scripts/ticktick.ts list 旧名称 --update --name 新名称
更改颜色
bun run scripts/ticktick.ts list 工作 --update --color #00FF00
选项参考
优先级级别
- - none - 无优先级（默认）
- low - 低优先级
- medium - 中优先级
- high - 高优先级
截止日期格式
- - today - 今天到期
- tomorrow - 明天到期
- in N days - N 天后到期（例如 in 3 days）
- next monday - 下一个工作日
- ISO 日期 - YYYY-MM-DD 或完整 ISO 格式
全局选项
- - --json - 以 JSON 格式输出结果（适用于脚本编写）
- --help - 显示任何命令的帮助信息
代理使用提示
当将此技能用作 AI 代理时：
- 1. 始终使用 --json 标志 以获得机器可读的输出
- 首先列出项目 使用 lists --json 获取有效的项目 ID
- 尽可能使用项目 ID 而不是名称以确保可靠性
- 在完成前检查任务状态 以避免错误
示例代理工作流程：
bash
1. 获取可用项目
bun run scripts/ticktick.ts lists --json
2. 在特定项目中创建任务
bun run scripts/ticktick.ts task 代理任务 --list 项目ID --priority high --json
3. 稍后，将其标记为完成
bun run scripts/ticktick.ts complete 代理任务 --list 项目ID --json
配置
令牌存储在 ~/.clawdbot/credentials/ticktick-cli/config.json 中：
json
{
clientId: 你的客户端ID,
clientSecret: 你的客户端密钥,
accessToken: ...,
refreshToken: ...,
tokenExpiry: 1234567890000,
redirectUri: http://localhost:8080
}
注意：凭据以明文存储。CLI 尝试将文件权限设置为 700/600；请将此文件视为敏感文件。
CLI 会在令牌过期时自动刷新。
故障排除
未认证 错误
运行 bun run scripts/ticktick.ts auth 进行身份验证。
未找到项目 错误
使用 bun run scripts/ticktick.ts lists 查看可用项目及其 ID。
未找到任务 错误
- - 检查任务标题是否完全匹配（不区分大小写）
- 尝试使用任务 ID 代替
- 使用 --list 将搜索范围缩小到特定项目
令牌过期错误
CLI 应自动刷新令牌。如果问题仍然存在，请再次运行 bun run scripts/ticktick.ts auth。
API 说明
此 CLI 使用 TickTick 开放 API v1。
速率限制
- - 每分钟 100 次请求
- 每 5 分钟 300 次请求
CLI 每次操作会进行多次 API 调用（列出项目以查找任务），因此批量操作可能很快达到限制。
批量端点
CLI 支持 TickTick 的批量端点进行批量操作：
POST https://api.ticktick.com/open/v1/batch/task
{
add: [...], // CreateTaskInput[]
update: [...], // UpdateTaskInput[]
delete: [...] // { taskId, projectId }[]
}
使用 batch-abandon 在单个 API 调用中放弃多个任务。批量 API 方法也可用于编程使用。
其他限制
- - 每个项目最多 500 个任务
- API 不支持某些高级功能（专注时间、习惯）
