Todoist CLI

A command-line interface for Todoist.

Installation

npm install -g @doist/todoist-cli

Agent Skills

Install skills for your coding agent:

td skill install claude-code
td skill install codex
td skill install copilot
td skill install cursor
td skill install gemini
td skill install pi
td skill install universal

Skills are installed to ~//skills/todoist-cli/SKILL.md (e.g. ~/.claude/ for claude-code, ~/.agents/ for universal, etc.). When updating the CLI, installed skills are updated automatically. The universal agent is compatible with Amp, OpenCode, and other agents that read from ~/.agents/.

The gemini agent installs to ~/.gemini/config/skills/todoist-cli/SKILL.md, the global location read by Antigravity, Antigravity CLI and Antigravity IDE alike. For project-scoped Antigravity skills use td skill install universal --local, which writes to .agents/skills/ — the workspace directory Antigravity reads.

td skill list
td skill uninstall 

Uninstallation

First, remove any installed agent skills:

td skill uninstall 

Then uninstall the CLI:

npm uninstall -g @doist/todoist-cli

Local Setup

git clone https://github.com/Doist/todoist-cli.git
cd todoist-cli
npm install
npm run build
npm link

This makes the td command available globally.

Setup

td auth login

This opens your browser to authenticate with Todoist. Once approved, the token is stored in your OS credential manager:

• macOS: Keychain
• Windows: Credential Manager
• Linux: Secret Service/libsecret

Secure storage is required by default. If it is unavailable, login fails without writing a credential to disk. To explicitly use plaintext config-file storage, pass --credential-store=plaintext; the CLI always prints a warning when it writes a credential this way. Existing plaintext tokens are migrated automatically the next time the CLI reads them successfully from the config file.

For a read-only OAuth token (scope data:read), run:

td auth login --read-only

To explicitly store a credential in plaintext instead of the OS credential manager:

td auth login --credential-store=plaintext

In read-only mode, commands that change Todoist data (create/update/delete/complete/move/archive, etc.) are blocked by the CLI.

Some commands need opt-in OAuth scopes, requested via --additional-scopes=<list> (comma-separated):

td auth login --additional-scopes=app-management   # td apps ...
td auth login --additional-scopes=backups           # td backup ...
td auth login --additional-scopes=billing           # td billing ...

Run td auth login --help for the full list. When a command fails for lack of a scope, the error suggests a re-login command that preserves whichever flags were originally used.

Alternative methods

Manual token: Get your API token from Todoist Settings > Integrations > Developer:

td auth token "your-token"

Manual tokens use the system credential manager by default too. To explicitly store one in plaintext, add --credential-store=plaintext; the CLI prints a warning after the write.

Environment variable:

export TODOIST_API_TOKEN="your-token"

TODOIST_API_TOKEN always takes priority over the stored token.