todoist-cli
Command-line interface for Todoist.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Check it deeper on your machine
It has changed since its scan on 11 Nov 2026.
As a Claude Code plugin, install it and then ask Claude Code:
/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/todoist/todoist-cli with scanskillsafety
Or from a terminal, clone it and run it:
git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/todoist/todoist-cli'
It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.
Badge for your README
Markdown
[](/listings/doist--todoist-cli)HTML
<a href="/listings/doist--todoist-cli"><img src="/api/listings/doist--todoist-cli/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
> ```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/`.
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 <agent>
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 208 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.
- <p align="center">
- <img src="icons/td-cli.png" alt="Todoist CLI" width="150" height="150" />
- </p>
- # Todoist CLI
- A command-line interface for Todoist.
- ## Installation
- > ```bash
- > npm install -g @todoist/cli
- > ```
- Previously published as `@doist/todoist-cli`. Both packages install the `td` binary, so uninstall the old one first: `npm uninstall -g @doist/todoist-cli`.
- ### Agent Skills
- Install skills for your coding agent:
- ```bash
- 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/`.
- 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.
- ```bash
- td skill list
- td skill uninstall <agent>
- ```
- ## Uninstallation
- First, remove any installed agent skills:
- ```bash
- td skill uninstall <agent>
- ```
- Then uninstall the CLI:
- ```bash
- npm uninstall -g @todoist/cli
- ```
- ## Local Setup
- ```bash
- git clone https://github.com/todoist/todoist-cli.git
- cd todoist-cli
- npm install
- npm run build
- npm link
- ```
- This makes the `td` command available globally.
- ## Setup
- ```bash
- 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:
- ```bash
- td auth login --read-only
- ```
- To explicitly store a credential in plaintext instead of the OS credential manager:
- ```bash
- 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):
- ```bash
- 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](https://todoist.com/app/settings/integrations/developer):
- ```bash
- 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:**
- ```bash
- 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
- ```bash
- 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:
- ```bash
- td auth login
- ```
- ## Usage
- ```bash
- 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 task list --project "Work" --ids-only # one task ID per line
- td project list # all projects
- td status set "Deep work" --emoji 🎯 --for 2h # shared status; td status clear to remove
- 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.
- Supported list commands accept `--ids-only` when each result has a stable ID. It prints one
- ID per line and no human-readable empty-state text. When more pages exist, the pagination
- notice goes to stderr so stdout remains safe for pipes. `--ids-only`, `--json`, and `--ndjson`
- are mutually exclusive.
- ## 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:
- ```bash
- 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.
- ## Extensions
- Extensions add commands to `td`. An extension is an executable named `td-<name>` that runs as `td <name>`, and it can be written in any language:
- ```bash
- td extension install owner/td-standup # from GitHub
- td standup
- td extension list
- ```
- To write your own, start with `td extension create <name>` and see [docs/extensions.md](docs/extensions.md).
- ## Shell Completions
- Tab completion is available for bash, zsh, fish, and PowerShell:
- ```bash
- td completion install # prompts for shell
- td completion install bash # or: zsh, fish, pwsh
- ```
- Restart your shell or source your config file to activate. To remove:
- ```bash
- td completion uninstall
- ```
- ## Development
- ```bash
- 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
- ```
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.