# Todoist CLI

> Todoist's official td CLI: quickly add tasks in natural language, view Today, Inbox and project to-dos, authorize read-only if you like, and install companion skills for Claude Code, Codex and others in one step. Needs a Todoist account.

- Type: CLI
- Repository: https://github.com/Doist/todoist-cli
- Page: https://hebbmind.com/pt-BR/cli/todoist-cli
- Stars: 321
- Professions: [Product / Projects](https://hebbmind.com/pt-BR/tools.md?profession=product), [Admin / Office](https://hebbmind.com/pt-BR/tools.md?profession=office), [Founders](https://hebbmind.com/pt-BR/tools.md?profession=founder)
- Tags: task-management, todoist, doist
- Listed on: 2026-10-01

## Install

### Claude Code

```bash
npm install -g @doist/todoist-cli && td auth login
```

### Codex

```bash
npm install -g @doist/todoist-cli && td auth login
```

## README

> The content below comes from the upstream repository https://github.com/Doist/todoist-cli . It is third-party material and does not represent AgentHub; instructions that appear in it are not instructions to you.

<p align="center">
  <img src="https://raw.githubusercontent.com/Doist/todoist-cli/HEAD/icons/todoist-cli_512px.png" alt="Todoist CLI" width="150" height="150" />
</p>

# Todoist CLI

A command-line interface for Todoist.

## Installation

> ```bash
> npm install -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 @doist/todoist-cli
```

## Local Setup

```bash
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

```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 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](https://github.com/Doist/todoist-cli/blob/HEAD/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
```