todoist-api

Original：🇺🇸 English
Translated
2 scripts

Manages Todoist tasks, projects, sections, labels, comments, completed-task reports, activity logs, ID migration, project templates, and sync workflows through Todoist API v1. Use when the user asks to capture tasks, quick-add work, triage an inbox, resolve Todoist names to IDs, bulk-close or move tasks, add repeated comments, review completed work, manage project structure, export templates, or automate Todoist workflows.

5installs
Sourcetristanmanchester/agent-skills
Added on

NPX Install

npx skill4agent add tristanmanchester/agent-skills todoist-api

Tags

Translated version includes tags in frontmatter
todoist-apitask-automationcli-toolworkflow-automationproject-management

SKILL.md Content

View Translation Comparison →

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:
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"

High-value agent workflows

Quick add

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"

Preview a bulk close

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

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

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

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:
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"]'