https://github.com/doist/twist-cli
Command-line interface for Twist
https://github.com/doist/twist-cli
Last synced: 3 months ago
JSON representation
Command-line interface for Twist
- Host: GitHub
- URL: https://github.com/doist/twist-cli
- Owner: Doist
- Created: 2026-01-15T15:41:43.000Z (6 months ago)
- Default Branch: main
- Last Pushed: 2026-04-02T21:24:38.000Z (4 months ago)
- Last Synced: 2026-04-03T01:15:15.962Z (4 months ago)
- Language: TypeScript
- Homepage:
- Size: 1.06 MB
- Stars: 3
- Watchers: 1
- Forks: 1
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
# Twist CLI
A command-line interface for Twist.
## Installation
> ```bash
> npm install -g @doist/twist-cli
> ```
### Agent Skills
Install skills for your coding agent:
```bash
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 `~//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/`.
```bash
tw skill list
tw skill uninstall
```
## Uninstallation
First, remove any installed agent skills:
```bash
tw skill uninstall
```
Then uninstall the CLI:
```bash
npm uninstall -g @doist/twist-cli
```
## Local Setup
```bash
git clone https://github.com/Doist/twist-cli.git
cd twist-cli
npm install
npm run build
npm link
```
This makes the `tw` command available globally.
## Setup
```bash
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:**
```bash
tw auth token "your-token"
```
**Environment variable:**
```bash
export TWIST_API_TOKEN="your-token"
```
`TWIST_API_TOKEN` always takes priority over the stored token.
### Auth commands
```bash
tw auth status # check if authenticated
tw auth logout # remove saved token
```
## Usage
```bash
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 # view thread with comments
tw thread view --comment 123 # view a specific comment
tw thread reply # reply to a thread
tw thread rename "New title" # rename a thread
tw thread update "New body" # edit a thread's body (first post)
tw conversation unread # list unread conversations
tw conversation view # view conversation messages
tw msg view # view a conversation message
tw search "keyword" # search across workspace
tw search "keyword" --all # fetch all result pages
tw react thread 👍 # 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 # show a group with members
tw groups create "Frontend" # create a group
tw groups create "FE" --users alice@doist.com,bob@doist.com
tw groups rename "New name" # rename a group
tw groups delete --yes # delete a group
tw groups add-user alice@doist.com bob@doist.com
tw groups remove-user id:123,id:456
```
References accept IDs (`123` or `id:123`), Twist URLs, or fuzzy names (for workspaces/users).
Run `tw --help` or `tw --help` for more options.
## Shell Completions
Tab completion is available for bash, zsh, and fish:
```bash
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:
```bash
tw completion uninstall
```
## Machine-readable output
All list/view commands support `--json` and `--ndjson` flags for scripting:
```bash
tw inbox --json # JSON array
tw inbox --ndjson # newline-delimited JSON
tw inbox --json --full # include all fields
```
## Development
```bash
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
```