@tonbo/cli 0.4.0 → 0.6.0

package/README.md

@@ -1,241 +1,118 @@
 # Tonbo CLI
 
-Install the public package with Node.js 22 or newer:
+The Tonbo CLI signs you in to Tonbo and manages account resources from the command line. Install the public package with Node.js 22 or newer:
 
 ```console
 npm install --global @tonbo/cli
 tonbo --version
 ```
 
-The CLI deploys an Agent directly from a local directory without requiring Git or Tonbo calls in the Agent source. Sign in, then initialize the current directory interactively:
+## Sign in
 
 ```console
-tonbo login
-tonbo init
-No Harness-specific configuration was found in this agent.
-? Which supported Harness should Tonbo use?
-❯ PI (`pi`)  Run this agent with the pi command.
-? How should this Agent connect to Tonbo?
-❯ Create a new agent  Create it only after you confirm the complete configuration.
-  Use an existing agent
-  Set up later
-? Agent name [my-agent]:
-
-Tonbo Agent configuration:
-  Agent:       Create my-agent in my-account (permanent address assigned after creation)
-  Harness:       PI
-  Execution:     PI CLI (`pi`)
-  Model:         claude-sonnet-4-5
-? Create agent and .tonbo with this configuration?
-❯ Create agent and .tonbo
-  Edit configuration  Change the agent, Harness, execution mode, model, or SDK entrypoint.
-  Cancel
-Created agent my-agent and .tonbo.
-Agent: my-agent (my-agent-my-account.tonbo.sh)
-Organization: my-account
-Application: https://my-agent-my-account.tonbo.sh
-Harness: PI
-Mode: PI CLI
-Next: tonbo deploy
+tonbo login [--account <name>]
+tonbo logout
 ```
 
-Use the arrow keys and Enter to select a supported Harness and either create or select the one Agent owned by this source tree. Agent creation and file writes wait until the final review; cancelling leaves both local and cloud state unchanged. `AGENTS.md` is Harness-neutral and never identifies PI by itself. When `.pi/settings.json` exists, the shared source inspector identifies the PI Harness and reports its workspace-local packages. A regular PI agent defaults to the native PI CLI; choose `Edit configuration` only when changing the Agent, execution mode, model, or another setting. Unsupported and planned Harnesses are not shown.
+`login` opens the browser at `https://tonbo.dev/cli/login`, where you pick the account (your personal account unless `--account` names another) and approve a personal API key named `CLI on <hostname>`. The browser returns a one-time code to a local callback on `127.0.0.1`, and the CLI redeems it with its PKCE verifier for the key. The key acts as you with your role in that account, expires after six months and replaces the key an earlier login on the same host created; there is no refresh, so an expired or revoked key asks you to run `tonbo login` again. One login holds one account: log in again to switch accounts.
 
-The generated `.tonbo` is TOML:
+The login and the credentials file are shared with [`yield`](../yield) through `@tonbo/cli-core`: either CLI's `login` signs both in, and either `logout` signs both out. The login is saved at `${XDG_CONFIG_HOME:-$HOME/.config}/tonbo/credentials.json` as `{version, account_id, key_id, key, expires_at}`. The CLI atomically replaces that file with owner-only permissions and refuses a symlink or a file other users can read. A file written by an earlier CLI release is not migrated; run `tonbo login`.
 
-```toml
-# Tonbo Agent configuration.
-# Edit this file directly or run `tonbo init` to reconfigure.
-version = 2
-agent = "my-agent-my-account.tonbo.sh"
+`logout` revokes the saved key through the Management API and removes the file. If the revocation fails, the file is still removed and the CLI reports the key id, so you can revoke it under API keys in the console.
 
-[harness]
-runtime = "pi"
+### Environment
 
-[harness.driver]
-kind = "native"
+- `TONBO_API_KEY`: a personal key (`tbo_…`) used instead of the saved login, for non-interactive use such as CI. `logout` acts only on the saved login.
+- `TONBO_API_ORIGIN`: the Management API origin, `https://api.tonbo.dev` by default; it must be https (or http on a loopback address). The login page is served from the same origin without its `api.` label.
 
-[inference]
-model = "claude-sonnet-4-5"
-```
+## Commands and the Management API
 
-The immutable full Agent hostname is the only durable Agent authority in the source tree; it is not a credential. This keeps Agents with the same name in different Organizations unambiguous. `deploy`, `run`, `ssh` and `secret` refuse an unbound declaration. `tonbo agent use <name-hostname-or-id>` accepts any convenient selector, resolves it through the signed-in account and writes the selected `agent-organization.tonbo.sh` hostname into `.tonbo`; rebinding an existing declaration requires interactive confirmation or `--force`. UUIDs remain internal API identities and are never committed by the CLI.
+Every command other than `login` and `logout` calls one operation of the [Management API](../../contracts/management/openapi-v1.yaml) and is named by that operation's `x-tonbo-cli`; the command set and the operations tagged with a command are the same set, which `test/commands.test.ts` checks in both directions. The CLI resolves each request from the operation table of the internal package [`@tonbo/cli-core`](../../packages/tonbo-cli-core) (`src/generated/contracts.ts`, which `pnpm --filter @tonbo/cli-core generate:contracts` derives from the contract). `login` and `logout` are the named exception: they obtain and discard the key the other commands present as their Bearer credential. What a command may do is what your role in the logged-in account allows; the CLI never decides it.
 
-The default inference model is written without prompting. Override it explicitly with `--model`. Headless initialization makes Harness and driver choices explicit and may bind the resulting declaration with `agent use`:
+| Command | Operation | Request |
+| --- | --- | --- |
+| `tonbo account show` | `getAccount` | `GET /v1/account` |
+| `tonbo region list` | `listRegions` | `GET /v1/regions` |
+| `tonbo member list [--limit <n>] [--cursor <c>]` | `listMembers` | `GET /v1/members` |
+| `tonbo member update <member> [--role <role>] [--name <name>]` | `updateMember` | `PATCH /v1/members/{subject}` |
+| `tonbo agent create <name> [--role <role>] [--region <region>] [--idempotency-key <key>]` | `createAgent` | `POST /v1/agents` |
+| `tonbo api-key list [--limit <n>] [--cursor <c>]` | `listApiKeys` | `GET /v1/api-keys` |
+| `tonbo api-key create <name> [--member <member>] [--read-only] [--bucket <name>]… [--database <name>]… [--database-prefix <prefix>]… [--expires-in <period>]` | `createApiKey` | `POST /v1/api-keys` |
+| `tonbo api-key show <key-id>` | `getApiKey` | `GET /v1/api-keys/{key_id}` |
+| `tonbo api-key revoke <key-id> [--yes]` | `revokeApiKey` | `DELETE /v1/api-keys/{key_id}` |
+| `tonbo bucket list [--limit <n>] [--cursor <c>]` | `listBuckets` | `GET /v1/buckets` |
+| `tonbo bucket create <name> [--region <region>] [--idempotency-key <key>]` | `createBucket` | `POST /v1/buckets` |
+| `tonbo bucket show <name>` | `getBucket` | `GET /v1/buckets/{name}` |
+| `tonbo bucket update <name> (--public \| --private)` | `updateBucket` | `PATCH /v1/buckets/{name}` |
+| `tonbo bucket delete <name> [--yes]` | `deleteBucket` | `DELETE /v1/buckets/{name}` |
+| `tonbo database list [--prefix <prefix>] [--limit <n>] [--cursor <c>]` | `listDatabases` | `GET /v1/databases` |
+| `tonbo database create <name> [--region <region>] [--idempotency-key <key>]` | `createDatabase` | `POST /v1/databases` |
+| `tonbo database show <name>` | `getDatabase` | `GET /v1/databases/{name}` |
+| `tonbo database update <name> (--public \| --private)` | `updateDatabase` | `PATCH /v1/databases/{name}` |
+| `tonbo database delete <name> [--yes]` | `deleteDatabase` | `DELETE /v1/databases/{name}` |
+| `tonbo database usage [--period <YYYY-MM>] [--sort list_value\|name] [--prefix <prefix>] [--limit <n>] [--cursor <c>]` | `listDatabaseUsage` | `GET /v1/usage/databases` |
+| `tonbo usage show [--period <YYYY-MM>]` | `getUsage` | `GET /v1/usage` |
 
-```console
-tonbo init --harness pi --driver native
-tonbo init --harness pi --driver command --agent-entry dist/agent.mjs
-tonbo agent use my-agent-my-account.tonbo.sh
-```
+### Output and errors
 
-After interactive initialization, deploy the current contents:
+Every command prints an aligned table or a list of fields for people. With `--json` it prints the answer's `data` exactly as the API returned it, one JSON value on stdout and nothing else there. A list prints one page; when there is another, the CLI writes `More results: run again with --cursor <cursor>` to stderr, so `--json` output stays the API's `data`. `database usage --json` prints the whole answer, since its `other` row, checkpoint and prices belong with the rows. `--limit` asks for up to that many items (the API's default is 50, its maximum 200).
 
-```console
-tonbo deploy
-tonbo run "Reply with exactly READY."
-```
+A refusal prints the problem's detail, the fields a validation error names, and the request's `X-Request-Id` to stderr, and the command exits with status 1. An invalid or expired key adds `Run tonbo login`.
 
-Choose `Use an existing agent` during `init` when the Agent already exists. `tonbo agent create <name>` and `tonbo agent use <name-hostname-or-id>` remain explicit automation and recovery commands.
+### Retried creations
 
-Every Agent has a home region, chosen when it is created and never changed afterwards. Its Deployments, Sessions and files stay in that region. The hostname and the SSH destination are the same in every region. Name the region with `--region`; `tonbo region list` shows the regions that accept new resources (`allocation_enabled`). Without `--region`, Tonbo uses the only region that accepts new Agents. When several do, interactive `init` and `agent create` ask which one to use, and a non-interactive request without `--region` is refused with HTTP 400 (`region is required`). `init --region` applies only to an Agent that interactive `init` creates:
+`agent create`, `bucket create` and `database create` send an `Idempotency-Key`, a new UUID unless `--idempotency-key` names one. When a creation is not confirmed (the network failed or the server answered 5xx), the CLI prints its key; retrying with that key and the same arguments returns what the first request created instead of creating a second one. `api-key create` has no idempotency key, because a key's secret is never stored and a replay could not return it; a live key's name is unique, so a blind retry is refused with 409 rather than creating a second key.
 
-```console
-tonbo region list
-tonbo agent create my-agent --region us-east-1
-tonbo init --region us-east-1
-```
+### Destructive commands
 
-`run` creates a durable Session and prints its ID in `--json` output. Pass that identity back to continue the same PI conversation:
+`api-key revoke`, `bucket delete` and `database delete` ask before they act when stdin and stderr are a terminal: a revocation is confirmed by typing `yes`, a deletion by typing the bucket's or database's name, as in the console. Without a terminal they refuse unless `--yes` is given.
 
-```console
-tonbo run --session 4d8e9501-... "Continue the previous task."
-```
+## Account
 
-Each `run` submits one durable Turn. Once the platform admits it, the Turn runs to its end whether or not the CLI keeps waiting, within the limits of `contracts/agents/turn-execution-v1.json` (today at most 60 minutes of execution, after waiting at most 70 minutes to start behind earlier Turns of the same Agent). `run` waits for the result as long as it takes: once the Turn is admitted it names the Turn and its Session on stderr and reads the Turn by id until it ends. It does not rely on the Management API's `202`, which comes only after a five-minute hold that outlasts how long Node's fetch waits for an answer; a submission that gets no answer before admission is sent again under the same id. Interrupting the wait, losing the network or signing out does not stop the Turn. `--no-wait` returns as soon as the Turn is admitted and prints how to collect its result later; `tonbo turn wait` does that from any bound directory whose signed-in account can use the Agent:
+`account show` prints the logged-in account: its id, name and kind, your member subject and role in it, and its limits.
 
-```console
-tonbo run --no-wait "Refactor the build and run the full test suite."
-tonbo turn wait 7a000000-... --session 4d8e9501-...
-```
+## Regions
 
-A failed Turn exits non-zero with its failure code, for example `Turn 7a000000-... failed (deadline_exceeded): ...`; the codes and their meaning are the `TurnFailureCode` schema of `contracts/management/openapi-v1.yaml`. `agent_busy` means the Agent already has the most Turns waiting to start and this one was not admitted; run it again later. Any other refusal also says the Turn was not admitted, and `run` stops sending a submission the platform has not admitted within 15 minutes. Waiting stops, without touching the Turn, a few minutes after the Turn's deadline if the platform has still not recorded its outcome.
+`region list` shows the regions new resources can be created in, with each region's data-plane origin.
 
-Every `tonbo deploy` creates one immutable Deployment: the uploaded source, the `.tonbo` settings and the git provenance of the source root (commit, branch, subject, author and whether the tree was dirty) when the directory is inside a git work tree. Git is optional; without it the Deployment records `tonbo deploy` as its source. Deployments are named by their commit subject, or by their short id (the first eight hex characters) when there is no commit, and every command that takes a Deployment accepts any unambiguous id prefix. The Agent's Production pointer names the one Deployment that serves its hostname; `deploy` moves Production to the new Deployment and prints the Deployment, its Production state and the exact standard OpenSSH command for the bound Agent and its username:
+## Members and Agents
 
 ```console
-$ tonbo deploy
-Deployed agent my-agent.
-Organization: my-account
-Deployment: Fix greeting (0f3a7c21)
-Source: 0123456 · main
-Production: promoting (generation 4)
-Application: https://my-agent-my-account.tonbo.sh
-
-Agent process: starts with the first turn and stays warm while the runtime is active.
-
-Start the Agent:
-  tonbo run "<prompt>"
-
-Connect with SSH:
-  ssh my-agent.my-account@tonbo.sh
+tonbo member list
+tonbo member update pi-live --role admin
+tonbo member update agent.80000000-0000-4000-8000-000000000003 --name pi-next
+tonbo agent create my-agent --region us-east-1
 ```
 
-When the new Deployment has the same contents as the Production Deployment it replaces, `deploy` says so; the record is still created. `tonbo deploy --no-promote` creates the Deployment without moving Production, for example to stage a build and promote it later:
-
-```console
-tonbo deploy --no-promote
-tonbo deployments                      # ID  NAME  STATUS  PRODUCTION  SOURCE  CREATED  BY
-tonbo deployments show 0f3a7c21        # datasheet and Rollouts for one Deployment
-tonbo deployments promote 0f3a7c21     # move Production to a Deployment
-tonbo deployments rollback             # move Production back to the previous Production Deployment
-tonbo deployments rollback 9b8c1d22    # or to a named one
-```
+`member list` lists the account's people and Agents with their kind, name and role. `member update` gives a member another role (`owner`, `admin` or `member`; only an owner grants `owner`) or renames an Agent with `--name`, or both at once. `<member>` is a member subject: a person's user id, or `agent.<agent id>` for an Agent. An Agent's bare id or its name works too: the CLI looks it up in `member list` and uses it only when exactly one member matches.
 
-`tonbo deployments` (alias `tonbo deployments list`) marks the current Production Deployment with `●` and earlier ones with `○`; `STATUS` is the Deployment's relationship to Production: `current`, `promoting`, `failed`, `stopped`, `previous` or `none`. Promotion and rollback compare-and-swap the Production generation, so two people moving Production at once cannot silently overwrite each other; a conflict is reported and the command can be retried after checking `tonbo deployments`. `tonbo agent show` prints the Production Deployment and its state alongside the Agent addresses.
+`agent create` creates an Agent identity with a role (`member` unless `--role` names another). Every Agent has a home region, chosen when it is created and never changed afterwards. Without `--region`, Tonbo uses the only region that accepts new Agents; when several do, an interactive `agent create` asks which one to use, and a non-interactive request without `--region` is refused.
 
-Use `tonbo agent show` to rediscover the username, home region, application address and SSH command later. `tonbo login` registers public keys found at the conventional `~/.ssh/id_ed25519.pub`, `id_ecdsa.pub` and `id_rsa.pub` paths. Register a key at another path with `tonbo ssh-key add <path.pub>` and revoke a lost or retired key with `tonbo ssh-key remove SHA256:...`. The CLI is not part of the SSH connection; ordinary OpenSSH, `scp` and `rsync` connect directly:
+## API keys
 
 ```console
-ssh my-agent.my-account@tonbo.sh
+tonbo api-key list
+tonbo api-key create ci-reader --member pi-live --read-only --bucket events --expires-in 6_months
+tonbo api-key revoke 70000000-0000-4000-8000-000000000007
 ```
 
-The SSH user name is the Agent qualified by its username; the signed public key identifies the Tonbo user and is checked against membership and IAM at connection time. The CLI resolves the Agent name in `.tonbo` and prints the server-authoritative destination, so users never need to remember or assemble a username. The shell and HTTP turns may coexist on the singleton runtime, allowing the shell to observe the Agent while it works. Session writer fencing protects durable conversation history; ordinary workspace files retain Linux process concurrency semantics.
+`api-key list` shows your keys, or every key of the account for an owner or admin, with the last four characters of each secret. `api-key create` creates a personal key for you, or with `--member` a key of an Agent (its subject, id or name; owners and admins only). `--read-only`, and either `--bucket` or `--database` and `--database-prefix` (repeat each for several), narrow the key for its whole life; `--expires-in` is one of `15_days`, `1_month`, `6_months`, `1_year` or `never` (the default). The secret is printed once, in that answer only, with a warning on stderr: store it then, because no command can show it again. `api-key show` prints one key, and `api-key revoke` revokes it and every token minted from it.
 
-Deploy does not create a hidden Session just to prewarm PI. The first real `tonbo run` starts the Session-bound PI RPC process; successful Turns keep that process hot, including across native Session switches. The process is disposable cache rather than durable state: pause, replacement and uncertain failures remove it, and the next Turn restores authority from the durable Session JSONL.
-
-The platform injects scoped inference access and owns PI Session capture. Do not put a model-provider API key or a Tonbo credential in `.tonbo`.
-
-Deploy snapshots regular files under `.tonbo`, excluding `.git`, `node_modules`, PI package caches, local environment files and patterns in `.tonboignore`. Coding tools start in the persistent Artifacts workspace, while `AGENTS.md` and trusted `.pi` extensions, skills, prompts and settings load from the Deployment's uploaded source.
-
-## Supported PI agent shapes
-
-### 1. Agent-local Agent
-
-Keep the normal PI agent layout. Tonbo runs the same `AGENTS.md`, `.pi/APPEND_SYSTEM.md`, `.pi/settings.json`, `.pi/extensions`, `.pi/skills` and `.pi/prompts` that local `pi` loads:
+## Buckets
 
 ```console
-pi
-tonbo init
-tonbo deploy
-tonbo run "Start the task."
+tonbo bucket create events --region us-east-1
+tonbo bucket update events --public
+tonbo bucket delete events
 ```
 
-### 2. PI Package agent
+`bucket list` and `bucket show` print each bucket's region, state, read access and URL; a stream lives at `{url}/{stream}`. `bucket create` creates a bucket in `--region`, or in the account's default region. `bucket update` publishes a bucket for anonymous reads with `--public` or takes it private with `--private`. `bucket delete` deletes a bucket and every stream in it; the bucket's name is never used again.
 
-Use PI's agent-local package declaration as the single source of truth. A package is a PI resource, not another Tonbo execution mode: `tonbo init` recognizes `.pi/settings.json`, then the native PI driver loads the packages. Install an immutable package reference locally, verify it with PI, and deploy the agent; Tonbo excludes `.pi/npm` and `.pi/git` caches and restores packages inside the isolated runtime:
+## Usage
 
-```console
-pi install -l npm:@acme/my-pi-agent@1.2.3
-pi
-tonbo init
-tonbo deploy
-```
-
-Remote npm packages must use an exact version. Git packages must use a full 40-character commit, for example `git:github.com/acme/my-pi-agent@0123456789abcdef0123456789abcdef01234567`. Movable tags, branches, ranges and `latest` fail deployment.
-
-### 3. PI SDK app
-
-Choose `Edit configuration`, change `Execution mode` to `PI SDK app`, and confirm the resulting summary. In automation, use `--driver command --agent-entry <file>`, or declare a command driver directly:
-
-```toml
-version = 2
-
-[harness]
-runtime = "pi"
-secrets = ["GITHUB_TOKEN"]
-
-[harness.driver]
-kind = "command"
-protocol = "pi-rpc-v1"
-command = ["node", "dist/agent.mjs"]
-
-[build]
-command = ["npm", "run", "build"]
-
-[inference]
-model = "claude-sonnet-4-5"
-```
-
-`tonbo deploy` runs the build command before creating the source snapshot. The entrypoint must keep stdout exclusively for PI RPC and send logs to stderr. It receives `PI_CODING_AGENT_MODULE`, `PI_CODING_AGENT_DIR`, `PI_CODING_AGENT_SESSION_DIR`, `TONBO_PI_SESSION_FILE`, `TONBO_PI_SESSION_ID`, `TONBO_PI_PROVIDER`, `TONBO_PI_MODEL` and `TONBO_PI_RPC_PROTOCOL`. Load the platform PI SDK from `PI_CODING_AGENT_MODULE`, open `TONBO_PI_SESSION_FILE`, create an `AgentSessionRuntime`, and pass it to `runRpcMode()`. This lets the app customize tools and runtime services without forking PI while preserving Tonbo's durable Session and Turn protocol.
-
-For a non-interactive invocation, provide a current Tonbo CLI OAuth access token; the committed `.tonbo` supplies the only Agent context:
-
-```console
-TONBO_ACCESS_TOKEN=... tonbo --json deploy
-TONBO_ACCESS_TOKEN=... tonbo --json run "health check"
-```
-
-Node.js 22 or newer is required. Human OAuth tokens are stored at `${XDG_CONFIG_HOME:-$HOME/.config}/tonbo/credentials.json`; the CLI atomically replaces that file with owner-only permissions and never writes it into an Agent directory.
+`usage show` prints the account's rated usage of one calendar month in UTC, the current one unless `--period YYYY-MM` names another: one line per product, region, dimension and model with its quantity and amount, and the total, in US dollars.
 
 ## Related design
 
-- [Design documentation map](../../docs/design/README.md)
-- [Agent source inspection and onboarding](../../docs/design/agent-source-onboarding.md)
-- [Shared source inspector](../../packages/agent-source-inspector/README.md)
-- [Agent resource model](../../docs/design/agent-resource-model.md)
-- [Agent Deployments, Production and Rollouts](../../docs/design/agent-deployments.md)
 - [ADR-0008: Tonbo CLI onboarding and credential boundaries](../../apps/user-center/docs/decisions/adr-0008-tonbo-cli-onboarding.md)
-- [Management API v1](../../contracts/management/openapi-v1.yaml)
-
-## Machines
-
-Machines belong to an Account independently of Agents. Allocate in `us-east-1`, bind an available Machine from Agent detail or the CLI, inspect measured metrics, and release it when no longer needed. Allocation starts no compute. The platform handles idle pause/resume automatically; there are no customer power controls or arbitrary Machine command/upload APIs.
-
-```console
-tonbo --json region list
-tonbo --json machine allocate --account <account-uuid> --region us-east-1 --request-id <request-uuid>
-tonbo --json machine allocation <request-uuid> --account <account-uuid>
-tonbo --json machine list --account <account-uuid>
-tonbo --json machine bind <machine-uuid> --agent <agent-uuid>
-tonbo --json machine show <machine-uuid>
-tonbo --json machine metrics <machine-uuid>
-tonbo --json machine unbind <machine-uuid>
-tonbo --json machine release <machine-uuid>
-```
-
-Only one active Agent binding per Machine and one Machine per Agent are currently supported. Unbinding drains execution and completes physical deletion, final usage settlement and storage credential revocation before the Machine becomes available. Wait for `available: true` in `machine show` before rebinding. Cross-Agent reassignment resets rootfs; the destination mounts its own Agent Workspace and Sessions. Hidden pause/resume within the same Agent retains rootfs and process state. Release also drains an existing binding automatically; it does not delete Agent files or Sessions. A Machine binds only to an Agent in the same region. `machine list` names any region it could not reach in `unavailable_regions`; its Machines are missing from that answer.
-
-`tonbo agent list` lists accessible Agents without requiring a local `.tonbo` file. JSON command output uses `agent` for one Agent and `agents` for the list; there is no duplicate `agent` output alias.
-
-Persist the allocation request UUID before sending when automating. Reuse it with the same account and region after a lost response; lookup returns the original Machine even after release. Omitting `--request-id` generates one, included in the success output or retry error.
+- [Tonbo CLI release](../../docs/operations/tonbo-cli-release.md)