CLI reference
Close to your code.
A single binary for macOS and Linux, on arm64 and x64. Linux builds require glibc.
Install
curl -fsSL https://todos.sh/install | shThe installer checks the SHA-256 checksum and installs to ~/.local/bin/todos. Run it again to update. You can read the script before you run it or inspect the release manifest.
Sign in and choose a workspace
todos auth login
todos ws list
todos ws use studio
todos team list
todos issue listLogin opens the key creation page. Paste the key into the terminal. If you already have a key, run todos auth login --key to paste it without opening the browser. Settings are stored with mode 0600 in $XDG_CONFIG_HOME/todos/config.json, or ~/.config/todos/config.json.
Use --json for scripts; non-terminal output is also JSON. Terminal tables show times in UTC; JSON keeps Unix timestamps. Exit codes: 0 success, 1 error, 2 unauthenticated, 3 forbidden, 4 rate limited, 5 monthly API allowance used.
Global flags
| Flag | Value | Description |
|---|---|---|
--workspace | Text | Workspace slug or ID |
--json | Switch | Print JSON |
--quiet | Switch | Suppress successful output |
--help, -h | Switch | Show help |
--version, -v | Switch | Print the version |
todos auth
Log in, log out, or check access
todos auth login [--key [<secret>]]
todos auth logout
todos auth status| Flag | Value | Description |
|---|---|---|
--key | Optional text | API key secret; prompts when empty |
todos try
Start a trial workspace without an account
todos try [--name <name>] [--agent <name>]| Flag | Value | Description |
|---|---|---|
--name | Text | Workspace name |
--agent | Text | Who works in it, shown on every change |
todos ws
List, select, or create workspaces
todos ws list [--limit <n>] [--cursor <cursor>]
todos ws use <workspace>
todos ws create --name <name> [--slug <slug>]| Flag | Value | Description |
|---|---|---|
--limit | Text | Page size (1–100) |
--cursor | Text | Next page cursor |
--name | Text | Workspace name |
--slug | Text | Workspace slug |
todos team
List, create, archive, or delete teams, or list workflow states
todos team list [--archived]
todos team create --name <name> --key <key> [--visibility public|private]
todos team states [--team <id>]
todos team archive <id>
todos team unarchive <id>
todos team delete <id> --yes| Flag | Value | Description |
|---|---|---|
--name | Text | Team name |
--key | Text | Issue key prefix, such as ENG |
--visibility | Text | public or private (default: public) |
--team | Text | Only this team's states |
--archived | Switch | List only archived teams |
--yes | Switch | Confirm a delete; it cannot be undone |
todos project
List, create, update, archive, or delete projects
todos project list [--archived]
todos project create --name <name> [options]
todos project update <id> [options]
todos project archive <id>
todos project unarchive <id>
todos project delete <id> --yes| Flag | Value | Description |
|---|---|---|
--name | Text | Project name |
--team | Text | Team ID |
--description | Text | Project description |
--status | Text | planned, active, paused, completed, or canceled |
--lead | Text | Lead user ID |
--start | Text | Start date as Unix seconds |
--target | Text | Target date as Unix seconds |
--archived | Switch | List only archived projects |
--yes | Switch | Confirm a delete; it cannot be undone |
todos issue
Find, create, and manage issues
todos issue list [filters]
todos issue show <key>
todos issue create --team <id> --title <title> [options]
todos issue update <key> [options]
todos issue move <key> --team <id> [--state <id>]
todos issue close <key> [--state <id>]
todos issue comment <key> --body <text>
todos issue search <query> [--limit <n>]
todos issue archive <key>
todos issue unarchive <key>
todos issue delete <key> --yes| Flag | Value | Description |
|---|---|---|
--limit | Text | Page size (1–100) |
--cursor | Text | Next page cursor |
--team | Text | Team ID |
--title | Text | Issue title |
--description | Text | Issue description |
--state | Text | Workflow state ID; list accepts a state kind |
--priority | Text | Priority (0–4) |
--assignee | Text | Assignee user ID, or none for no assignee |
--project | Text | Project ID, or none for no project |
--parent | Text | Parent issue key or ID, or none for no parent |
--ancestor | Text | Issue key or ID; list its sub-issues at any depth |
--label | Text | Filter by label ID |
--labels | Text | Comma-separated label IDs; empty clears them |
--due | Text | Due date as Unix seconds |
--estimate | Text | Issue estimate |
--position | Text | Sort position |
--archived | Switch | List only archived issues |
--q | Text | Search query |
--body | Text | Comment text |
--yes | Switch | Confirm a delete; it cannot be undone |
todos inbox
List or read your notifications
todos inbox list [--unread] [--limit <n>] [--cursor <cursor>]
todos inbox read [--ids <id,id>] [--issue <key>]| Flag | Value | Description |
|---|---|---|
--unread | Switch | Only unread notifications |
--ids | Text | Notification IDs to mark read (default: all) |
--issue | Text | Mark only this issue's notifications read, such as ENG-12 |
--limit | Text | Page size (1–100) |
--cursor | Text | Next page cursor |
todos label
List or create labels
todos label list
todos label create --name <name> --color <hex> [--team <id>]| Flag | Value | Description |
|---|---|---|
--name | Text | Label name |
--color | Text | Label color |
--team | Text | Team ID (default: workspace-wide) |
todos key
List, create, rotate, or revoke API keys
todos key list [--personal] [--limit <n>] [--cursor <cursor>]
todos key create --name <name> --scopes <csv> [--role <role>] [--personal]
todos key rotate <id> [--grace PT0S..PT24H] [--personal]
todos key revoke <id> [--personal]| Flag | Value | Description |
|---|---|---|
--limit | Text | Page size (1–100) |
--cursor | Text | Next page cursor |
--personal | Switch | Manage personal keys |
--name | Text | Key name |
--scopes | Text | Comma-separated scopes or read/write groups |
--role | Text | Workspace role (default: member) |
--teams | Text | Comma-separated team IDs |
--workspaces | Text | Personal key workspace IDs, or * |
--expires | Text | Expiry timestamp in milliseconds |
--grace | Text | Rotation grace: PT0S or PT1H through PT24H |
todos webhook
Manage webhooks and inspect deliveries
todos webhook list
todos webhook create --url <https-url> --events <csv>
todos webhook test <id>
todos webhook deliveries <id>| Flag | Value | Description |
|---|---|---|
--url | Text | Webhook URL |
--events | Text | Comma-separated event types |
todos import
Import a Linear workspace or a GitHub repository
todos import linear [--teams <keys>] [--token <key>] [--dry-run]
todos import github <owner/repo> [--team <key>] [--token <token>] [--dry-run]| Flag | Value | Description |
|---|---|---|
--token | Text | Source token; else LINEAR_API_KEY, or GITHUB_TOKEN, GH_TOKEN, or gh auth token |
--teams | Text | Linear team keys, comma-separated; all teams when omitted |
--team | Text | Team key for the repository; made from its name when omitted |
--dry-run | Switch | Read the source and print counts only |
todos config
Read or set local settings
todos config get <api|key|workspace>
todos config set <api|key|workspace> <value>This command has no extra flags.