Skip to content
Back to search

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.

Checked today

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
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/doist--todoist-cli/badge.svg)](/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

i

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.

  1. <p align="center">
  2. <img src="icons/td-cli.png" alt="Todoist CLI" width="150" height="150" />
  3. </p>
  4. # Todoist CLI
  5. A command-line interface for Todoist.
  6. ## Installation
  7. > ```bash
  8. > npm install -g @todoist/cli
  9. > ```
  10. Previously published as `@doist/todoist-cli`. Both packages install the `td` binary, so uninstall the old one first: `npm uninstall -g @doist/todoist-cli`.
  11. ### Agent Skills
  12. Install skills for your coding agent:
  13. ```bash
  14. td skill install claude-code
  15. td skill install codex
  16. td skill install copilot
  17. td skill install cursor
  18. td skill install gemini
  19. td skill install pi
  20. td skill install universal
  21. ```
  22. 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/`.
  23. 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.
  24. ```bash
  25. td skill list
  26. td skill uninstall <agent>
  27. ```
  28. ## Uninstallation
  29. First, remove any installed agent skills:
  30. ```bash
  31. td skill uninstall <agent>
  32. ```
  33. Then uninstall the CLI:
  34. ```bash
  35. npm uninstall -g @todoist/cli
  36. ```
  37. ## Local Setup
  38. ```bash
  39. git clone https://github.com/todoist/todoist-cli.git
  40. cd todoist-cli
  41. npm install
  42. npm run build
  43. npm link
  44. ```
  45. This makes the `td` command available globally.
  46. ## Setup
  47. ```bash
  48. td auth login
  49. ```
  50. This opens your browser to authenticate with Todoist. Once approved, the token is stored in your OS credential manager:
  51. - macOS: Keychain
  52. - Windows: Credential Manager
  53. - Linux: Secret Service/libsecret
  54. 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.
  55. For a read-only OAuth token (scope `data:read`), run:
  56. ```bash
  57. td auth login --read-only
  58. ```
  59. To explicitly store a credential in plaintext instead of the OS credential manager:
  60. ```bash
  61. td auth login --credential-store=plaintext
  62. ```
  63. In read-only mode, commands that change Todoist data (create/update/delete/complete/move/archive, etc.) are blocked by the CLI.
  64. Some commands need opt-in OAuth scopes, requested via `--additional-scopes=<list>` (comma-separated):
  65. ```bash
  66. td auth login --additional-scopes=app-management # td apps ...
  67. td auth login --additional-scopes=backups # td backup ...
  68. td auth login --additional-scopes=billing # td billing ...
  69. ```
  70. 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.
  71. ### Alternative methods
  72. **Manual token:** Get your API token from [Todoist Settings > Integrations > Developer](https://todoist.com/app/settings/integrations/developer):
  73. ```bash
  74. td auth token "your-token"
  75. ```
  76. Manual tokens use the system credential manager by default too. To explicitly store one
  77. in plaintext, add `--credential-store=plaintext`; the CLI prints a warning after the write.
  78. **Environment variable:**
  79. ```bash
  80. export TODOIST_API_TOKEN="your-token"
  81. ```
  82. `TODOIST_API_TOKEN` always takes priority over the stored token.
  83. 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.
  84. ### Auth commands
  85. ```bash
  86. td auth status # check if authenticated + mode (read-only/read-write/unknown)
  87. td auth logout # remove saved token and auth metadata
  88. ```
  89. To switch back to normal write access, re-run:
  90. ```bash
  91. td auth login
  92. ```
  93. ## Usage
  94. ```bash
  95. td add "Buy milk tomorrow #Shopping" # quick add with natural language
  96. td today # tasks due today + overdue
  97. td inbox # inbox tasks
  98. td task list # all tasks
  99. td task list --project "Work" # tasks in project
  100. td task list --project "Work" --ids-only # one task ID per line
  101. td project list # all projects
  102. td status set "Deep work" --emoji 🎯 --for 2h # shared status; td status clear to remove
  103. td task view https://app.todoist.com/app/task/buy-milk-8Jx4mVr72kPn3QwB # paste a URL
  104. ```
  105. Run `td --help` or `td <command> --help` for more options.
  106. Supported list commands accept `--ids-only` when each result has a stable ID. It prints one
  107. ID per line and no human-readable empty-state text. When more pages exist, the pagination
  108. notice goes to stderr so stdout remains safe for pipes. `--ids-only`, `--json`, and `--ndjson`
  109. are mutually exclusive.
  110. ## Accessibility
  111. 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:
  112. ```bash
  113. td today --accessible
  114. # or
  115. export TD_ACCESSIBLE=1
  116. td today
  117. ```
  118. 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.
  119. ## Extensions
  120. 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:
  121. ```bash
  122. td extension install owner/td-standup # from GitHub
  123. td standup
  124. td extension list
  125. ```
  126. To write your own, start with `td extension create <name>` and see [docs/extensions.md](docs/extensions.md).
  127. ## Shell Completions
  128. Tab completion is available for bash, zsh, fish, and PowerShell:
  129. ```bash
  130. td completion install # prompts for shell
  131. td completion install bash # or: zsh, fish, pwsh
  132. ```
  133. Restart your shell or source your config file to activate. To remove:
  134. ```bash
  135. td completion uninstall
  136. ```
  137. ## Development
  138. ```bash
  139. npm install
  140. npm run build # compile
  141. npm run dev # watch mode
  142. npm run type-check # type check
  143. npm run fix # auto-fix lint + format
  144. npm test # run tests
  145. ```

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.