@kutrion/cli 1.2.14 → 1.2.21

package/README.md

@@ -34,13 +34,18 @@ 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. When the account signs in with an emailed code, a blank entry or `r` at the prompt sends a new
-code. A script pipes the password instead, with `--code` when the account has a second factor:
+history. An account with no authenticator app or security key is emailed a 6-digit code at every password
+sign-in, and `login` prompts for it; a blank entry or `r` at the prompt sends a new code. `--code` passes an
+authenticator-app code. A password piped on stdin is for an account that has an authenticator app:
 
 ```sh
-printf '%s\n' "$KT_PASSWORD" | kt login --email you@example.com --password-stdin
+printf '%s\n' "$KT_PASSWORD" | kt login --email you@example.com --password-stdin --code 123456
 ```
 
+Without `--code`, an emailed-code account stops there with a message, because stdin cannot also answer the
+prompt. Scripts and CI should not sign in with a password at all: they use an agent token (`KT_AGENT_TOKEN`
+with `kt exec`, `kt run` or `kt action run`).
+
 With no `--email` and no `--password-stdin`, `login` first asks the Kutrion app on this computer to sign the CLI in,
 and falls back to the email and password when no app answers. Without a terminal it asks only an app this CLI has
 already paired with, because the first pairing needs you to type `yes`. When a later command is refused because the
@@ -74,11 +79,32 @@ kt ssh <connId>
 kt --help
 ```
 
+When `kt conn add` or `kt conn set` leaves a credential not yet authorized for the connection's host, a terminal is asked to type yes and the saved value authorizes it. `--yes` skips the question, `--no-authorize` skips the step, and `--json` never asks.
+
 `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>
+and `kt cred set` prompt for the value, or read it from stdin with `--value-stdin`. `--value-stdin` stores a value that contains a newline (an SSH key, a PEM block, a `.env`) byte-for-byte, final newline included, so it equals its source file; a single-line value (`echo pw | kt ...`) loses its one terminating newline. `--password-stdin` follows the same rule. `kt export <vaultId>
 <file>` and `kt audit export <file>` write the file owner-only (mode 0600), tightening an existing file
 before writing to it.
 
+`kt export` releases a whole vault in plain text, so it needs a request confirmed in the same session: it
+asks for your authenticator code, then for the code mailed to your account email for that request. Without
+a terminal, `kt export <vaultId> --request` prints the request id and exits 19; then, in the same session
+and within 10 minutes, run `kt step-up` and pipe the mailed code to
+`kt export <vaultId> [file] --code-stdin <requestId>`. A passkey cannot be checked in a terminal, so an account
+with no authenticator app exports from the web app. Unattended, scheduled export is not supported.
+
+In a Private vault, `kt cred add` and `kt cred set` ask for your vault passphrase (or read it with
+`--vault-passphrase-stdin`, as `kt get --reveal` does), seal the value and notes on this machine and
+send only the ciphertext. With both `--value-stdin` and `--vault-passphrase-stdin`, stdin carries the
+passphrase on its first line and the value after it:
+`printf '%s\n%s' "$PASSPHRASE" "$VALUE" | kt cred add <vaultId> --name db --value-stdin --vault-passphrase-stdin`.
+`kt cred dest add <vaultId> <credId> --host <h>` lists the hosts and asks you to type yes; without a terminal pass `--yes` to authorize without the question (it exits 2 without it). `--enter-value` always needs a terminal.
+A rename alone needs no passphrase. `kt import` refuses a Private vault, because the export file is
+parsed by the server; nothing is sent. A write with `--vault-passphrase-stdin` to a vault the server
+says is not Private is refused before stdin is read. The CLI also remembers, per server, the ids of
+the vaults it has seen Private (`~/.config/kutrion/private-vaults.json`, mode 0600, ids only), and
+refuses a write when one of them later answers as not Private.
+
 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.
@@ -121,12 +147,19 @@ The exit status says what kind of failure it was, so a script can branch without
 | 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) |
+| 13 | Not found (404), including an id that is not well formed |
 | 14 | Conflict with the current state (409) |
 | 15 | Rate limited (429) |
 | 16 | Server error (5xx) |
+| 17 | A download stalled: no bytes for `--stall-timeout` seconds (`kt sftp get`, `kt file get`); the error prints the `--resume` command |
+| 18 | `kt exec` lost its connection after the request was sent, or the session ended without an exit status: the command may have run (see below) |
+| 19 | `kt export --request`: the export request was made and is pending until confirmed in this session; `kt grant wait`: the request is still pending after 540 seconds |
+| 20 | `kt mcp status`: an agent credential expired, is due its 90-day confirm, or reached the end of its confirmed lifetime; its owner can renew or confirm it |
+| 21 | `kt mcp status`: an agent credential was revoked; reissue it with `kt mcp install` |
+
+`kt grant wait <id>` follows a request for up to 540 seconds and exits 0 when it is approved or done, 12 when it was denied or refused, 13 when it expired or is no longer available, 14 when it was canceled or replaced by a newer request, and 19 when it is still pending at the limit; run it again to keep following.
 
-`kt exec` exits with the remote command's own status, with or without `--json`.
+`kt exec` exits with the remote command's own status, with or without `--json`. Status 18 is the exception, and only it: the connection to Kutrion dropped after the command was sent (or the host ended the session with no exit status, as when a command restarts the host's SSH service), so the command may have run. Check with a status command or `kt audit --action SSH_EXEC_STARTED` before repeating it. For a command that ends the session or the broker on purpose, `kt exec --detach <conn> <command...>` starts it on the host outside the session under `nohup` (the command is sent in plain text as the literal `sh -c` argument, so the risk gate, exec policy and audit row see it as typed; the job's pid, output and exit code go in `${XDG_STATE_HOME:-$HOME/.local/state}/kt-detach`, which must be a mode 700 directory owned by the user, not a symlink) and prints a handle at once with status 0. `kt exec <conn> --status <handle>` then reports `running`, `finished` with its exit code, or `unknown`, followed by the last 4096 bytes of the output; Kutrion stores no output. The start and each check are audited as ordinary execs with their command. `--detach` is refused when exec is limited to an allowlist, because the wrapper is a different command from the one allowed. A connection that fails before anything is sent keeps its ordinary error and status.
 
 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
@@ -141,14 +174,84 @@ 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 status                            # each client's agent (live, expiring, expired or revoked), 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.
+that client to load the new server. The default scopes cannot run commands; add `--scopes` with
+`ssh.exec` for that, and the install asks for an authenticator code first.
+
+### Keep an installed agent alive (`kt agent keepalive`)
+
+An agent with ssh or files access is granted at most 7 days at a time. Keepalive replaces its agent token
+before then, so the client keeps working without a reinstall. It is off unless you turn it on:
+
+```sh
+kt mcp install --client claude-code --keepalive   # at install
+kt agent keepalive --on --client claude-code      # for an existing install
+kt agent keepalive --off [--client claude-code]   # stop; the timer goes when no client is left
+```
+
+A timer (a launchd LaunchAgent on macOS, a `systemd --user` timer on Linux) runs
+`kt agent keepalive --run` every 6 hours. The timer holds only the path to `kt` and those arguments,
+no credential and no `KT_` variable, and logs ids and outcomes to `~/.config/kutrion/keepalive.log`
+(mode 0600). A run rotates an agent, with your `kt` session, when it has under 3 days left and the
+`kt mcp` bridge used it on this machine in the last 7 days, so the agent token is replaced about every 4
+days while the machine is in use. It writes the new agent token to the client's keychain slot, and a
+running bridge picks it up on its next call. A run skips the agent when the keychain is locked or the
+slot holds a different agent's token, and stops trying when the server refuses the rotate (revoked,
+step-up required, or its 90-day confirm is due). `kt mcp status` shows the days left and what the last
+run did, with the remedy when there is one; it is usually `kt mcp install --client <id> --keepalive`.
+
+An agent with `ssh.exec` is not kept alive: rotating or renewing it asks for a step-up, which the timer
+cannot give. It lasts up to 7 days unless renewed with a step-up in the web app, and is then minted again
+with `kt mcp install`, which asks for a code;
+`--keepalive` is refused together with `ssh.exec`, and a reinstall that adds `ssh.exec` turns an earlier
+opt-in off.
+
+Every rotate is recorded in the audit log. Windows has no timer yet, and keepalive needs the OS keychain
+(not `KT_TOKEN_STORE=file`). A bridge fed by `KT_AGENT_TOKEN` must not opt in: keepalive replaces the
+agent token in the keychain slot, which that bridge never reads, so the rotate would strand it.
+
+## List your agents (`kt agent ls`)
+
+`kt agent ls` lists your agents, including expired and revoked ones, with each one's state (`live`,
+`expiring` within 14 days, `expired` or `revoked`), its expiry and when it was last used. `--json` prints
+the same fields as JSON.
+
+## Mint an agent for a server (`kt agent mint`)
+
+For a cron job or service that has no browser to sign in with:
+
+```sh
+kt agent mint --scope-vault prod --write-env /etc/kutrion/agent.env
+```
+
+It mints an agent for the signed-in account and prints the token once. `--scope-vault` and
+`--scope-conn` (repeatable, id or name) limit it to those vaults or connections; with none it reaches
+everything you can. `--scopes`, `--days`, `--egress lan|cloud` and `--name` set its scopes, lifetime,
+AI egress class and label. `--write-env <file>` writes `KT_AGENT_TOKEN` and `KT_API_BASE` to a 0600
+file instead and never prints the token; an existing file needs `--yes`. Source the file in the job
+and run `kt run` or other commands as that agent.
+
+When the organization gates agent minting behind a passkey approval, `kt agent mint` requests the approval,
+prints a presence code once on stderr, and waits. Open the link mailed to your account email, approve with
+your passkey and type the code on the approve page; kt then mints the agent from the same session and prints the
+token once. The approval must be finished within 5 minutes. If kt is interrupted after the approval,
+`kt grant wait <requestId> --complete` finishes the mint from the same session (the presence code cannot be shown
+again). An account that approves with a mailed code instead cannot mint from the CLI; use the web app.
+
+### Workloads (`kt agent mint --workload`)
+
+For an unattended engine such as n8n: `kt agent mint --workload client_secret --scope-vault prod --name n8n` mints a
+workload and prints its `client_id` and `client_secret` once; `--workload static` prints a bearer token instead (and
+accepts `--write-env`). A workload must name its vaults with `--scope-vault`; `--exec-mode allowlist|unrestricted` sets
+what its commands may be. Minting needs a fresh step-up. `kt agent rotate <id>` issues a new secret (the old one stops
+working at once) and `kt agent revoke <id>` ends one agent or workload. Refused token requests for a workload client are
+audit rows: `kt audit --action AGENT_TOKEN_REFUSED`.
 
 ## Job files in CI (`kt run`)
 
@@ -192,7 +295,8 @@ still carries one is refused with that reason rather than silently ignored. Rota
 `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_AGENT_TOKEN=$(kt ci-login --trust $KT_OIDC_TRUST_ID) || exit 1   # exchange the pipeline's OIDC token
+export KT_AGENT_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
@@ -200,7 +304,48 @@ kt run kutrion.yml --dry-run               # validate and list the steps, touch
 
 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.
+`permissions: id-token: write` and `ci-login` requests the token itself, for the audience in
+`KT_OIDC_AUDIENCE` (default `kutrion`). A trust registered with a different audience needs
+`KT_OIDC_AUDIENCE` set to that value in the job, or a new trust with `--audience kutrion`.
+
+Register the trust with `kt trust add --issuer <url> --audience <aud> --subject <pattern> --vault <id>`.
+`--vault` and `--connection` are repeatable. Any `ssh.*` or `files.*` scope needs at least one
+`--connection <id>` (`--conn` is an alias), and `ssh.exec` also needs `--exec-mode unrestricted`, a full
+shell as the connection's account and the only mode available today.
+
+`kt trust ls` shows each trust's status (`live`, `confirm_due`, `confirm_overdue` or `suspended`) and, for a
+suspended trust, the reason. A credential event, or a bulk revoke run with `--include-trusts`, suspends a
+trust: its exchanges are refused until its owner runs `kt trust resume <id>`. Resuming is confirmed like
+creating: an authenticator code, then the code mailed to you (`--request` and `--code-stdin <requestId>`
+split it for scripts). Only the owner can resume a trust.
+
+Grants have two approval paths, and the server picks one from the account's factors; `kt` follows whichever it
+answers (`path` in the request). `kt` always says it can follow the link path (`x-grant-paths: link`).
+
+- `code`: the code mailed to your email, after an authenticator app check, as above. An account with no passkey stays
+  on this path, so its only factors are the mailbox and the authenticator app: a person who holds both can approve.
+  Adding a passkey moves the account to the `link` path.
+- `link`: an account with a passkey gets an approve link by email and no code. Open it in a browser, approve with
+  the passkey and type the presence code `kt` printed to stderr as `XXXX-XXXX` when the request was made. The
+  code comes only from that terminal; Kutrion never sends it. `kt` shows it once and never writes it to a file,
+  the config, a log or the keychain; `--json` output includes it. `kt trust add` then waits for the approval.
+  `kt trust add` and `kt trust resume` need a terminal for either path unless `--request`, `--json` or
+  `--code-stdin` is given, and say so before any request is sent.
+
+`kt grant wait <id>` follows a request by id (polling every 10 seconds, for up to 540 seconds; exit status above) and resumes after a crash or Ctrl-C, but it
+cannot show the presence code again; if it was lost, request again. A `--request` on the link path prints the id,
+the presence code and exits 19; run `kt grant wait <id>` to follow it. If an earlier request was already approved
+and is waiting to be finished, the new request is refused (`grant_request_approved`); `kt` names the device that
+asked and follows that request, and it can be replaced 5 minutes after its approval. A request ends as `denied`,
+`expired`, `cancelled`, `superseded` or `refused`; `refused` means it was refused before it was approved, so
+request again.
+
+```sh
+kt agent revoke --filter owner --owner <userId> --reason "laptop lost" --include-trusts
+```
+
+`kt agent revoke` revokes agents in bulk by `--filter all|owner|client|scope`. `--include-trusts` also
+suspends the trusts in scope (not with `--filter client`) and prints `trusts_suspended`.
 
 **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
@@ -208,7 +353,11 @@ the REST API. It has to: a principal from `ci-login` is an opaque `vta_` token,
 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.
+stored session over REST, unchanged, except in CI (`CI` set to anything but empty, `false` or `0`): there a missing `KT_AGENT_TOKEN` is an
+error and `kt run` never falls back to a stored login. `--dry-run` needs neither.
+
+Assign the token on its own line, as above. `export KT_AGENT_TOKEN=$(kt ci-login ...)` returns the exit
+status of `export`, so a failed login would not stop the job.
 
 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