orbit-cli

Command-line client for the Orbit kanban board.

Built so AI agents (Claude Code, Cursor, Aider, ...) can manage tasks end-to-end — create cards, post comments, change status, edit metadata — through a small set of predictable subcommands. Humans get a friendly table view by default; agents pass --json for machine output.

Install

npm i -g @orrisai/orbit-cli
# or
pnpm add -g @orrisai/orbit-cli
# or one-shot, no install:
npx @orrisai/orbit-cli --help

The binary is orbit-cli regardless of the scoped package name. Requires Node 20+.

Auth

Get your token from the Orbit UI (sidebar → your avatar → "复制 token") or ask an admin. Then either:

orbit-cli auth login --token orb_…    # saves to ~/.config/orbit-cli/token
# or
export ORBIT_TOKEN=orb_…               # one-shot env override

Verify with orbit-cli auth (whoami).

Commands

auth                  [login --token T | logout]   Auth & whoami
projects              [list | show <p> | create --name N]
tasks                 [list <p> | show <id> | create <p> --title T |
                       update <id> ... | move <id> <col> | delete <id>]
comment               [list <id> | add <id> --text … | delete <id> <c>]
checklist             [list <id> | add <id> <text> | check/uncheck <c> | delete <c>]
relate                <task-a> <task-b>             Link two tasks (undirected)
unrelate              <task-a> <task-b>             Remove the link
relations             <task-id>                     Show parents / children / siblings
split                 <task-id> --title T [...]     Split unfinished work into a new card
members               [list]
activity              <project>
api                   <METHOD> <path> [--data JSON|@FILE|-]
schema                [<resource>]                  Introspect API for agents

Examples

# Browse
orbit-cli projects
orbit-cli tasks Trio
orbit-cli tasks Trio --col 待办池 --label P0
orbit-cli tasks show PC-04

# Mutate
orbit-cli tasks create Trio --title "新需求：xxx" --label P0 --label backend
orbit-cli tasks update PC-04 --col col_doing --assignee +James --label +P0
orbit-cli tasks move PC-04 进行中

# Comment from stdin (great for long replies)
cat reply.md | orbit-cli comment add PC-04 --text -

# Checklist
orbit-cli checklist add PC-04 "review PR feedback"
orbit-cli checklist check k_abc123

# Relations & split
orbit-cli relate PC-04 PC-08                 # undirected link
orbit-cli relations PC-04                    # show parents / children / siblings
orbit-cli split PC-04 \
  --title "（继续）原标题" \
  --carry-checklist                          # auto-pull every unchecked item
orbit-cli unrelate PC-04 PC-08

# Cleanup
orbit-cli tasks delete PC-04

Agent usage

For an agent, the most useful flow is:

1. orbit-cli --json schema — list of resources + descriptions
2. orbit-cli --json schema tasks — full operation list, HTTP paths, field types for the tasks resource (or any other resource)
3. orbit-cli --json … — every command emits raw JSON in this mode
4. orbit-cli --quiet … — only IDs go to stdout, perfect for piping (orbit-cli --quiet tasks create … | orbit-cli comment add - …)

The schema command is the agent's onboarding entry — call it once, then everything else is a translation from plan → command.

Name resolution

Project / member / column / label arguments accept either the canonical id (p_orbit, u_50…, col_doing, l_p0) or the human-readable name (case-insensitive, with unique-prefix fallback). So all of these work:

orbit-cli tasks Trio
orbit-cli tasks trio                   # case-insensitive
orbit-cli tasks tri                    # unique prefix (errors if ambiguous)
orbit-cli tasks p-c20efe1ed127         # canonical id

orbit-cli tasks move PC-04 进行中       # column by Chinese name
orbit-cli tasks move PC-04 col_doing   # by id

Use @self as a member shortcut to refer to the authenticated user.

Set operations on labels / assignees

For tasks update, --label and --assignee accept three forms:

| Form | Meaning | | ----- | ---------------------------------- | | X | Replace the entire set with [X] | | +X | Add X to the set (idempotent) | | -X | Remove X from the set (idempotent) |

If all ops are bare names, the set is replaced. Mixing in any + or - switches to additive mode. So:

orbit-cli tasks update PC-04 --label P0           # set labels = [P0]
orbit-cli tasks update PC-04 --label +P0          # add P0
orbit-cli tasks update PC-04 --label +P0 --label -doc   # add P0, remove doc
orbit-cli tasks update PC-04 --label P0 --label backend # set labels = [P0, backend]

Long-form input

--description and --text accept three sources:

| Form | Meaning | | ------------- | ----------------------------- | | "literal" | Use the string as-is | | @path/to.md | Read the file contents | | - | Read from stdin |

echo "looking at this now" | orbit-cli comment add PC-04 --text -
orbit-cli tasks create Trio --title "新卡" --description @brief.md

Global flags

--host <url>      Orbit base URL (default: https://orbit.zeabur.app)
--token <token>   Auth token (overrides env + saved file)
--json            Emit raw JSON
--quiet, -q       Print just IDs (one per line)
--help, -h        Show help
--version         Print version

Env vars: ORBIT_HOST, ORBIT_TOKEN, XDG_CONFIG_HOME.

Development

pnpm test         # node:test unit tests (parser, name resolution, set ops)
pnpm smoke        # end-to-end against $ORBIT_HOST (requires ORBIT_TOKEN)

The CLI is one file plus a small pure-helpers module:

cli/
  bin/orbit-cli.mjs   # entrypoint, command dispatch, HTTP, schema, help
  src/parse.mjs       # parseArgs / matchByName / patchSet (pure)
  test/parse.test.mjs # unit tests
  test/smoke.sh       # full CRUD smoke against a live instance

HTTP is shelled out to curl rather than Node's fetch — undici hit ETIMEDOUT against the host on IPv6 in some environments, while curl is reliable. The same trick is used elsewhere in the Orbit repo's seed scripts.

License

MIT