VerifiedPlugin
Productivity
todoist
Library for connecting AI agents to Todoist. Includes tools that can be integrated into LLMs, enabling them to access and modify a Todoist account on the user's behalf.
@doistProductivity
Plugin
todoist-cli
A command-line interface for Todoist.
Plugin Signal69/100Solid
maintained99
capable23
documented100
adopted52
Install
$ npx -y skills add Doist/todoist-cli --agent claude-code
Run the curl in your terminal, the rest in Claude Code.
Stats
276
Stars
17
Forks
Active
Maintenance
TypeScript
Language
MIT
License
2d ago
Last commit
6mo ago
Created
Repo: Doist/todoist-cli
What's inside
Skills
2/add-commandGuide for adding new CLI commands or subcommands to todoist-cli. Use when implementing new SDK endpoints, adding subcommands to existing command groups, or extending CLI functionality./todoist-cliManage Todoist tasks, projects, labels, filters, sections, comments, reminders, and workspaces via the `td` CLI. Use when the user wants to view, create, update, complete, or organize Todoist items, or mentions tasks, inbox, today, upcoming, projects, labels, or filters.
README
1Todoist 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 ~/<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>
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
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.
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, fish, and PowerShell:
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:
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
File tree
350Doist/todoist-cliView on GitHub
.agents/
skills/
add-command/
SKILL.md
.claude/
skills/
add-command/
SKILL.md
.github/
workflows/
check-semantic-pull-request.yml
check-skill-sync.yml
issue-automation.yml
lint.yml
release.yml
request-reviews.yml
test.yml
update-todoist-sdk.yml
.gitignore
.npmrc
.nvmrc
.oxfmtrc.json
.oxlintrc.json
.prettierignore
.vscode/
settings.json
AGENTS.md
CHANGELOG.md
CLAUDE.md
CODEBASE.md
CONTRIBUTING.md
docs/
decisions/
001-lenient-cli-ergonomics.md
icons/
td-cli.png
td-cli.svg
lefthook.yml
LICENSE
package-lock.json
package.json
README.md
release.config.js
renovate.json
scripts/
check-skill-sync.js
postinstall.js
sync-skill.js
skills/
todoist-cli/
SKILL.md
src/
__mocks__/
chalk.ts
commands/
activity.test.ts
activity.ts
add.test.ts
add.ts
apps/
apps.test.ts
delete.ts
helpers.test.ts
helpers.ts
index.ts
list.ts
update.ts
view.ts
attachment.test.ts
attachment.ts
auth/
auth.test.ts
helpers.ts
index.ts
login.test.ts
login.ts
logout.ts
status.ts
store-wrap.ts
token.ts
backup/
backup.test.ts
download.ts
helpers.ts
index.ts
list.ts
billing/
billing.test.ts
format.test.ts
format.ts
index.ts
plan.ts
prices.ts
pricing.ts
subscription.ts
changelog.test.ts
changelog.ts
comment/
add.ts
browse.ts
comment.test.ts
delete.ts
helpers.ts
index.ts
list.ts
update.ts
view.ts
completed/
completed.test.ts
index.ts
list.ts
completion/
helpers.ts
index.ts
install.ts
server.ts
uninstall.ts
config/
config.test.ts
index.ts
view.ts
doctor.test.ts
doctor.ts
filter/
browse.ts
create.ts
delete.ts
filter.test.ts
helpers.ts
index.ts
list.ts
update.ts
view.ts
folder/
create.ts
delete.ts
folder.test.ts
helpers.ts
index.ts
list.ts
update.ts
view.ts
hc/
hc.test.ts
index.ts
locale.ts
locales.ts
search.ts
view.ts
inbox.test.ts
inbox.ts
label/
browse.ts
create.ts
delete.ts
helpers.ts
index.ts
label.test.ts
list.ts
remove-shared.ts
rename-shared.ts
update.ts
view.ts
notification/
accept.ts
helpers.ts
index.ts
list.ts
notification.test.ts
read.ts
reject.ts
unread.ts
view.ts
project/
activity-stats.ts
analyze-health.ts
archive.ts
archived-count.ts
archived.ts
browse.ts
collaborators.ts
create.ts
delete.ts
health-context.ts
health.ts
helpers.ts
index.ts
join.ts
list.ts
move.ts
permissions.ts
progress.ts
project.share.test.ts
project.test.ts
reorder.test.ts
reorder.ts
share.ts
unarchive.ts
update.test.ts
update.ts
view.ts
reminder/
add.ts
delete.ts
get.ts
helpers.ts
index.ts
list.ts
location/
add.ts
delete.ts
get.ts
index.ts
update.ts
reminder.test.ts
update.ts
section/
archive.ts
browse.ts
create.ts
delete.ts
index.ts
list.ts
reorder.ts
section.test.ts
unarchive.ts
update.ts
settings/
helpers.ts
index.ts
settings.test.ts
update.ts
view.ts
skill/
index.ts
install.ts
list.ts
skill.test.ts
uninstall.ts
update.ts
stats/
goals.ts
helpers.ts
index.ts
stats.test.ts
vacation.ts
view.ts
task/
add.ts
browse.ts
complete.ts
delete.ts
helpers.ts
index.ts
list.ts
move.ts
quickadd.test.ts
quickadd.ts
reschedule.ts
task.test.ts
uncomplete.ts
update.ts
view.ts
template/
create.ts
export-file.ts
export-url.ts
helpers.ts
import-file.ts
import-id.ts
index.ts
template.test.ts
today.test.ts
today.ts
upcoming.test.ts
upcoming.ts
update/
index.ts
update.test.ts
user/
aliases.ts
current.ts
index.ts
list.ts
project-account.ts
remove.ts
use.ts
user.test.ts
view.test.ts
view.ts
workspace/
activity.ts
create.ts
delete.ts
helpers.ts
index.ts
insights.ts
list.ts
projects.ts
update.ts
use.ts
user-tasks.ts
users.ts
view.ts
workspace.test.ts
index.ts
lib/
api/
core.test.ts
core.ts
filters.ts
notifications.ts
projects-sync.ts
reminders.ts
sections-sync.ts
stats.ts
user-settings.ts
workspaces.ts
auth-flags.test.ts
auth-flags.ts
auth-html.ts
auth-provider.test.ts
auth-provider.ts
auth-store.test.ts
auth-store.ts
auth.test.ts
auth.ts
browser.ts
children.test.ts
children.ts
collaborators.ts
completion.test.ts
completion.ts
config.test.ts
config.ts
constants.ts
dates.test.ts
dates.ts
duration.test.ts
duration.ts
errors.ts
global-args.test.ts
global-args.ts
help-center.test.ts
help-center.ts
local-file.test.ts
local-file.ts
logger.ts
markdown.test.ts
markdown.ts
migrate-auth.test.ts
migrate-auth.ts
oauth-scopes.test.ts
oauth-scopes.ts
options.ts
order.ts
output.test.ts
output.ts
pagination.test.ts
pagination.ts
permissions.test.ts
permissions.ts
progress.test.ts
progress.ts
refs.test.ts
refs.ts
reorder.ts
skills/
content.ts
create-installer.ts
index.ts
types.ts
update-installed.test.ts
update-installed.ts
spinner.test.ts
spinner.ts
stdin.ts
task-list.test.ts
task-list.ts
update.ts
urls.test.ts
urls.ts
usage-tracking.test.ts
usage-tracking.ts
user-records.test.ts
user-records.ts
users.test.ts
users.ts
postinstall.ts
test-support/
api-mock.ts
fixtures.ts
mock-api.ts
project-program.ts
tsconfig.build.json
tsconfig.json
vitest.config.tsMore Flows by @doist.
@doistFAQ
todoist-cli is a Claude Code plugin with 2 hand-picked skills for productivity work, indexed on Flowy. Install it with the command on its page. It includes add-command, todoist-cli. Its skills do not fire on their own yet. Request auto-invocation to have Flowy route them as you prompt. Free and open source.
- What is todoist-cli?
- A command-line interface for Todoist.
- How do I install todoist-cli?
- Run these in Claude Code: npx -y skills add Doist/todoist-cli --agent claude-code. Then prompt normally.
- Does todoist-cli auto-invoke its skills?
- Not yet. It is indexed on Flowy as a plain plugin. Request auto-invocation on its page and Flowy will route its skills for you as you prompt.
- Is todoist-cli free?
- Yes. Flowy is free and open source, with nothing gated. You can read every skill in full before you install.