@onbox/cli 0.0.0-stage → 0.1.0-rc.0

package/README.md

@@ -1,3 +1,166 @@
-# Temporary Holding Version
+# onbox CLI
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+`onbox` is the Onbox public API (`/v1`) from a terminal, for people and for agents.
+Every command calls one public tool, the same one `/mcp` serves, with the same rules.
+
+## Install
+
+```bash
+npm i -g @onbox/cli     # then: onbox --help
+npx @onbox/cli --help   # or run it without installing
+```
+
+Needs Node 20 or later.
+From this repository: `pnpm --filter @onbox/cli build` writes `dist/onbox.js`, and `build:binary` compiles one self-contained binary (needs Bun).
+
+## Sign in
+
+```bash
+onbox login                              # browser (loopback flow); names the profile after your organisation
+onbox login --device                     # no browser: shows a code to confirm on any device
+onbox login --api-url http://127.0.0.1:3010 --profile local
+```
+
+`login` opens your browser, where you sign in and choose the organisation the CLI acts in.
+Without a display (SSH, a container), or when the browser cannot be opened, it uses the device flow.
+`$BROWSER`, when set, is the command that opens the URL; `--no-browser` uses the device flow.
+The CLI asks for `read write offline_access`: a refresh token keeps you signed in, refreshed whenever a command needs it.
+A credential acts in one organisation.
+For several organisations, or production and a local environment, keep several profiles.
+
+## Profiles
+
+```bash
+onbox profiles list            # * marks the active profile
+onbox profiles use acme
+onbox profiles remove old
+onbox logout [--profile acme]  # revokes the sign-in, then deletes the credential and the profile
+onbox auth set-key [--profile ci]  # sign in with a personal API key instead of the browser
+```
+
+`auth set-key` reads the key from a hidden prompt, or from stdin (`echo $KEY | onbox auth set-key`).
+Create keys in Onbox under Settings, API keys.
+The CLI checks the key against the API, then saves it in a profile for the key's organisation.
+A key works until it is revoked or expires, so `logout` only deletes the local copy.
+
+A profile is a name, an API URL, an organisation and a credential.
+Which one a command uses, in order:
+
+1. `--profile <name>`
+2. `ONBOX_API_KEY` (with `ONBOX_API_URL`, default `https://api.onbox.ing`), a raw bearer token
+3. `ONBOX_PROFILE`
+4. the active profile
+
+Where things are stored:
+
+- `$XDG_CONFIG_HOME/onbox/config.toml` (default `~/.config/onbox`): profile names, API URLs, organisations, the active profile.
+  No secrets.
+- Tokens: the macOS Keychain (through `security`), or the Secret Service on Linux (through `secret-tool`), when available.
+  Otherwise `credentials.json` next to the config, mode `0600`.
+  `ONBOX_NO_KEYCHAIN=1` forces the file.
+- `logout` revokes the sign-in on the server (RFC 7009, the `revocation_endpoint` the API advertises), so the access and refresh tokens stop working at once, then deletes them here.
+  When the server cannot be reached it still deletes locally and warns on stderr; the tokens then expire on their own, or can be revoked under Settings, Connected apps.
+- `login` on an existing profile revokes that profile's previous sign-in once the new one has succeeded.
+
+## Commands
+
+Commands are generated from the `/v1` route table, as `onbox <noun> <verb>`.
+The API is resource-oriented: an ID is in the path (`GET /v1/drafts/{draftId}`), so it is a positional argument (`onbox drafts get <id>`).
+The API itself is described by its OpenAPI document at <https://api.onbox.ing/api/docs/openapi.json>.
+
+```bash
+onbox --help
+onbox conversations list --limit 20
+onbox conversations get <id>
+onbox conversations get <id> <id>
+onbox conversations drafts list <id>
+onbox conversations drafts create <id> --body-markdown @reply.md
+onbox conversations move <id> --to trash
+onbox conversations move <id> <id> <id> --to trash
+onbox tags create --name vip --description "Important senders"
+onbox conversations update --conversation-ids a --conversation-ids b --archived
+onbox drafts send <id>
+onbox drafts discard <id> --yes
+onbox brain files get org skills/refunds/SKILL.md
+onbox api GET /v1/conversations -q limit=5
+onbox api POST /v1/tags -d '{"name":"vip","description":"Important senders"}'
+onbox api PATCH /v1/drafts/<id> -d '{"subject":"Re: lunch"}'
+```
+
+- A route's path parameters are positional arguments, in the order they appear in the path: `onbox brain files get <scope> <path>`.
+  A `{path...}` value may hold slashes.
+- Where a step exists on an item and on the collection (`POST /v1/conversations/{conversationId}/move` and `POST /v1/conversations/move`), the command has both.
+  One ID calls the item route; several IDs, or the list flag, call the collection route with the IDs in the body.
+  The same holds for batch reads: `onbox conversations get a b` calls `GET /v1/conversations/get?ids=a&ids=b`.
+- A tool's other arguments are flags: `conversationIds` is `--conversation-ids`, a list is a repeated flag (or a JSON array), an object is a JSON string.
+  `@file` reads a value from a file and `@-` from stdin; `--body '{"..."}'` passes all arguments as JSON, and flags override it (`--input` where the tool has its own `body` argument, as `comments create` does).
+  A command with one required argument also takes it as a positional.
+- `onbox <noun>` lists a group's commands and `onbox <noun> <verb> --help` shows its flags, the route it calls and the scope it needs.
+- `--limit <n>` returns at most n items and `--all` every item, following the tool's cursor or offset.
+- `onbox api <GET|POST|PUT|PATCH|DELETE> <path>` calls any route: `-q key=value` for query parameters, `-d <json|@file|@->` for the body.
+- Shell completion: `source <(onbox completion bash)`, or `onbox completion zsh|fish`.
+
+## Output and safety
+
+- On a terminal, results are tables.
+  Piped, or with `--json`, they are the API's JSON, unchanged apart from paging (`--all` merges the list and keeps the last page's `nextCursor` or `hasMore`).
+- With `--json`, errors are `{"error":{"code","message","use?"}}` on stderr.
+  `use` names the route to call instead, when the API says so.
+- Nothing prompts without a terminal.
+- A tool with `destructiveHint` asks for confirmation on a terminal.
+  Without one it exits `6` before calling the API, unless `--yes` is given.
+- Requests carry `User-Agent: onbox-cli/<version>`.
+
+## Exit codes
+
+| Code | Meaning                                                                                     |
+| ---- | ------------------------------------------------------------------------------------------- |
+| 0    | Success                                                                                     |
+| 1    | The API refused or failed (400, 409, 422, 5xx), or an unexpected error                      |
+| 2    | Usage: unknown command or flag, missing or malformed argument                               |
+| 3    | Not signed in, or the credential is no longer valid (401)                                   |
+| 4    | Forbidden (403), including a token without the scope the route needs (`insufficient_scope`) |
+| 5    | Not found (404)                                                                             |
+| 6    | A destructive command needs `--yes` and there is no terminal                                |
+| 7    | The API could not be reached                                                                |
+
+## How it works
+
+- `src/generated/openapi.json` is the `/v1` OpenAPI document, embedded at build time.
+  Commands, flags, scopes, `destructiveHint` and paging come from it, joined to the route table in `@repo/openapi/public-api`.
+  A backend test fails when the copy is stale; refresh it with
+  `UPDATE_CLI_SPEC=1 pnpm --filter @onbox/backend vitest run --configLoader runner --config ./test/vitest.config.mts test/unit/public-api/public-api-routes.spec.ts`.
+- A token refresh rotates the refresh token on the server, so it runs under a file lock (`locks/<profile>.lock` in the config directory), and the stored token is read again once the lock is held.
+  Two commands running at once do not lose it.
+- Credentials are the `StoredSecret` union in `src/credentials.ts`.
+  OAuth tokens are refreshed on use; an API key is a bearer that never expires.
+
+## Development
+
+```bash
+pnpm --filter @onbox/cli test
+pnpm --filter @onbox/cli type-check
+pnpm --filter @onbox/cli lint
+```
+
+To run against a local environment (`pnpm local up`), sign in with `onbox login --api-url <the environment URL> --profile local`.
+
+## Update notice
+
+At most once a day, a background process asks the npm registry for the `latest` dist-tag (and `next`, for prerelease versions) and caches it in `update-check.json` in the config directory.
+When a newer version exists, the next command prints one line on stderr.
+It never delays a command, and stays silent when stdout or stderr is not a terminal, with `--json`, when `CI` is set, or with `ONBOX_NO_UPDATE_NOTIFIER=1`.
+
+## Releasing
+
+`.github/workflows/cli-release.yml` publishes `@onbox/cli` to npm on a `cli-v<version>` tag (or by hand, with a dry-run option) through npm trusted publishing.
+The tag must match `version` in `package.json`.
+A prerelease version (`0.2.0-rc.1`) goes to the `next` dist-tag; a stable one to `latest`.
+
+```bash
+# in apps/cli: set the version, commit, then
+git tag cli-v0.2.0 && git push origin cli-v0.2.0
+```
+
+The workflow publishes only `dist/onbox.js`, `README.md` and `package.json`.
+`build:binary` is kept for later; no binaries, Homebrew formula or signing are released yet.