Todoist API

Manages Todoist tasks, projects, sections, labels, comments, completed-task reports, activity logs, ID migration, project templates, and sync workflows throu...

Security Scan

The skill is a plausible Todoist API wrapper with sensible safety defaults, but the registry metadata omits the fact that it requires a Todoist API token and the CLI supports a base_url override — verify token handling and the metadata before installing.

Purpose & Capability

The skill's name, description, and included scripts clearly target the Todoist REST API and the required capabilities (task/project/label management) match the code. However, the registry metadata lists no required environment variables or primary credential while both SKILL.md and the scripts expect a Todoist API token (TODOIST_API_TOKEN or TODOIST_TOKEN). This mismatch is incoherent: a Todoist integration legitimately needs an API token and the registry should declare that.

Instruction Scope

Runtime instructions and scripts stay within the Todoist API domain: they use api.todoist.com, support dry-run/confirm semantics, and the 'raw' and 'sync' escape hatches are documented. The CLI accepts --base-url which can point to an alternate host: this is a legitimate testing/compatibility feature but could be abused to send tokens to a non-Todoist endpoint if misused. The instructions do not ask for unrelated system files or unrelated credentials.

Install Mechanism

No install spec is provided (instruction-only with bundled Python scripts). Nothing is downloaded at install time; risk from install mechanism is low. The presence of code files means the code will run on the host, so the user should review the included scripts before executing.

Credentials

The skill legitimately requires a single Todoist API token (TODOIST_API_TOKEN or TODOIST_TOKEN), which is proportionate to its purpose. The concern is that the registry metadata does not declare this required credential (required env vars: none, primary credential: none), creating an information gap and increasing the chance a user might unwittingly expose secrets. No other unrelated credentials are requested.

Persistence & Privilege

The skill does not request persistent/always-on inclusion (always: false) and does not modify other skills or system-wide settings. Autonomous invocation is enabled (platform default) but not combined with other broad privileges here.

What to consider before installing

This skill appears to be a legitimate Todoist API helper, but take these precautions before installing or running it: 1) The scripts expect a Todoist token (TODOIST_API_TOKEN / TODOIST_TOKEN) even though the registry metadata doesn't declare one — do not provide your token unless you trust the source. 2) Inspect scripts/todoist_api.py and smoke_test.py yourself (they are included) to confirm there are no unexpected network endpoints; the code defaults to api.todoist.com but allows --base-url (avoid pointing that to unknown hosts). 3) Run the read-only smoke_test first in an isolated environment with a token of limited scope or a throwaway account to verify behavior. 4) Prefer using --dry-run and --confirm for any write/bulk operations. 5) Ask the publisher to correct the registry metadata to list TODOIST_API_TOKEN (or make the credential requirement explicit) before installing in production. If you cannot verify these points, treat the skill as unsafe to receive your real Todoist token.

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