@tonbo/cli
v0.36.1
Published
The Tonbo CLI. Compute, disks, databases and streams for AI agents: your agent picks what it needs, sets it up, and knows what it costs, from the command line.
Readme
Tonbo CLI
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:
npm install --global @tonbo/cli
tonbo --versionUsage
tonbo login
tonbo database create notes
tonbo database list --json
tonbo database list --account acmetonbo --help prints the rules every command shares (output and --json, pages, exit status, the login, accounts and keys, retried creations, destructive commands) and the environment variables the CLI reads; tonbo <command> --help prints what one command does, its arguments, each flag with its default, and an example. The same words, with the operation each command calls and what its --json prints, are the CLI reference at tonbo.dev/docs/reference/cli.
Sign in
tonbo login signs this computer in as you, once (ADR-0018): every account you belong to is reachable with --account <name>, with your role in each, and joining an organization needs no new login. A command acts in --account, else TONBO_ACCOUNT, else the default tonbo account use <name> sets, else your personal account; tonbo account list lists your accounts. For each request the CLI exchanges the login for a short-lived token of that one account, so the login itself never reaches a resource server. It works only on the computer that logged in, ends after 30 days unused or 180 days at most, and is listed and revoked on the console's Sign-in sessions page. TONBO_API_KEY takes its place for CI and Agents: an API key reaches only its own account. A personal key goes to the Management API as it is; an Agent key, which no resource server accepts directly, answers 401 exchange_required and is then exchanged at POST /api/iam/token for a token kept in memory until a minute before its 10-minute expiry, as the Tonbo SDK does (apiKeyBearer in @tonbo/cli-core).
The login file, login.json, and the device id it is tied to are shared with yield through @tonbo/cli-core, by the contract credentials-v2.json. A login an earlier release saved, credentials.json (credentials-v1.json), is read only when there is no login.json.
Commands and the Management API
Every command other than login and logout is named by one operation of the Management API through its x-tonbo-cli and calls that operation, plus reads of the same resource (a --wait, the Machine a name_taken refusal names, the activations machine show reads for the last end, the Volume a machine create or update --volume names, read for its id and region, or the Volume list machine show and machine delete read for the name of the Machine's Volume); tonbo machine logs, once it ships, is the named Streams exception, reading the stream at the Machine's logs.url. tonbo volume move is the one command that sends another command's operation: it reads the Volume and both Machines and sends the target's updateMachine with move_from (the machine create --move-from of an existing Machine, docs/design/machines-volume-move.md). Apart from it, 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 (src/generated/contracts.ts, which pnpm --filter @tonbo/cli-core generate:contracts derives from the contract). login, logout, account list and account use are the named exception: they obtain, choose among and discard what the other commands present as their Bearer credential. What a command may do is what your role in the account it acts in allows; the CLI never decides it.
The help lives with the commands: src/app.ts defines each command, its arguments and flags with their one-line descriptions, and src/help.ts holds the long help, each flag's default, the examples, the shared rules and the environment. commands.json is all of it as --help prints it, which the docs' CLI reference renders; test/commands.test.ts holds it to the program, and holds every runnable command to its details and example and the environment list to the variables the code reads, so after changing a command run pnpm --filter @tonbo/cli commands.
Updates
Every request to the Management API and to tonbo.dev carries the CLI's release in Tonbo-CLI-Version, and every answer names the latest release in Tonbo-CLI-Latest and the oldest supported one in Tonbo-CLI-Minimum, by the contract versions-v1.json: Latest is this package's version on main, so merging a release bump moves it with no other change, and Minimum is declared in the contract. When Latest is newer, the command ends with one line on stderr, at most once a day (update-notice.json beside the login), never with --json, without a terminal, under CI or with TONBO_NO_UPDATE_NOTICE=1. A release below Minimum is refused with 410 cli_upgrade_required on any request; the CLI prints the detail and exits 1. tonbo update runs the update of the package manager that installed it (npm, pnpm, bun or yarn), printing the command first, and only prints the command for npx or a path it cannot tell; --check only compares. src/update.ts holds all of it.
