Todoist CLI

A command-line interface for Todoist.

Installation

bash 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 ~/<agent-dir>/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/.

td skill list
td skill uninstall <agent>

Uninstallation

First, remove any installed agent skills:

td skill uninstall <agent>

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

If secure storage is unavailable, the CLI warns and falls back to ~/.config/todoist-cli/config.json. 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

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"

Environment variable:

export TODOIST_API_TOKEN="your-token"

TODOIST_API_TOKEN always takes priority over the stored token.

Note: externally provided tokens (TODOIST_API_TOKEN or td auth token) are treated as unknown scope and assumed write-capable. The CLI cannot currently auto-detect OAuth scope for these tokens.

Auth commands

td auth status   # check if authenticated + mode (read-only/read-write/unknown)
td auth logout   # remove saved token and auth metadata

To switch back to normal write access, re-run:

td auth login

Usage

td add "Buy milk tomorrow #Shopping"   # quick add with natural language
td today                               # tasks due today + overdue
td inbox                               # inbox tasks
td task list                           # all tasks
td task list --project "Work"          # tasks in project
td project list                        # all projects
td task view https://app.todoist.com/app/task/buy-milk-8Jx4mVr72kPn3QwB  # paste a URL

Run td --help or td <command> --help for more options.

Accessibility

For users who rely on screen readers or cannot distinguish colors, use the --accessible flag or set TD_ACCESSIBLE=1 to add text labels to color-coded output:

td today --accessible
# or
export TD_ACCESSIBLE=1
td today

When active, due dates get a due: prefix, deadlines get a deadline: prefix, durations get a ~ prefix, and favorite items get a ★ suffix. Default output without the flag is unchanged.

Shell Completions

Tab completion is available for bash, zsh, and fish:

td completion install        # prompts for shell
td completion install bash   # or: zsh, fish

Restart your shell or source your config file to activate. To remove:

td completion uninstall

Development

npm install
npm run build       # compile
npm run dev         # watch mode
npm run type-check  # type check
npm run fix         # auto-fix lint + format
npm test            # run tests