Back to Details

todoist-api

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Todoist API

Todoist API

When to use this skill

何时使用此技能

Use this skill when work involves Todoist data or automation, especially:
  • capture or quick-add new tasks
  • inspect, filter, move, complete, reopen, or delete tasks
  • manage projects, sections, labels, or comments
  • resolve human names to Todoist IDs before writing
  • perform safer bulk edits with dry-runs
  • review completed work or recent activity
  • build Todoist scripts, agents, or integrations around the public API
当工作涉及Todoist数据或自动化时使用此技能，尤其是以下场景：
  • 捕获或快速添加新任务
  • 查看、筛选、移动、完成、重新打开或删除任务
  • 管理项目、分区、标签或评论
  • 在写入操作前将人工命名的名称解析为Todoist ID
  • 通过预演（dry-run）执行更安全的批量编辑
  • 查看已完成工作或近期活动
  • 围绕公开API构建Todoist脚本、Agent或集成

When not to use this skill

何时不使用此技能

Do not use this skill for:
  • editing the user’s local Todoist app UI directly
  • calendar-specific workflows that belong in a calendar skill
  • attachment upload flows that require multipart handling unless you are prepared to use 
    curl
    or the 
    raw
    escape hatch
  • non-Todoist task systems
请勿在以下场景使用此技能：
  • 直接编辑用户本地Todoist应用的UI
  • 属于日历技能的特定日历工作流
  • 需要多部分处理的附件上传流程（除非你准备使用
    curl
    或
    raw
    兜底方案）
  • 非Todoist的任务管理系统

Safety defaults

安全默认设置

  • Start read-only if the user’s intent is ambiguous.
  • Resolve names to IDs before any write.
  • Prefer close over delete unless the user explicitly wants permanent removal.
  • Run 
    --dry-run
    first for bulk or destructive work.
  • Use 
    --confirm
    for bulk closes, moves, repeated comments, and deletes.
  • If a command may return a large payload, set 
    --output FILE
    so stdout stays small and predictable.
  • 如果用户意图不明确，先以只读模式开始操作。
  • 在执行任何写入操作前，将名称解析为ID。
  • 除非用户明确要求永久删除，否则优先选择关闭（close）而非删除（delete）。
  • 对于批量或破坏性操作，先运行
    --dry-run
    预演。
  • 执行批量关闭、移动、重复评论和删除操作时，使用
    --confirm
    确认。
  • 如果命令可能返回大体积结果，设置
    --output FILE
    ，使标准输出保持小巧且可预测。

Pick the smallest capable surface

选择最小适用范围

  • One object, one endpoint → use a low-level REST wrapper such as 
    get-task
    , 
    update-project
    , or 
    get-comment
    .
  • Natural-language capture → use 
    quick-add-task
    .
  • Resolve names safely → use 
    resolve-project
    , 
    resolve-section
    , 
    resolve-label
    .
  • Create if missing → use 
    ensure-project
    , 
    ensure-section
    , 
    ensure-label
    .
  • Many matching tasks → use 
    bulk-close-tasks
    , 
    bulk-move-tasks
    , 
    bulk-comment-tasks
    .
  • Completed-work review → use 
    report-completed
    or 
    get-completed-tasks
    .
  • Full or incremental sync / batched writes → use 
    sync
    .
  • Unwrapped or niche endpoint → use 
    raw
    .
  • 单个对象，单个端点 → 使用低级REST封装，如
    get-task
    、
    update-project
    或
    get-comment
    。
  • 自然语言捕获 → 使用
    quick-add-task
    。
  • 安全解析名称 → 使用
    resolve-project
    、
    resolve-section
    、
    resolve-label
    。
  • 不存在则创建 → 使用
    ensure-project
    、
    ensure-section
    、
    ensure-label
    。
  • 多个匹配任务 → 使用
    bulk-close-tasks
    、
    bulk-move-tasks
    、
    bulk-comment-tasks
    。
  • 已完成工作回顾 → 使用
    report-completed
    或
    get-completed-tasks
    。
  • 全量或增量同步 / 批量写入 → 使用
    sync
    。
  • 未封装或小众端点 → 使用
    raw
    。

Output contract

输出约定

The main script prints structured output to stdout by default.
  • --format json
    returns a stable JSON envelope with fields like 
    action
    , 
    ok
    , 
    count
    , 
    next_cursor
    , 
    matched_count
    , 
    changed_count
    , and 
    resolved
    .
  • --format summary
    returns a smaller human-readable summary.
  • --output FILE
    writes the full output to a file and prints a small JSON notice to stdout.
This is designed for agent pipelines: stdout stays parseable, stderr carries diagnostics, and retries are built in for transient failures.
主脚本默认向标准输出打印结构化结果。
  • --format json
    返回稳定的JSON包，包含
    action
    、
    ok
    、
    count
    、
    next_cursor
    、
    matched_count
    、
    changed_count
    和
    resolved
    等字段。
  • --format summary
    返回更简洁的人类可读摘要。
  • --output FILE
    将完整输出写入文件，并向标准输出打印一个小型JSON通知。
此设计适用于Agent流水线：标准输出保持可解析，标准错误输出承载诊断信息，且内置了针对临时故障的重试机制。

Scripts

脚本

  • scripts/todoist_api.py
     — main non-interactive Todoist CLI
  • scripts/smoke_test.py
     — read-only connectivity check
Inspect help first:
bash
python3 scripts/todoist_api.py --help
python3 scripts/todoist_api.py get-tasks-by-filter --help
python3 scripts/todoist_api.py bulk-move-tasks --help
python3 scripts/smoke_test.py --help
  • scripts/todoist_api.py
     — 主要的非交互式Todoist CLI工具
  • scripts/smoke_test.py
     — 只读连通性检查工具
先查看帮助信息：
bash
python3 scripts/todoist_api.py --help
python3 scripts/todoist_api.py get-tasks-by-filter --help
python3 scripts/todoist_api.py bulk-move-tasks --help
python3 scripts/smoke_test.py --help

Quick start

快速开始

Set a token:
bash
export TODOIST_API_TOKEN="YOUR_TODOIST_TOKEN"
Read-only smoke test:
bash
python3 scripts/smoke_test.py
Sanity-check access:
bash
python3 scripts/todoist_api.py get-projects --limit 5
python3 scripts/todoist_api.py get-labels --limit 10
Resolve names before writes:
bash
python3 scripts/todoist_api.py resolve-project --name "Inbox"
python3 scripts/todoist_api.py resolve-section --project-name "Client Alpha" --name "Next Actions"
python3 scripts/todoist_api.py resolve-label --name "waiting-on"
设置令牌：
bash
export TODOIST_API_TOKEN="YOUR_TODOIST_TOKEN"
只读连通性测试：
bash
python3 scripts/smoke_test.py
验证访问权限：
bash
python3 scripts/todoist_api.py get-projects --limit 5
python3 scripts/todoist_api.py get-labels --limit 10
写入操作前解析名称：
bash
python3 scripts/todoist_api.py resolve-project --name "Inbox"
python3 scripts/todoist_api.py resolve-section --project-name "Client Alpha" --name "Next Actions"
python3 scripts/todoist_api.py resolve-label --name "waiting-on"

High-value agent workflows

高价值Agent工作流

Quick add

快速添加

bash
python3 scripts/todoist_api.py quick-add-task \
  --text "Email Chris tomorrow at 09:00 #Work @follow-up p2"
bash
python3 scripts/todoist_api.py quick-add-task \
  --text "Email Chris tomorrow at 09:00 #Work @follow-up p2"

Create-if-missing section

不存在则创建分区

bash
python3 scripts/todoist_api.py ensure-section \
  --project-name "Client Alpha" \
  --name "Next Actions"
bash
python3 scripts/todoist_api.py ensure-section \
  --project-name "Client Alpha" \
  --name "Next Actions"

Preview a bulk close

预演批量关闭

bash
python3 scripts/todoist_api.py bulk-close-tasks \
  --filter "overdue & @errands" \
  --dry-run
bash
python3 scripts/todoist_api.py bulk-close-tasks \
  --filter "overdue & @errands" \
  --dry-run

Execute the same bulk close

执行相同的批量关闭

bash
python3 scripts/todoist_api.py bulk-close-tasks \
  --filter "overdue & @errands" \
  --confirm
bash
python3 scripts/todoist_api.py bulk-close-tasks \
  --filter "overdue & @errands" \
  --confirm

Move matching tasks into a resolved section

将匹配任务移动到已解析的分区

bash
python3 scripts/todoist_api.py bulk-move-tasks \
  --filter "#Inbox & !recurring" \
  --target-project-name "Work" \
  --target-section-name "Next Actions" \
  --dry-run
bash
python3 scripts/todoist_api.py bulk-move-tasks \
  --filter "#Inbox & !recurring" \
  --target-project-name "Work" \
  --target-section-name "Next Actions" \
  --dry-run

Report completed work

生成已完成工作报告

bash
python3 scripts/todoist_api.py report-completed \
  --since "2026-03-01T00:00:00Z" \
  --until "2026-03-31T23:59:59Z" \
  --by completion \
  --output reports/march-completed.json
bash
python3 scripts/todoist_api.py report-completed \
  --since "2026-03-01T00:00:00Z" \
  --until "2026-03-31T23:59:59Z" \
  --by completion \
  --output reports/march-completed.json

Recommended operating pattern

推荐操作流程

  1. Resolve or list the target object.
  2. Read current state with a low-level getter.
  3. Preview the write with 
    --dry-run
    .
  4. Execute with 
    --confirm
    when needed.
  5. Verify by re-reading or by running a report command.
  1. 解析或列出目标对象。
  2. 使用低级获取命令读取当前状态。
  3. 使用
    --dry-run
    预演写入操作。
  4. 需要时使用
    --confirm
    执行操作。
  5. 通过重新读取或运行报告命令验证结果。

Feature index

功能索引

  • Command catalogue and endpoint coverage → references/REFERENCE.md
  • Task-first recipes → references/RECIPES.md
  • Todoist-specific caveats → references/GOTCHAS.md
  • 命令目录与端点覆盖 → references/REFERENCE.md
  • 任务优先方案 → references/RECIPES.md
  • Todoist特定注意事项 → references/GOTCHAS.md

Escape hatches

兜底方案

Use 
raw
when the public CLI surface does not yet wrap a needed endpoint:
bash
python3 scripts/todoist_api.py raw \
  --method GET \
  --path /projects/PROJECT_ID/full
Use 
sync
when you need incremental sync or batched commands:
bash
python3 scripts/todoist_api.py sync \
  --sync-token '*' \
  --resource-types '["all"]'
当公开CLI尚未封装所需端点时，使用
raw
：
bash
python3 scripts/todoist_api.py raw \
  --method GET \
  --path /projects/PROJECT_ID/full
当你需要增量同步或批量命令时，使用
sync
：
bash
python3 scripts/todoist_api.py sync \
  --sync-token '*' \
  --resource-types '["all"]'