feat: secrets

README.md

@@ -44,9 +44,9 @@ By default skills land under the agent's standard directory (`~/.claude/skills/`
 
 ### `excloud-cli`
 
-Safe end-to-end control of Excloud resources through the `exc` CLI. Covers compute (create / inspect / resize / restart / terminate, delete protection, exec / scp / console), networking (subnets, public IPv4, security groups and rules/bindings), volumes and snapshots, SSH keys, Kubernetes (clusters, workers, kubeconfig fetch / merge), object storage buckets (bucket lifecycle, object copy/sync/delete/share, access keys, multipart uploads), IAM (accounts, service accounts, API keys, policies), billing, quota, serial console logs, and metrics.
+Safe end-to-end control of Excloud resources through the `exc` CLI. Covers compute (create / inspect / resize / restart / terminate, delete protection, exec / scp / console), networking (subnets, public IPv4, security groups and rules/bindings), volumes and snapshots, SSH keys, Kubernetes (clusters, workers, kubeconfig fetch / merge), object storage buckets (bucket lifecycle, object copy/sync/delete/share, access keys, multipart uploads), org secrets (path-addressed encrypted store with versions, audited reveals, value-source flags, reveal output combinators), IAM (accounts, service accounts, API keys, policies), billing, quota, serial console logs, and metrics.
 
-**Use when:** the user asks to plan or run `exc` commands, provision / introspect / tear down VMs, attach a public IP, adjust a security group, pull a kubeconfig, manage buckets or S3 access keys, debug a stuck boot via serial logs, or exec / scp against a VM.
+**Use when:** the user asks to plan or run `exc` commands, provision / introspect / tear down VMs, attach a public IP, adjust a security group, pull a kubeconfig, manage buckets or S3 access keys, save / reveal / rotate an org secret, debug a stuck boot via serial logs, or exec / scp against a VM.
 
 **Key guidance the skill encodes:**
 

skills/excloud-cli/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: excloud-cli
-description: Drive Excloud resources (compute, networking, security groups, volumes, snapshots, public IPs, IAM, billing, Kubernetes, object storage buckets) through the `exc` CLI. Use when a user asks to plan or execute `exc` commands - creating / inspecting / updating / deleting VMs, running commands on them via `exec` / `scp` / `console`, managing security groups and public IPs, pulling Kubernetes kubeconfigs, or managing buckets/objects/access keys - with safety guardrails and auth checks.
+description: Drive Excloud resources (compute, networking, security groups, volumes, snapshots, public IPs, IAM, billing, Kubernetes, object storage buckets, secrets) through the `exc` CLI. Use when a user asks to plan or execute `exc` commands - creating / inspecting / updating / deleting VMs, running commands on them via `exec` / `scp` / `console`, managing security groups and public IPs, pulling Kubernetes kubeconfigs, managing buckets/objects/access keys, or saving / revealing / rotating org secrets - with safety guardrails and auth checks.
 ---
 
 # Excloud CLI
@@ -49,6 +49,7 @@ Require explicit user confirmation before running any of these:
 - `exc account revoke`, `exc serviceaccount delete`, `exc apikey delete`, `exc policy delete`, `exc policy binding delete`.
 - `exc buckets delete`, `exc buckets rm`, `exc buckets objects delete`, recursive bucket/object deletes, and `exc buckets multipart abort`.
 - `exc buckets keys delete`; also treat `exc buckets keys create` output as sensitive because the secret is shown once.
+- `exc secret delete` (soft-delete, no undo); also `exc secret reveal` — every call writes an audit event, so don't run it for "discovery".
 
 For shell commands delivered through `exc compute exec` or an `exec` script file, refuse or confirm explicitly before running anything like `shutdown`, `reboot`, `rm -rf`, `mkfs`, `dd`, `wipefs`, rewrites of `/etc/fstab`, bootloader edits, or `systemctl stop ssh*` (the last one will make the VM unreachable over SSH — see Interactive access).
 
@@ -343,6 +344,32 @@ Normal users should prefer `objects upload`; it automatically uses multipart for
 - `exc buckets multipart complete <bucket> <uploadId> --parts '<json-array>'` — `--parts` can be inline JSON or a path to a JSON file.
 - `exc buckets multipart abort <bucket> <uploadId>` — destructive cleanup of an unfinished upload.
 
+## Secrets
+
+`exc secret …` stores org-scoped values encrypted at rest with versioning and an audit trail. Path-addressed (`/database/prod/password`, must start with `/`), unique per org while active; soft-delete only — there is no undo, but a deleted path can be re-used immediately.
+
+Every command that targets one secret accepts `--id` or `--path` (mutually exclusive); `--path` is resolved client-side via `lookup`.
+
+**Value source flags** (`create`, `version add`) are mutually exclusive — exactly one of `--value <inline>`, `--from-file <path>`, `--from-stdin`. Prefer `--from-stdin` (TTY prompts without echo) or `--from-file` over `--value` — inline values land in shell history.
+
+**`reveal` is the only plaintext-returning command and every call writes an audit row.** Default prints the value to stdout with a trailing newline; non-obvious output combinators:
+
+- `--out <path>` — write to file with mode `0600` (preferred for multi-line blobs like kubeconfigs).
+- `--copy` — copy to OS clipboard (`pbcopy` / `wl-copy` / `xclip` / `xsel`).
+- `--env VAR` — emit a shell-safe `VAR='…'` line for `eval $(exc secret reveal --path /foo --env FOO)`.
+- `--silent` — suppress the stdout print of the value (combine with `--out`/`--copy`).
+- `--version <n>` — pin a specific historical version; default is the latest.
+
+On a TTY, `reveal` also prints a stderr note "Revealed version N of secret M (audited)" so a human sees the audit happened; piped consumers don't see this.
+
+**409 on create** is rewritten to: `a secret already exists at <path> — add a new version with 'exc secret version add --path <path> --from-stdin'`. Take the hint — don't `delete` an existing secret just to re-create it unless that's what the user actually wants.
+
+**Naming convention used elsewhere in the codebase** is `/{service}/{resource_id}/{field}` (e.g. `/database/17/password`, `/kubernetes/prod/kubeconfig`, `/api-keys/<hash>/token`). Stick to lowercase, slash-separated; don't put `org_id` in the path (already scoped).
+
+`exc secret delete` requires `--yes` in non-interactive shells (refuses otherwise); on a TTY it prompts `Type yes to continue`. Soft-deleted secrets disappear from `list`/`lookup`/`get` but the audit history survives.
+
+`exc secret list` / `events` / `version list` render tables; empty states go to stderr with a hint.
+
 ## IAM, billing, quota
 
 - `exc org list`