Twist CLI
A command-line interface for Twist.
Installation
npm install -g @doist/twist-cli
Agent Skills
Install skills for your coding agent:
tw skill install claude-code
tw skill install codex
tw skill install cursor
tw skill install gemini
tw skill install pi
tw skill install universal
Skills are installed to ~/<agent-dir>/skills/twist-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/.
tw skill list
tw skill uninstall <agent>
Uninstallation
First, remove any installed agent skills:
tw skill uninstall <agent>
Then uninstall the CLI:
npm uninstall -g @doist/twist-cli
Local Setup
git clone https://github.com/todoist/twist-cli.git
cd twist-cli
npm install
npm run build
npm link
This makes the tw command available globally.
Setup
tw auth login
This opens your browser to authenticate with Twist. 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/twist-cli/config.json. Existing plaintext tokens are migrated automatically the next time the CLI reads them successfully from the config file. Non-secret settings such as the current workspace remain in the config file.
Alternative methods
Manual token:
tw auth token "your-token"
Environment variable:
export TWIST_API_TOKEN="your-token"
TWIST_API_TOKEN always takes priority over the stored token.
Auth commands
tw auth status # check if authenticated
tw auth logout # remove saved token
Usage
tw inbox # inbox threads
tw inbox --unread # unread threads only
tw mentions # content mentioning you
tw mentions --since 2026-04-01 --all --json
tw thread view <ref> # view thread with comments
tw thread view <ref> --comment 123 # view a specific comment
tw thread reply <ref> # reply to a thread
tw thread rename <ref> "New title" # rename a thread
tw thread update <ref> "New body" # edit a thread's body (first post)
tw conversation unread # list unread conversations
tw conversation view <ref> # view conversation messages
tw msg view <ref> # view a conversation message
tw search "keyword" # search across workspace
tw search "keyword" --all # fetch all result pages
tw react thread <ref> 👍 # add reaction
tw away # show away status
tw away set vacation 2026-03-20 # set away until date
tw away clear # clear away status
tw groups # list groups in a workspace
tw groups view <ref> # show a group with members
tw groups create "Frontend" # create a group
tw groups create "FE" --users [email protected],[email protected]
tw groups rename <ref> "New name" # rename a group
tw groups delete <ref> --yes # delete a group
tw groups add-user <ref> [email protected] [email protected]
tw groups remove-user <ref> id:123,id:456
References accept IDs (123 or id:123), Twist URLs, or fuzzy names (for workspaces/users).
Run tw --help or tw <command> --help for more options.
Shell Completions
Tab completion is available for bash, zsh, and fish:
tw completion install # prompts for shell
tw completion install bash # or: zsh, fish
Restart your shell or source your config file to activate. To remove:
tw completion uninstall
Machine-readable output
All list/view commands support --json and --ndjson flags for scripting:
tw inbox --json # JSON array
tw inbox --ndjson # newline-delimited JSON
tw inbox --json --full # include all fields
Development
npm install
npm run build # compile
npm run dev # watch mode
npm run type-check # type check
npm run format # format code
npm test # run tests