todoist-api

Todoist CLI 技能

此技能提供使用 td CLI 工具操作 Todoist 的流程指南。

前提条件

必须安装并完成身份验证的 td CLI。使用以下命令验证：

td auth status

如果未安装或未完成身份验证：

• 未安装：告知用户使用 npm install -g @doist/todoist-cli 安装
• 未完成身份验证：告知用户运行 td auth login，通过 OAuth 进行身份验证

Agent 输出格式

如需机器可读的输出，请使用以下标志：

• --json - 以 JSON 数组形式输出
• --ndjson - 以按行分隔的 JSON 形式输出（每行一个对象）
• --full - 在 JSON 输出中包含所有字段（默认仅显示必要字段）

确认要求

执行任何破坏性操作前，务必使用 AskUserQuestion 或类似工具征求用户确认。 对一组逻辑相关的操作，只需确认一次。

破坏性操作包括：

• 删除任务、项目、分区、标签或评论
• 完成任务
• 更新现有资源
• 归档项目

只读操作无需确认。

快速命令

命令	描述
td add "text"	使用自然语言解析快速添加
td today	今天到期和已逾期的任务
td upcoming [days]	未来 N 天内到期的任务（默认：7）
td inbox	收件箱中的任务
td completed	最近完成的任务

快速添加示例

td add "Buy milk tomorrow p1 #Shopping"
td add "Call dentist every monday @health"
td add "Review PR #Work /Code Review"

快速添加解析器支持：

• 到期日期：tomorrow、next monday、Jan 15
• 优先级：从 p1（紧急）到 p4（普通）
• 项目：#ProjectName
• 分区：/SectionName
• 标签：@label1 @label2

任务

列出任务

td task list [options]

筛选条件：

• --project <name> - 按项目名称或 id:xxx 筛选
• --label <name> - 按标签筛选（多个标签以逗号分隔）
• --priority <p1-p4> - 按优先级筛选
• --due <date> - 按到期日期筛选（today、overdue 或 YYYY-MM-DD）
• --filter <query> - 原始 Todoist 筛选查询
• --assignee <ref> - 按受派人筛选（me 或 id:xxx）
• --workspace <name> - 筛选指定工作区
• --personal - 仅筛选个人项目

输出：

td task list --json                    # JSON array
td task list --project "Work" --json   # Filtered JSON
td task list --all --json              # All tasks (no limit)

查看任务详情

td task view <ref>              # Human-readable
td task view <ref> --json       # JSON output

ref 可以是任务名称、部分匹配内容或 id:xxx。

创建任务

快速添加（自然语言）：

td add "Task text with #Project @label tomorrow p2"

显式标志：

td task add --content "Task text" \
  --project "Work" \
  --due "tomorrow" \
  --priority p2 \
  --labels "urgent,review" \
  --description "Additional details"

选项：

• --content <text> - 任务内容（必填）
• --due <date> - 到期日期（自然语言或 YYYY-MM-DD）
• --deadline <date> - 截止日期（YYYY-MM-DD）
• --priority <p1-p4> - 优先级
• --project <name> - 项目名称或 id:xxx
• --section <id> - 分区 ID
• --labels <a,b> - 以逗号分隔的标签
• --parent <ref> - 父任务，用于创建子任务
• --description <text> - 任务描述
• --assignee <ref> - 指派给用户（名称、电子邮件、id:xxx 或 "me"）
• --duration <time> - 时长（例如，30m、1h、2h15m）

更新任务

td task update <ref> --content "New content" --due "next week"

选项：

• --content <text> - 新内容
• --due <date> - 新到期日期
• --deadline <date> - 截止日期
• --no-deadline - 移除截止日期
• --priority <p1-p4> - 新优先级
• --labels <a,b> - 替换标签
• --description <text> - 新描述
• --assignee <ref> - 指派给用户
• --unassign - 移除受派人
• --duration <time> - 时长

完成任务

td task complete <ref>

重新打开任务

td task uncomplete id:xxx

注意：取消完成状态需要任务 ID（id:xxx 格式）。

删除任务

td task delete <ref>

移动任务

td task move <ref> --project "New Project"
td task move <ref> --section <section-id>
td task move <ref> --parent <task-ref>

在浏览器中打开

td task browse <ref>

项目

列出项目

td project list                     # Human-readable tree
td project list --json              # JSON array
td project list --personal --json   # Personal projects only

查看项目

td project view <ref>
td project view <ref> --json

创建项目

td project create --name "Project Name" \
  --color "blue" \
  --parent "Parent Project" \
  --view-style board \
  --favorite

选项：

• --name <name> - 项目名称（必填）
• --color <color> - 颜色名称
• --parent <ref> - 父项目，用于嵌套
• --view-style <style> - "list" 或 "board"
• --favorite - 标记为收藏

更新项目

td project update <ref> --name "New Name" --color "red"

归档/取消归档项目

td project archive <ref>
td project unarchive <ref>

删除项目

td project delete <ref>

注意：项目中不得有未完成的任务。

列出协作者

td project collaborators <ref>

分区

列出分区

td section list <project>           # Human-readable
td section list <project> --json    # JSON array

创建分区

td section create --name "Section Name" --project "Project Name"

更新分区

td section update <id> --name "New Name"

删除分区

td section delete <id>

标签

列出标签

td label list              # Human-readable
td label list --json       # JSON array

创建标签

td label create --name "label-name" --color "green" --favorite

更新标签

td label update <ref> --name "new-name" --color "blue"

删除标签

td label delete <name>

评论

列出评论

td comment list <task-ref>                    # Comments on task
td comment list <project-ref> --project       # Comments on project

添加评论

td comment add <task-ref> --content "Comment text"
td comment add <project-ref> --project --content "Comment text"

更新评论

td comment update <id> --content "Updated text"

删除评论

td comment delete <id>

提醒

列出提醒

td reminder list <task-ref>

添加提醒

td reminder add <task-ref> --due "tomorrow 9am"

删除提醒

td reminder delete <id>

过滤器

列出已保存的过滤器

td filter list --json

显示符合过滤器条件的任务

td filter show <filter-ref> --json

创建过滤器

td filter create --name "My Filter" --query "today & p1"

已完成的任务

td completed                              # Today's completed tasks
td completed --since 2024-01-01           # Since specific date
td completed --project "Work" --json      # Filtered JSON output
td completed --all --json                 # All completed (no limit)

选项：

• --since <date> - 开始日期（YYYY-MM-DD），默认值：今天
• --until <date> - 结束日期（YYYY-MM-DD），默认值：明天
• --project <name> - 按项目筛选

活动和统计数据

td activity                  # Recent activity
td stats                     # Productivity stats and karma

分页

对于大型结果集，可使用 --all 获取全部内容，或使用游标处理分页：

# First page
result=$(td task list --json --limit 50)

# If there's a next_cursor in the response, continue
cursor=$(echo "$result" | jq -r '.[-1].id // empty')
td task list --json --limit 50 --cursor "$cursor"

引用解析

命令中的 <ref> 参数接受：

• 任务／项目／标签名称（支持部分匹配）
• id:xxx 用于精确匹配 ID
• 数字 ID（会被解释为 id:xxx）

其他参考资料

如需特定主题的详细信息，请参阅：

• references/completed-tasks.md - 通过 API 获取已完成任务历史记录的替代方法
• references/filters.md - --filter 标志所用的 Todoist 过滤器查询语法

工作流摘要

1. 验证身份验证状态 - td auth status
2. 读取操作 - 无需确认，直接执行
3. 写入操作 - 执行前请先征求确认
4. 使用 JSON 输出 - 添加 --json 标志以获取机器可读数据
5. 处理大型数据集 - 使用 --all 或通过 --cursor 分页