todoist-api

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Todoist CLI Skill

This skill provides procedural guidance for working with Todoist using the

td

CLI tool.

本Skill提供了使用

td

CLI工具操作Todoist的流程指引。

Prerequisites

前置条件

The

td

CLI must be installed and authenticated. Verify with:

bash

td auth status

If td is not installed or not authenticated:

Not installed: Tell the user to install with
```
npm install -g @doist/todoist-cli
```
Not authenticated: Tell the user to run
```
td auth login
```
to authenticate via OAuth

必须已安装并认证

td

CLI。可通过以下命令验证：

bash

td auth status

如果未安装或未认证：

未安装: 告知用户使用
```
npm install -g @doist/todoist-cli
```
进行安装
未认证: 告知用户运行
```
td auth login
```
通过OAuth完成认证

Output Formats for Agents

面向Agent的输出格式

For machine-readable output, use these flags:

```
--json
```
- Output as JSON array
```
--ndjson
```
- Output as newline-delimited JSON (one object per line)
```
--full
```
- Include all fields in JSON output (default shows essential fields only)

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

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

Confirmation Requirement

确认要求

Before executing any destructive action, always ask the user for confirmation using AskUserQuestion or similar tool. A single confirmation suffices for a logical group of related actions.

Destructive actions include:

Deleting tasks, projects, sections, labels, or comments
Completing tasks
Updating existing resources
Archiving projects

Read-only operations do not require confirmation.

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

破坏性操作包括：

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

只读操作无需确认。

Quick Commands

快速命令

Command	Description
`td add "text"`	Quick add with natural language parsing
`td today`	Tasks due today and overdue
`td upcoming [days]`	Tasks due in next N days (default: 7)
`td inbox`	Tasks in Inbox
`td completed`	Recently completed tasks

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

Quick Add Examples

快速添加示例

bash

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

The quick add parser supports:

Due dates:
```
tomorrow
```
,
```
next monday
```
,
```
Jan 15
```
Priority:
```
p1
```
(urgent) through
```
p4
```
(normal)
Project:
```
#ProjectName
```
Section:
```
/SectionName
```
Labels:
```
@label1 @label2
```

bash

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
```

Tasks

任务

List Tasks

列出任务

bash

td task list [options]

Filters:

```
--project <name>
```
- Filter by project name or id:xxx
```
--label <name>
```
- Filter by label (comma-separated for multiple)
```
--priority <p1-p4>
```
- Filter by priority
```
--due <date>
```
- Filter by due date (today, overdue, or YYYY-MM-DD)
```
--filter <query>
```
- Raw Todoist filter query
```
--assignee <ref>
```
- Filter by assignee (me or id:xxx)
```
--workspace <name>
```
- Filter to workspace
```
--personal
```
- Filter to personal projects only

Output:

bash

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

bash

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
```
- 仅筛选个人项目

输出示例：

bash

td task list --json                    # JSON数组格式
td task list --project "Work" --json   # 筛选后的JSON格式
td task list --all --json              # 所有任务（无数量限制）

View Task Details

查看任务详情

bash

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

The ref can be a task name, partial match, or

id:xxx

bash

td task view <ref>              # 人类可读格式
td task view <ref> --json       # JSON格式输出

<ref>

参数可以是任务名称、部分匹配内容或

id:xxx

格式。

Create Task

创建任务

Quick add (natural language):

bash

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

Explicit flags:

bash

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

Options:

```
--content <text>
```
- Task content (required)
```
--due <date>
```
- Due date (natural language or YYYY-MM-DD)
```
--deadline <date>
```
- Deadline date (YYYY-MM-DD)
```
--priority <p1-p4>
```
- Priority level
```
--project <name>
```
- Project name or id:xxx
```
--section <id>
```
- Section ID
```
--labels <a,b>
```
- Comma-separated labels
```
--parent <ref>
```
- Parent task for subtask
```
--description <text>
```
- Task description
```
--assignee <ref>
```
- Assign to user (name, email, id:xxx, or "me")
```
--duration <time>
```
- Duration (e.g., 30m, 1h, 2h15m)

快速添加（自然语言）：

bash

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

显式参数：

bash

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）

Update Task

更新任务

bash

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

Options:

```
--content <text>
```
- New content
```
--due <date>
```
- New due date
```
--deadline <date>
```
- Deadline date
```
--no-deadline
```
- Remove deadline
```
--priority <p1-p4>
```
- New priority
```
--labels <a,b>
```
- Replace labels
```
--description <text>
```
- New description
```
--assignee <ref>
```
- Assign to user
```
--unassign
```
- Remove assignee
```
--duration <time>
```
- Duration

bash

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>
```
- 时长

Complete Task

完成任务

bash

td task complete <ref>

bash

td task complete <ref>

Reopen Task

重新打开任务

bash

td task uncomplete id:xxx

Note: Uncomplete requires the task ID (id:xxx format).

bash

td task uncomplete id:xxx

注意：重新打开任务需要使用任务ID（id:xxx格式）。

Delete Task

删除任务

bash

td task delete <ref>

bash

td task delete <ref>

Move Task

移动任务

bash

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

bash

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

Open in Browser

在浏览器中打开

bash

td task browse <ref>

bash

td task browse <ref>

Projects

项目

List Projects

列出项目

bash

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

bash

td project list                     # 人类可读的树形结构
td project list --json              # JSON数组格式
td project list --personal --json   # 仅列出个人项目

View Project

查看项目详情

bash

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

bash

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

Create Project

创建项目

bash

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

Options:

```
--name <name>
```
- Project name (required)
```
--color <color>
```
- Colour name
```
--parent <ref>
```
- Parent project for nesting
```
--view-style <style>
```
- "list" or "board"
```
--favorite
```
- Mark as favourite

bash

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
```
- 标记为收藏

Update Project

更新项目

bash

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

bash

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

Archive/Unarchive Project

归档/取消归档项目

bash

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

bash

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

Delete Project

删除项目

bash

td project delete <ref>

Note: Project must have no uncompleted tasks.

bash

td project delete <ref>

注意：项目必须没有未完成的任务才能删除。

List Collaborators

列出协作者

bash

td project collaborators <ref>

bash

td project collaborators <ref>

Sections

分区

List Sections

列出分区

bash

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

bash

td section list <project>           # 人类可读格式
td section list <project> --json    # JSON数组格式

Create Section

创建分区

bash

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

bash

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

Update Section

更新分区

bash

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

bash

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

Delete Section

删除分区

bash

td section delete <id>

bash

td section delete <id>

Labels

Comments

List Comments

列出评论

bash

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

bash

td comment list <task-ref>                    # 任务下的评论
td comment list <project-ref> --project       # 项目下的评论

Add Comment

添加评论

bash

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

bash

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

Update Comment

更新评论

bash

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

bash

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

Delete Comment

删除评论

bash

td comment delete <id>

bash

td comment delete <id>

Reminders

提醒

List Reminders

列出提醒

bash

td reminder list <task-ref>

bash

td reminder list <task-ref>

Add Reminder

添加提醒

bash

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

bash

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

Delete Reminder

删除提醒

bash

td reminder delete <id>

bash

td reminder delete <id>

Filters

筛选器

List Saved Filters

列出已保存的筛选器

bash

td filter list --json

bash

td filter list --json

Show Tasks Matching Filter

显示匹配筛选器的任务

bash

td filter show <filter-ref> --json

bash

td filter show <filter-ref> --json

Create Filter

创建筛选器

bash

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

bash

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

Completed Tasks

已完成任务

bash

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)

Options:

```
--since <date>
```
- Start date (YYYY-MM-DD), default: today
```
--until <date>
```
- End date (YYYY-MM-DD), default: tomorrow
```
--project <name>
```
- Filter by project

bash

td completed                              # 今日完成的任务
td completed --since 2024-01-01           # 自指定日期起完成的任务
td completed --project "Work" --json      # 筛选后的JSON格式输出
td completed --all --json                 # 所有已完成任务（无数量限制）

可选参数：

```
--since <date>
```
- 起始日期（YYYY-MM-DD格式），默认：今日
```
--until <date>
```
- 结束日期（YYYY-MM-DD格式），默认：明日
```
--project <name>
```
- 按项目筛选

Activity and Stats

活动与统计

bash

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

bash

td activity                  # 近期活动
td stats                     # 生产力统计与积分

Pagination

分页

For large result sets, use

--all

to fetch everything, or handle pagination with cursors:

bash

undefined

对于大型结果集，使用

--all

参数获取所有数据，或使用游标处理分页：

bash

undefined

First page

第一页

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

If there's a next_cursor in the response, continue

如果响应中存在next_cursor，继续获取下一页

cursor=$(echo "$result" | jq -r '.[-1].id // empty') td task list --json --limit 50 --cursor "$cursor"

undefined

cursor=$(echo "$result" | jq -r '.[-1].id // empty') td task list --json --limit 50 --cursor "$cursor"

undefined

Reference Resolution

引用解析

The

<ref>

parameter in commands accepts:

Task/project/label name (partial match supported)
```
id:xxx
```
for exact ID match
Numeric ID (interpreted as id:xxx)

命令中的

<ref>

参数支持：

任务/项目/标签的名称（支持部分匹配）
```
id:xxx
```
格式的精确ID匹配
数字ID（会被解析为id:xxx格式）

Additional Reference

额外参考

For detailed information on specific topics, consult:

```
references/completed-tasks.md
```
- Alternative methods for completed task history via API
```
references/filters.md
```
- Todoist filter query syntax for
```
--filter
```
flag

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

```
references/completed-tasks.md
```
- 通过API获取已完成任务历史的替代方法
```
references/filters.md
```
- 用于
```
--filter
```
参数的Todoist筛选查询语法

Workflow Summary

工作流总结

Verify authentication -
```
td auth status
```
Read operations - Execute directly without confirmation
Write operations - Ask for confirmation before executing
Use JSON output - Add
```
--json
```
flag for machine-readable data
Handle large datasets - Use
```
--all
```
or pagination with
```
--cursor
```

验证认证状态 -
```
td auth status
```
只读操作 - 直接执行，无需确认
写入操作 - 执行前需向用户确认
使用JSON输出 - 添加
```
--json
```
参数以获取机器可读数据
处理大型数据集 - 使用
```
--all
```
参数或通过
```
--cursor
```
进行分页

todoist-api

Original

Translation

Todoist CLI Skill

Todoist CLI Skill

Prerequisites

前置条件

Output Formats for Agents

面向Agent的输出格式

Confirmation Requirement

确认要求

Quick Commands

快速命令

Quick Add Examples

快速添加示例

Tasks

任务

List Tasks

列出任务

View Task Details

查看任务详情

Create Task

创建任务

Update Task

更新任务

Complete Task

完成任务

Reopen Task

重新打开任务

Delete Task

删除任务

Move Task

移动任务

Open in Browser

在浏览器中打开

Projects

项目

List Projects

列出项目

View Project

查看项目详情

Create Project

创建项目

Update Project

更新项目

Archive/Unarchive Project

归档/取消归档项目

Delete Project

删除项目

List Collaborators

列出协作者

Sections

分区

List Sections

列出分区

Create Section

创建分区

Update Section

更新分区

Delete Section

删除分区

Labels

标签

List Labels

列出标签

Create Label

创建标签

Update Label

更新标签

Delete Label

删除标签

Comments

评论

List Comments

列出评论

Add Comment

添加评论

Update Comment

更新评论

Delete Comment