@tonbo/cli 0.3.4 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +60 -172
  2. package/dist/bin/tonbo.js +937 -2244
  3. package/package.json +7 -13
package/README.md CHANGED
@@ -1,224 +1,112 @@
1
1
  # Tonbo CLI
2
2
 
3
- Install the public package with Node.js 22 or newer:
3
+ 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:
4
4
 
5
5
  ```console
6
6
  npm install --global @tonbo/cli
7
7
  tonbo --version
8
8
  ```
9
9
 
10
- 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:
10
+ ## Sign in
11
11
 
12
12
  ```console
13
- tonbo login
14
- tonbo init
15
- No Harness-specific configuration was found in this agent.
16
- ? Which supported Harness should Tonbo use?
17
- ❯ PI (`pi`) Run this agent with the pi command.
18
- ? How should this Agent connect to Tonbo?
19
- ❯ Create a new agent Create it only after you confirm the complete configuration.
20
- Use an existing agent
21
- Set up later
22
- ? Agent name [my-agent]:
23
-
24
- Tonbo Agent configuration:
25
- Agent: Create my-agent in my-account (permanent address assigned after creation)
26
- Harness: PI
27
- Execution: PI CLI (`pi`)
28
- Model: claude-sonnet-4-5
29
- ? Create agent and .tonbo with this configuration?
30
- ❯ Create agent and .tonbo
31
- Edit configuration Change the agent, Harness, execution mode, model, or SDK entrypoint.
32
- Cancel
33
- Created agent my-agent and .tonbo.
34
- Agent: my-agent (my-agent-my-account.tonbo.sh)
35
- Organization: my-account
36
- Application: https://my-agent-my-account.tonbo.sh
37
- Harness: PI
38
- Mode: PI CLI
39
- Next: tonbo deploy
13
+ tonbo login [--account <name>]
14
+ tonbo logout
40
15
  ```
41
16
 
42
- 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.
17
+ `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.
43
18
 
44
- The generated `.tonbo` is TOML:
19
+ 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`.
45
20
 
46
- ```toml
47
- # Tonbo Agent configuration.
48
- # Edit this file directly or run `tonbo init` to reconfigure.
49
- version = 2
50
- agent = "my-agent-my-account.tonbo.sh"
21
+ `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.
51
22
 
52
- [harness]
53
- runtime = "pi"
23
+ ### Environment
54
24
 
55
- [harness.driver]
56
- kind = "native"
25
+ - `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.
26
+ - `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.
57
27
 
58
- [inference]
59
- model = "claude-sonnet-4-5"
60
- ```
28
+ ## Commands and the Management API
61
29
 
62
- 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.
30
+ 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 `src/generated/contracts.ts`, which `pnpm 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.
63
31
 
64
- 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`:
32
+ | Command | Operation | Request |
33
+ | --- | --- | --- |
34
+ | `tonbo account show` | `getAccount` | `GET /v1/account` |
35
+ | `tonbo region list` | `listRegions` | `GET /v1/regions` |
36
+ | `tonbo member list [--limit <n>] [--cursor <c>]` | `listMembers` | `GET /v1/members` |
37
+ | `tonbo member update <member> [--role <role>] [--name <name>]` | `updateMember` | `PATCH /v1/members/{subject}` |
38
+ | `tonbo agent create <name> [--role <role>] [--region <region>] [--idempotency-key <key>]` | `createAgent` | `POST /v1/agents` |
39
+ | `tonbo api-key list [--limit <n>] [--cursor <c>]` | `listApiKeys` | `GET /v1/api-keys` |
40
+ | `tonbo api-key create <name> [--member <member>] [--read-only] [--bucket <name>]… [--expires-in <period>]` | `createApiKey` | `POST /v1/api-keys` |
41
+ | `tonbo api-key show <key-id>` | `getApiKey` | `GET /v1/api-keys/{key_id}` |
42
+ | `tonbo api-key revoke <key-id> [--yes]` | `revokeApiKey` | `DELETE /v1/api-keys/{key_id}` |
43
+ | `tonbo bucket list [--limit <n>] [--cursor <c>]` | `listBuckets` | `GET /v1/buckets` |
44
+ | `tonbo bucket create <name> [--region <region>] [--idempotency-key <key>]` | `createBucket` | `POST /v1/buckets` |
45
+ | `tonbo bucket show <name>` | `getBucket` | `GET /v1/buckets/{name}` |
46
+ | `tonbo bucket update <name> (--public \| --private)` | `updateBucket` | `PATCH /v1/buckets/{name}` |
47
+ | `tonbo bucket delete <name> [--yes]` | `deleteBucket` | `DELETE /v1/buckets/{name}` |
48
+ | `tonbo usage show [--period <YYYY-MM>]` | `getUsage` | `GET /v1/usage` |
65
49
 
66
- ```console
67
- tonbo init --harness pi --driver native
68
- tonbo init --harness pi --driver command --agent-entry dist/agent.mjs
69
- tonbo agent use my-agent-my-account.tonbo.sh
70
- ```
50
+ ### Output and errors
71
51
 
72
- After interactive initialization, deploy the current contents:
52
+ 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`. `--limit` asks for up to that many items (the API's default is 50, its maximum 200).
73
53
 
74
- ```console
75
- tonbo deploy
76
- tonbo run "Reply with exactly READY."
77
- ```
54
+ 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`.
78
55
 
79
- 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.
56
+ ### Retried creations
80
57
 
81
- `run` creates a durable Session and prints its ID in `--json` output. Pass that identity back to continue the same PI conversation:
58
+ `agent create` and `bucket 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.
82
59
 
83
- ```console
84
- tonbo run --session 4d8e9501-... "Continue the previous task."
85
- ```
60
+ ### Destructive commands
86
61
 
87
- 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:
62
+ `api-key revoke` and `bucket 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 name, as in the console. Without a terminal they refuse unless `--yes` is given.
88
63
 
89
- ```console
90
- $ tonbo deploy
91
- Deployed agent my-agent.
92
- Organization: my-account
93
- Deployment: Fix greeting (0f3a7c21)
94
- Source: 0123456 · main
95
- Production: promoting (generation 4)
96
- Application: https://my-agent-my-account.tonbo.sh
64
+ ## Account
97
65
 
98
- Agent process: starts with the first turn and stays warm while the runtime is active.
66
+ `account show` prints the logged-in account: its id, name and kind, your member subject and role in it, and its limits.
99
67
 
100
- Start the Agent:
101
- tonbo run "<prompt>"
68
+ ## Regions
102
69
 
103
- Connect with SSH:
104
- ssh my-agent.my-account@tonbo.sh
105
- ```
70
+ `region list` shows the regions new resources can be created in, with each region's data-plane origin.
106
71
 
107
- 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:
72
+ ## Members and Agents
108
73
 
109
74
  ```console
110
- tonbo deploy --no-promote
111
- tonbo deployments # ID NAME STATUS PRODUCTION SOURCE CREATED BY
112
- tonbo deployments show 0f3a7c21 # datasheet and Rollouts for one Deployment
113
- tonbo deployments promote 0f3a7c21 # move Production to a Deployment
114
- tonbo deployments rollback # move Production back to the previous Production Deployment
115
- tonbo deployments rollback 9b8c1d22 # or to a named one
75
+ tonbo member list
76
+ tonbo member update pi-live --role admin
77
+ tonbo member update agent.80000000-0000-4000-8000-000000000003 --name pi-next
78
+ tonbo agent create my-agent --region us-east-1
116
79
  ```
117
80
 
118
- `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.
81
+ `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.
119
82
 
120
- Use `tonbo agent show` to rediscover the username, 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:
83
+ `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.
121
84
 
122
- ```console
123
- ssh my-agent.my-account@tonbo.sh
124
- ```
125
-
126
- 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.
127
-
128
- 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.
129
-
130
- 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`.
131
-
132
- 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.
133
-
134
- ## Supported PI agent shapes
135
-
136
- ### 1. Agent-local Agent
137
-
138
- 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:
85
+ ## API keys
139
86
 
140
87
  ```console
141
- pi
142
- tonbo init
143
- tonbo deploy
144
- tonbo run "Start the task."
88
+ tonbo api-key list
89
+ tonbo api-key create ci-reader --member pi-live --read-only --bucket events --expires-in 6_months
90
+ tonbo api-key revoke 70000000-0000-4000-8000-000000000007
145
91
  ```
146
92
 
147
- ### 2. PI Package agent
93
+ `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 `--bucket` (repeat it for several buckets) 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.
148
94
 
149
- 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:
95
+ ## Buckets
150
96
 
151
97
  ```console
152
- pi install -l npm:@acme/my-pi-agent@1.2.3
153
- pi
154
- tonbo init
155
- tonbo deploy
156
- ```
157
-
158
- 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.
159
-
160
- ### 3. PI SDK app
161
-
162
- 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:
163
-
164
- ```toml
165
- version = 2
166
-
167
- [harness]
168
- runtime = "pi"
169
- secrets = ["GITHUB_TOKEN"]
170
-
171
- [harness.driver]
172
- kind = "command"
173
- protocol = "pi-rpc-v1"
174
- command = ["node", "dist/agent.mjs"]
175
-
176
- [build]
177
- command = ["npm", "run", "build"]
178
-
179
- [inference]
180
- model = "claude-sonnet-4-5"
98
+ tonbo bucket create events --region us-east-1
99
+ tonbo bucket update events --public
100
+ tonbo bucket delete events
181
101
  ```
182
102
 
183
- `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.
103
+ `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.
184
104
 
185
- For a non-interactive invocation, provide a current Tonbo CLI OAuth access token; the committed `.tonbo` supplies the only Agent context:
105
+ ## Usage
186
106
 
187
- ```console
188
- TONBO_ACCESS_TOKEN=... tonbo --json deploy
189
- TONBO_ACCESS_TOKEN=... tonbo --json run "health check"
190
- ```
191
-
192
- 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.
107
+ `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.
193
108
 
194
109
  ## Related design
195
110
 
196
- - [Design documentation map](../../docs/design/README.md)
197
- - [Agent source inspection and onboarding](../../docs/design/agent-source-onboarding.md)
198
- - [Shared source inspector](../../packages/agent-source-inspector/README.md)
199
- - [Agent resource model](../../docs/design/agent-resource-model.md)
200
- - [Agent Deployments, Production and Rollouts](../../docs/design/agent-deployments.md)
201
111
  - [ADR-0008: Tonbo CLI onboarding and credential boundaries](../../apps/user-center/docs/decisions/adr-0008-tonbo-cli-onboarding.md)
202
- - [Management API v1](../../contracts/management/openapi-v1.yaml)
203
-
204
- ## Machines
205
-
206
- 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.
207
-
208
- ```console
209
- tonbo --json region list
210
- tonbo --json machine allocate --account <account-uuid> --region us-east-1 --request-id <request-uuid>
211
- tonbo --json machine allocation <request-uuid> --account <account-uuid>
212
- tonbo --json machine list --account <account-uuid>
213
- tonbo --json machine bind <machine-uuid> --agent <agent-uuid>
214
- tonbo --json machine show <machine-uuid>
215
- tonbo --json machine metrics <machine-uuid>
216
- tonbo --json machine unbind <machine-uuid>
217
- tonbo --json machine release <machine-uuid>
218
- ```
219
-
220
- 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.
221
-
222
- `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.
223
-
224
- 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.
112
+ - [Tonbo CLI release](../../docs/operations/tonbo-cli-release.md)