@tonbo/cli 0.11.1 → 0.12.0

package/README.md

@@ -13,15 +13,20 @@ tonbo --version
 tonbo login
 tonbo database create notes
 tonbo database list --json
+tonbo database list --account acme
 ```
 
-`tonbo --help` prints the rules every command shares (output and `--json`, pages, exit status, keys and the login file, 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](https://tonbo.dev/docs/reference/cli).
+`tonbo --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](https://tonbo.dev/docs/reference/cli).
 
-The login and the credentials file are shared with [`yield`](../yield) through `@tonbo/cli-core`, by the contract [`credentials-v1.json`](../../contracts/cli/credentials-v1.json).
+## Sign in
+
+`tonbo login` signs this computer in as you, once ([ADR-0018](../../apps/user-center/docs/decisions/adr-0018-one-cli-login-per-person.md)): 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.
+
+The login file, `login.json`, and the device id it is tied to are shared with [`yield`](../yield) through `@tonbo/cli-core`, by the contract [`credentials-v2.json`](../../contracts/cli/credentials-v2.json). A login an earlier release saved, `credentials.json` ([`credentials-v1.json`](../../contracts/cli/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](../../contracts/management/openapi-v1.yaml) 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, or the Volume a `machine create` or `update --volume` names, read for its id and region); `tonbo machine logs`, once it ships, is the named Streams exception, reading the stream at the Machine's `logs.url`. 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.
+Every command other than `login` and `logout` is named by one operation of the [Management API](../../contracts/management/openapi-v1.yaml) 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, or the Volume a `machine create` or `update --volume` names, read for its id and region); `tonbo machine logs`, once it ships, is the named Streams exception, reading the stream at the Machine's `logs.url`. 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`, `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`](src/app.ts) defines each command, its arguments and flags with their one-line descriptions, and [`src/help.ts`](src/help.ts) holds the long help, each flag's default, the examples, the shared rules and the environment. [`commands.json`](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`.