@ricsam/r5dctl 0.0.126 → 0.0.128

package/README.md

@@ -1,6 +1,6 @@
 # @ricsam/r5dctl
 
-CLI for managing r5d.dev platform resources (projects, branches, and sessions).
+CLI for managing r5d.dev account instructions, environment variables, secret files, projects, branches, and sessions.
 
 ## Installation
 
@@ -39,6 +39,40 @@ Credentials are stored in:
 - `-b, --branch <branch>`
 - `-s, --session <sessionId>`
 
+## Account instructions and credentials
+
+The same commands work for authenticated users and agents. They manage the authenticated account across all projects, workspaces, and workers. Project, branch, and session flags do not narrow their scope.
+
+```bash
+r5dctl account instructions get > AGENTS.md
+r5dctl account instructions set --file AGENTS.md
+cat AGENTS.md | r5dctl account instructions set --stdin
+printf '' | r5dctl account instructions set --stdin  # clear account instructions
+r5dctl --json account instructions get
+
+r5dctl account env list
+r5dctl account env set API_TOKEN --description "Service API access" --file ./api-token.txt
+r5dctl account env set REGION --description "Default region" --value eu-north-1
+cat ./api-token.txt | r5dctl account env set API_TOKEN --stdin
+r5dctl account env set API_TOKEN --description "Updated purpose"  # preserve its value
+r5dctl account env revoke API_TOKEN  # remove the value, retain its metadata
+r5dctl account env delete API_TOKEN  # remove the entry
+
+r5dctl account secrets list
+r5dctl account secrets set KUBECONFIG --description "Personal Kubernetes access" --file ~/.kube/config
+cat ./private-key.pem | r5dctl account secrets set PRIVATE_KEY_FILE --description "Signing key" --stdin
+r5dctl account secrets revoke PRIVATE_KEY_FILE
+r5dctl account secrets delete PRIVATE_KEY_FILE
+```
+
+`instructions get` writes the saved AGENTS.md content exactly, with no extra newline. With `--json`, it returns an object containing `content` and `updatedAt`. Setting instructions requires exactly one of `--file` or `--stdin`; empty input clears them. File and stdin input must be UTF-8, and leading/trailing whitespace, line endings, and a UTF-8 BOM are preserved. Stdin is read only with an explicit `--stdin` flag.
+
+`env` entries are delivered as environment variable values. `secrets` entries are delivered as protected files, with each entry's environment variable containing the file path. Both kinds are encrypted at rest. Their names share one account namespace and must be valid environment variable names, at most 128 characters; `R5D_` and `R5DCTL_` prefixes are reserved. The CLI refuses to change an entry's kind through the other command group.
+
+New entries require `--description` and one value source. Existing entries preserve their description when the flag is omitted, and preserve their value when only a description is supplied. `--value` is supported only for `env`; use `--file` or `--stdin` for secret files and sensitive environment values so contents are absent from shell arguments and history. Explicit empty input sets an empty value; use `revoke` to remove the value. Lists show metadata and whether a value is configured, including under `--json`; neither lists nor mutation responses print values. There is no command to read stored credential values.
+
+Updates and revocations affect future command delivery. Existing commands and interactive shells keep their current environment until they finish or are restarted. Revoke does not invalidate a credential at its provider or remove a copy already retained by a process; rotate the provider credential when that is needed.
+
 ## Common Commands
 
 ```bash
@@ -111,22 +145,8 @@ r5dctl -p <project> -b <branch> ps list --worker <label>
 r5dctl -s <session-id> ps list --json
 r5dctl ps stop <run-id>
 
-r5dctl k8s usage
-r5dctl k8s usage --namespace default --workload api --container server
-r5dctl k8s usage --window 7d
-r5dctl k8s usage --workload default/api --window 7d --json
-r5dctl vcluster trusted-workflow add --repo owner/repository --workflow .github/workflows/deploy.yml
-r5dctl vcluster trusted-workflow list
-r5dctl vcluster trusted-workflow remove <workflow-id>
 ```
 
-Trusted workflows authenticate Kubernetes through the dedicated
-`ricsam/r5d-cluster-auth` GitHub Action. They do not run or authenticate
-`r5dctl` inside GitHub Actions, and no R5D secret needs to be stored in the
-repository. Trust applies to that workflow path on every Git ref and grants
-cluster-admin, so protect workflow changes and do not invoke it for untrusted
-pull requests.
-
 `create branch` creates a linked worktree branch through the platform from an existing branch's checkout, with the same `--source worktree:<branch>` and `--working-tree carry|clean` semantics as `session start --new-worktree` (carry is the default) and no session prompt. `--worker <label>` selects the connected worker that cuts the checkout; omitted, the platform chooses one, and an r5d worker shell's temporary credential is always bound to its own worker. The command returns as soon as the operation is accepted and prints its id; `describe branch-operation <operation-id>` reports `provisioning`, `ready`, or `failed` with the worker and any error. Neither prints a commit hash: read the branch with git in its checkout once it is ready.
 
 `delete branch` removes one or more branches and every session on them through the platform, which is the only supported way to remove a linked worktree: the platform owns those checkouts, so never run `git worktree remove`, `git worktree prune`, or `git branch -D` inside a project checkout. Without `--confirm` it prints each branch and its sessions and exits non-zero without deleting anything. With `--confirm` each branch is resolved to the exact managed branch it names today, its deletion is accepted at once by the platform, and the command waits (polling every 2 seconds, up to 10 minutes) until the platform reports it completed before requesting the next one; a failure does not stop the remaining deletions, and the exit status is non-zero if any branch failed. `--no-wait` prints the accepted branch id instead of waiting; `describe branch-deletion <branch-id>` reports `pending` (with the retry reason when the worker has not answered yet), `failed` with the platform's error, or `completed`, and answers `completed` for a branch id that no longer exists. The deletion stays bound to that branch id: a same-name branch created afterwards is never deleted by an old request, and re-running the command for a branch whose deletion failed retries it. The primary branch `main` is refused before anything is deleted, as is a branch with a running agent or active process (stop them first); a name that only has sessions and no managed branch is refused too (delete those sessions with `delete session`). On a server that predates the route, the command explains that the server does not support `delete branch` yet instead of reporting a missing branch.
@@ -157,9 +177,7 @@ Add `-f`/`--follow`/`--watch` to `session start` to poll the provisioning handle
 
 `ps list` shows active long-running commands managed by r5d. It does not expose the worker host's general OS process table or interactive PTYs. Global project, branch, and session options filter the list, while `--worker` selects a worker label. The `LANE` column names the worker command lane each run holds (`general`, `utility`, or `control`) or waits for (`queued:general`), from the worker's latest capacity report; `-` means the worker did not report the run. `ps stop` sends `SIGTERM` to the selected run. Inside an r5d-provided worker shell, the temporary credential can only list and stop runs on that shell's worker.
 
-A managed worker runs two general shells at a time; a third waits up to 60 seconds and then fails with "command capacity is busy". Coordination does not compete for those slots: when an agent shell runs one plain `r5dctl` coordination command (`ps list`, `ps stop`, `workspace status`, `session status|stop|prompt|claim|claims|process-log`, `describe …`, `get …`, `sessions recent`, the `conversation` read forms, `create|update|delete session`, `answer-questions`, `answer-env-request`) with plain or simply quoted arguments, the platform runs it in a reserved control lane: two small slots, no shell, a 120-second limit. Shell operators, pipes, redirections, `$` expansions, environment assignments, wrappers, paths to r5dctl, `--`, `--follow`, and credential or endpoint flags make it an ordinary shell command again. `workspace status` prints each worker's lane totals, holders, and queue.
-
-`k8s usage` shows current and rolling CPU and memory usage for every workload container in your managed vCluster. The default window is `24h`; pass `--window 7d` for seven days. Filter with `--namespace`, `--workload`, or `--container`; a workload may be identified by name, `namespace/name`, or Kubernetes UID. Human-readable output shows current totals across sampled replicas and the selected window's maximum. Global `--json` includes min/max summaries, the complete five-minute history envelope, per-pod series, coverage, and freshness metadata.
+The worker host determines execution capacity. If its configured command launcher provides a reserved control lane, an agent shell can use it for one plain `r5dctl` coordination command (`ps list`, `ps stop`, `workspace status`, `session status|stop|prompt|claim|claims|process-log`, `describe …`, `get …`, `sessions recent`, the `conversation` read forms, `create|update|delete session`, `answer-questions`, `answer-env-request`) with plain or simply quoted arguments. The command runs without a shell, using the launcher's control capacity and runtime limit. Shell operators, pipes, redirections, `$` expansions, environment assignments, wrappers, paths to r5dctl, `--`, `--follow`, and credential or endpoint flags make it an ordinary shell command again. `workspace status` prints each worker's lane totals, holders, and queue.
 
 `get envs` reports names and whether values are set without revealing the values by default. Add `--show-values` to reveal every value; multiline and control characters are escaped for readable output. Without the global `--json` flag, `get env <name>` writes only that value to stdout, with no added newline or labels, so it works directly with command substitution and pipelines: