todoist-api-skill（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

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

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.

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.

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.

Scripts

• scripts/todoist_api.py — main non-interactive Todoist CLI
• scripts/smoke_test.py — read-only connectivity check

Inspect help first:

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:

export TODOIST_API_TOKEN="YOUR_TODOIST_TOKEN"

Read-only smoke test:

python3 scripts/smoke_test.py

Sanity-check access:

python3 scripts/todoist_api.py get-projects --limit 5
python3 scripts/todoist_api.py get-labels --limit 10

Resolve names before writes:

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

Quick add

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

Create-if-missing section

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

Preview a bulk close

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

Execute the same bulk close

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

Move matching tasks into a resolved section

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

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.

Feature index

• Command catalogue and endpoint coverage → references/REFERENCE.md
• Task-first recipes → references/RECIPES.md
• Todoist-specific caveats → references/GOTCHAS.md

Escape hatches

Use raw when the public CLI surface does not yet wrap a needed endpoint:

python3 scripts/todoist_api.py raw \
  --method GET \
  --path /projects/PROJECT_ID/full

Use sync when you need incremental sync or batched commands:

python3 scripts/todoist_api.py sync \
  --sync-token '*' \
  --resource-types '["all"]'