@kutrion/cli 0.0.0-stage → 1.1.6

package/README.md

@@ -1,3 +1,140 @@
-# 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 login
+
+```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`:
+
+```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
+```
+
+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, 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
+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.
+
+## 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
+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 — or `--token <vta_…>` — `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
+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
+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.