<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 @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/`.

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

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:

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

```bash td auth login -