@kutrion/cli 0.0.0-stage → 1.2.0

package/README.md

@@ -1,3 +1,188 @@
-# Temporary Holding Version
+# Kutrion CLI (`kt`)
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Vaults, credentials and SSH/SFTP/RDP brokering from the terminal. The published package is a single
+self-contained bundle (the shared client, `ws` and `@noble/post-quantum` are inlined at build time),
+so it installs with no transitive dependencies.
+
+## Install
+
+Download the CLI tarball from https://kutrion.com/downloads, then install it with npm from the folder
+you saved it in. It needs Node 18 or newer and pulls in no dependencies:
+
+```sh
+node -v                                  # must report v18 or newer
+npm i -g ./kutrion-cli-<version>.tgz     # the leading ./ is required; use the file name you downloaded
+kt --version
+```
+
+`npm i -g @kutrion/cli` does not work: the package is not on the public npm registry.
+
+## 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. 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
+kt vaults
+kt get <vaultId> <credId>
+kt conn add --name web-01 --host 10.0.0.5 --username deploy --cred <credId>
+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.
+
+`--base <url>` (or `KT_API_BASE`) points at a server; the token is stored in the OS keychain. There
+is no default: unconfigured, `kt` exits non-zero rather than guessing an address to send credentials
+to. `login` also refuses a plaintext `http://` server unless it is loopback. On a machine with no
+keychain, `KT_TOKEN_STORE=file` keeps the token in `~/.config/kutrion/token` (mode 0600).
+
+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, 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 signed in, wire an assistant to Kutrion through the CLI's MCP bridge. Your organization's plan
+needs agent access:
+
+```sh
+kt mcp install --client claude-code      # or claude-desktop, cursor, copilot
+kt mcp status                            # each client's agent, and which clients are wired
+kt mcp uninstall --client claude-code    # revoke the agent and remove the config entry
+```
+
+`install` mints an agent for that client, keeps its credential in the OS keychain, writes the
+client's config to launch `kt mcp`, and starts the bridge once to check that it launches. The config
+holds the server address and the client name, never a credential. Follow the next step it prints for
+that client to load the new server.
+
+## Job files in CI (`kt run`)
+
+`kt run <file>` executes a declarative job file through the broker. Paired with `kt ci-login`, which
+exchanges the pipeline's own OIDC token for a short-lived principal, a CI job needs no stored
+Kutrion credential and the job file in the repo holds no secret: connections are referenced by name
+and resolved against the caller at run time. A literal `password:`/`value:`/`token:` key anywhere in
+the file is rejected rather than used, and no step type names a vault entry at all — the credential
+a connection uses is the server's business, and a command that tries to interpolate one is refused.
+
+```yaml
+name: deploy smoke
+connections:
+  web: prod-web-01          # a connection name, or its id
+steps:
+  - name: nginx is up
+    exec: { connection: web, command: "systemctl is-active nginx" }
+    expect: { exit_code: 0, stdout_contains: active }
+
+  - name: pull the config
+    get: { connection: web, remote: /etc/nginx/nginx.conf, local: ./nginx.conf }
+
+  - name: publish the healthcheck
+    put: { connection: web, local: ./health.sh, remote: /usr/local/bin/health.sh }
+
+  - name: mirror the artifacts
+    sync:
+      from: { connection: web, path: /var/artifacts }
+      to: { connection: web, path: /backup/artifacts }
+      mirror: true
+```
+
+Each step carries exactly one action (`exec`, `get`, `put`, `sync`). `expect` applies to `exec` and
+supports `exit_code`, `stdout_contains`, `stderr_contains`, `stdout_not_contains` and
+`stdout_matches`; a step that asserts nothing still requires exit code 0. The run stops at the first
+failed step and reports the rest as skipped, unless that step sets `continue_on_error: true`.
+
+There is no `rotate` step. It was accepted once and is withdrawn: rotating changes a stored
+credential, so a job file naming the wrong one can lock every human out of that system. A file that
+still carries one is refused with that reason rather than silently ignored. Rotate with
+`kt rotation run` or from the web app, where a person is present.
+
+```sh
+export KT_AGENT_TOKEN=$(kt ci-login --trust $KT_OIDC_TRUST_ID)   # exchange the pipeline's OIDC token
+kt run kutrion.yml                         # console reporter, exits non-zero on failure
+kt run kutrion.yml --reporter junit --out report.xml
+kt run kutrion.yml --dry-run               # validate and list the steps, touch nothing
+```
+
+On GitLab, the job's OIDC token comes from an `id_tokens:` block that exposes it as `KT_ID_TOKEN`,
+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, `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 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 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
+GitLab job renders it once the job declares `artifacts:reports:junit`, and GitHub needs a reporting
+action — the file alone is not picked up. With `--out` the report is written to a file and progress
+goes to stderr, so the console stays readable while a machine consumes the file.