@kutrion/cli 1.1.6 → 1.2.0

package/README.md

@@ -17,15 +17,21 @@ kt --version
 
 `npm i -g @kutrion/cli` does not work: the package is not on the public npm registry.
 
-## First login
+## First sign-in
 
 ```sh
 kt --base https://kutrion.com login --email you@example.com
 ```
 
 `login` prompts for the password (and a 2FA code when the account has one), so neither lands in shell
-history; `--password` and `--code` exist for scripts. A successful login saves the server to
-`~/.config/kutrion/config.json`, so every command after it needs no `--base`:
+history. A script pipes the password instead, with `--code` when the account has a second factor:
+
+```sh
+printf '%s\n' "$KT_PASSWORD" | kt login --email you@example.com --password-stdin
+```
+
+A successful login saves the server to `~/.config/kutrion/config.json`, so every command after it
+needs no `--base`:
 
 ```sh
 kt whoami
@@ -36,6 +42,23 @@ kt ssh <connId>
 kt --help
 ```
 
+`kt get` prints a credential with its value hidden; add `--reveal` to print the value. `kt cred add`
+and `kt cred set` prompt for the value, or read it from stdin with `--value-stdin`. `kt export <vaultId>
+<file>` and `kt audit export <file>` write the file owner-only (mode 0600), tightening an existing file
+before writing to it.
+
+Secrets passed as flags (`--password`, `--value`, and `--token` on `kt run`, `kt mcp` and
+`kt ci-login`) are refused before anything is sent: a flag lands in shell history and in the process
+list. Use `--password-stdin`, `--value-stdin`, `KT_AGENT_TOKEN` or `KT_ID_TOKEN` instead.
+
+Saved layouts, the account-synced arrangement the web app opens at sign-in, are `kt layouts`,
+`kt layout create <name> [--default]` and `kt layout rm <id>`.
+
+Snippets, the saved commands kept in vaults, are `kt snippets`, `kt snippet show <name|id>` and
+`kt snippet run <name|id> --conn <connId> [--insert]`. `run` prints the whole command, opens a
+brokered shell and has the server type it there, with the use recorded in the audit log; `--insert`
+places it at the prompt without pressing Enter.
+
 Use the address exactly as written. The CLI does not follow a redirect on a login: a redirected POST
 is re-sent without its body, so `kt` stops and prints the address the server pointed to instead.
 
@@ -46,16 +69,41 @@ keychain, `KT_TOKEN_STORE=file` keeps the token in `~/.config/kutrion/token` (mo
 
 Precedence is `--base`, then `KT_API_BASE`, then the saved server, and only `login` writes it:
 `--base` on any other command is a one-off that reads a different server without changing the saved
-one. To switch servers, log in again; each server's token is filed under its own URL, so sessions are
-never crossed and logging into one does not end the other. `logout` clears the token for the current
+one. To switch servers, sign in again; each server's token is filed under its own URL, so sessions are
+never crossed and signing in to one does not end the other. `logout` clears the token for the current
 server and leaves the saved URL, so the next `login` needs no flag either.
 
 Environment variables set under the names earlier CLI releases used are still read when the `KT_`
 name is not set, so an existing shell profile or assistant config keeps working.
 
+## Scripting: exit status and `--json`
+
+The exit status says what kind of failure it was, so a script can branch without parsing text:
+
+| Status | Meaning |
+|---|---|
+| 0 | Success |
+| 1 | Any other failure: bad usage, an unknown flag, a transport error, another 4xx |
+| 2, 3 | Transfer commands only: partial transfer, and a job still running after the wait |
+| 10 | Not signed in, or the session was refused (HTTP 401) |
+| 11 | Needs a plan the organization does not have (402) |
+| 12 | Refused: permission, policy or step-up (403) |
+| 13 | Not found (404) |
+| 14 | Conflict with the current state (409) |
+| 15 | Rate limited (429) |
+| 16 | Server error (5xx) |
+
+`kt exec` exits with the remote command's own status, with or without `--json`.
+
+With `--json`, stdout carries only JSON. A failure is one object on stdout,
+`{ "error": "<code>", "status": <http status>, "exit_code": <n>, "message": "<text>" }` (`status` only
+when the server answered), and prompts go to stderr. A flag no command takes is refused before
+anything is sent. Answers to prompts can be piped, one per line; a prompt with no line left fails
+instead of exiting 0.
+
 ## Connect an AI assistant (`kt mcp install`)
 
-Once logged in, wire an assistant to Kutrion through the CLI's MCP bridge. Your organisation's plan
+Once signed in, wire an assistant to Kutrion through the CLI's MCP bridge. Your organization's plan
 needs agent access:
 
 ```sh
@@ -121,17 +169,17 @@ On GitLab, the job's OIDC token comes from an `id_tokens:` block that exposes it
 with the audience your trust is registered for. On GitHub Actions, give the job
 `permissions: id-token: write` and `ci-login` requests the token itself.
 
-**How a pipeline authenticates.** With `KT_AGENT_TOKEN` set — or `--token <vta_…>` — `kt run` runs
+**How a pipeline authenticates.** With `KT_AGENT_TOKEN` set, `kt run` runs
 as that pipeline principal and sends its steps to the server's agent endpoint (`/mcp`) rather than to
 the REST API. It has to: a principal from `ci-login` is an opaque `vta_` token, and every REST route
 verifies a JWT, so an exchanged principal authenticates nothing there. Routing through the agent
-endpoint is also what subjects each step to the organisation's agent tool policy and records it in
+endpoint is also what subjects each step to the organization's agent tool policy and records it in
 the flight recorder against the pipeline's identity. Without that variable `kt run` uses your own
 stored session over REST, unchanged. `--dry-run` needs neither.
 
 Two things differ on the pipeline path. A `get` step receives the file as broker-redacted UTF-8 text
 capped at 1MB rather than raw bytes, and the step says so in its output — do not use it to move a
-binary. And a step the organisation gates on a human approval is refused rather than waited on, since
+binary. And a step the organization gates on a human approval is refused rather than waited on, since
 a pipeline has nobody to ask.
 
 Reporters are `console`, `junit` and `json`. The JUnit document is standard `<testsuites>` XML; a