@shardflux/cli 0.1.0 → 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,44 @@
+# Changelog
+
+Every command and option the README shows is available from the version named here. Below 1.0, a minor release may
+break compatibility; breaking changes are marked **Breaking**.
+
+## 0.3.0 (unreleased)
+
+Needs `@shardflux/sdk` 0.6.0 or later.
+
+### Where the time went: `--timing`
+
+- `--timing` on `workspaces open`, `workspaces suspend|resume|fork|delete|close|reset` (with `--wait`, the whole wait),
+  `operations wait` and `templates draft open|test|state|discard` prints the SDK's lifecycle timing on stderr after
+  the call: the client phases (the request, each operation state seen while waiting with the server's reason, such as
+  `capacity_pending (no_ready_host)`), the operation's own server timing (queued, ran, total; start or resume path),
+  the time spent outside the server, and retries. It is printed when the call fails, times out or is interrupted
+  too, before the error, and the exit code is unchanged.
+- `workspaces exec`, `files read|write|ls` and `workspaces changes` take `--timing` too: it times the wake, when the
+  command had to wake a suspended workspace.
+- With `--json`, the timing is a `timing` field of the JSON on stdout instead (snake_case; `null` when the command
+  made no lifecycle call), and of the error document on stderr (`{"error": {...}, "timing": {...}}`). Existing fields
+  are unchanged.
+
+### Waits are the SDK's
+
+- `workspaces open` waits with the SDK's waited open: the API holds the request until the workspace is ready
+  (`Prefer: wait`, up to 20 s at a time) instead of the CLI polling and then reading the workspace. The ready
+  workspace comes with its first tool token, so the open is listed as an agent session under the CLI's label (as a
+  reopen of a running workspace already was). Output, `--timeout` and exit codes are unchanged.
+- Lifecycle commands with `--wait` use the SDK's `wait`. Output and exit codes are unchanged, except that
+  `workspaces fork --wait` prints the new workspace as it is after the fork, not as it was requested.
+- Ctrl-C ends a held open at once (exit 130); the open continues server side, and opening the key again keeps
+  waiting.
+
+## 0.2.0 (2026-09-28)
+
+Secrets (`secrets ...`, `workspaces open --secret`, `workspaces secrets`), session workspaces (`--lifetime session`,
+`workspaces close`), layered workspaces (`workspaces reset|save-as-template|changes`), templates
+(`templates list|files|diff|draft ...`), and waking suspended workspaces on use (`--no-wake`, `--wake-timeout`).
+
+## 0.1.0 (2026-09-26)
+
+First release: `login`, `whoami`, `usage`, `workspaces open|list|get|exec|suspend|resume|fork|delete|sessions`,
+`files read|write|ls`, `operations list|get|wait`, `--json`, and documented exit codes.

package/README.md

@@ -42,6 +42,8 @@ shard ws suspend acme/demo --wait
 | `SHARDFLUX_API_KEY` | Project API key (`sfk_<key id>_<secret>`). Required. `shard` never accepts the key as an argument (`--api-key`, `--token` and similar flags are refused) and never prints it; anything shaped like a key is redacted from error output. |
 | `SHARDFLUX_API_URL` | API base URL. Default `https://api.shardflux.dev`; `--api-url` overrides it. Plain `http://` is allowed only for loopback hosts. |
 | `SHARDFLUX_AGENT_LABEL` | Attribution label for the tool tokens `shard` obtains for exec and files. Default `cli`; `--agent-label` overrides it. Each label is one agent session, listed by `shard ws sessions`. |
+| `SHARDFLUX_NO_WAKE=1` | Do not resume a suspended workspace on use; same as `--no-wake` (see "Suspended workspaces" below). `--wake` overrides it. |
+| `SHARDFLUX_WAKE_TIMEOUT_MS` | Longest wait, in milliseconds, for a workspace to wake or finish a transition. Default `120000`; `--wake-timeout <ms>` overrides it. |
 | `SHARDFLUX_HTTP_KEEPALIVE=1` | Reuse HTTP connections (see "HTTP connections" below). |
 
 `shard login` stores nothing. There is no config file: the key is read from the environment on
@@ -54,22 +56,124 @@ every run.
 | `login`, `whoami` | Show the principal behind the key. |
 | `version` | Print the CLI and SDK versions. |
 | `usage [--org <id>]` | Usage summary for the current period: plan, meters and allowances. |
-| `workspaces open <key> --template <slug> [--cpu-millis N --memory-mib N --disk-gib N] [--no-wait] [--timeout 5m]` | Open by key. Creates the workspace on first use and reconnects or resumes it afterwards, never resetting it. Waits until it is ready unless you pass `--no-wait`. |
-| `workspaces list [--state S] [--prefix P] [--include-deleted] [--all] [--limit N] [--cursor C]` | One page, or every page with `--all`. The next cursor is printed on stderr. |
+| `workspaces open <key> --template <slug> [--secret NAME]... [--lifetime persistent\|session] [--cpu-millis N --memory-mib N --disk-gib N] [--no-wait] [--timeout 5m] [--timing]` | Open by key. Creates the workspace on first use and reconnects or resumes it afterwards, never resetting it. Waits until it is ready unless you pass `--no-wait`. `--secret` binds secret names (replacing the binding of an existing workspace). `--lifetime session`: the workspace is discarded when the session ends (`workspaces close` or the idle timeout), and the key then opens a new workspace. |
+| `workspaces list [--state S] [--prefix P] [--lifetime persistent\|session\|any] [--purpose standard\|template_draft\|template_test\|any] [--include-deleted] [--all] [--limit N] [--cursor C]` | One page, or every page with `--all`. The next cursor is printed on stderr. By default only persistent standard workspaces are listed. |
 | `workspaces get <id\|key>` | One workspace (deleted ones included). |
 | `workspaces exec <id\|key> [--cwd D] [--env K=V]... [--timeout T] [--stdin F\|-] -- <cmd> [args...]` | Runs argv with no shell. Output is streamed and resumes from byte offsets after dropped connections. `shard` exits with the command's exit code. Ctrl-C cancels the command. |
 | `files read <id\|key> <path> [--out F]` | Raw bytes to stdout, or to a local file. |
 | `files write <id\|key> <path> [--from F\|-] [--append] [--no-parents]` | Atomic write. The default source is stdin. |
 | `files ls <id\|key> <path> [--limit N]` | Directory listing. |
-| `workspaces suspend\|resume <id\|key> [--wait] [--timeout T]` | Lifecycle operation. Returns immediately unless you pass `--wait`. |
+| `workspaces suspend\|resume <id\|key> [--wait] [--timeout T] [--timing]` | Lifecycle operation. Returns immediately unless you pass `--wait`. |
 | `workspaces fork <id\|key> <new-key> [caps] [--wait]` | Fork into a new key. |
-| `workspaces delete <id\|key> --yes [--wait]` | Delete the workspace. Tool access ends at once; keys are never reused. |
+| `workspaces delete <id\|key> --yes [--wait]` | Delete the workspace. Tool access ends at once. The key of a persistent workspace is never reused. |
+| `workspaces close <id\|key> [--wait]` | End a session workspace now: it is deleted, and the key then opens a new workspace. A persistent workspace is refused (`not_session`). |
+| `workspaces reset <id\|key> --yes [--wait]` | Layered workspaces: wipe every change and restart on the template. The previous state stays restorable for 7 days. |
+| `workspaces save-as-template <id\|key> --template <slug> [--display-name N] [--description T] [--checkpoint ID] [--default-lifetime L] [--default-idle-timeout D] [--acknowledge PATH]... [--no-auto-publish] [--wait]` | Save a layered workspace as the next version of an organization template. `--wait` follows the build. |
+| `workspaces changes <id\|key> [--path P] [--hash] [--summary] [--all] [--limit N] [--cursor C]` | What a layered, running workspace changed against its template. |
 | `workspaces sessions <id\|key>` | Attributed agent sessions: label, principal and tokens issued. |
-| `operations list <id\|key> [--state S] [--kind K]`, `operations get <op>`, `operations wait <op> [--timeout T]` | Operations. |
+| `workspaces secrets <id\|key> [--set NAME]... [--clear]` | Show the secret names bound to the workspace and their status, or replace them. |
+| `secrets create <NAME> [--from-file F] [--description T] [--tool T]... [--allow-workspace ID]... [--org ID [--allow-project ID]... [--all-projects]]` | Create a secret. The value comes from standard input or `--from-file`, never from an argument. |
+| `secrets list [--org ID] [--include-deleted] [--all]`, `secrets get <id\|NAME>` | Secret metadata. Values are never shown. |
+| `secrets update <id\|NAME> [--description T] [--tool T]... [--allow-workspace ID]... [--any-workspace] [--allow-project ID]... [--all-projects] [--clear-projects]` | Change the description or usage permissions. |
+| `secrets rotate <id\|NAME> [--from-file F]` | Store a new value (standard input or file); older values are erased. |
+| `secrets versions <id\|NAME>`, `secrets delete <id\|NAME> --yes`, `secrets access-log <id\|NAME>` | Versions, deletion (also removes the name from every workspace binding), and the access log. |
+| `operations list <id\|key> [--state S] [--kind K]`, `operations get <op>`, `operations wait <op> [--timeout T] [--timing]` | Operations. |
+| `templates list [--owner platform\|organization] [--include-archived] [--all]` | Templates the project can open, with their open version, layouts, file list state and draft. |
+| `templates files <slug> <version> [path] [--stat] [--owner O] [--all] [--limit N]` | One directory of a version's file tree, or one entry with `--stat`. |
+| `templates diff <slug> --from <version\|base> --to <version> [--prefix P] [--change K] [--all]` | Diff two versions: added, removed, changed, type_changed, metadata. The totals come first. |
+| `templates draft open <slug> [--base slug@version] [caps] [--no-wait]` | Open the template's draft, a layered workspace you edit with `workspaces exec`/`files`. |
+| `templates draft status <slug>` | The draft's workspace, base version, states and live test instances. |
+| `templates draft state <slug> [--label T] [--wait]`, `... state <slug> --list` | Capture a state of the running draft, or list its states. |
+| `templates draft test <slug> [--state ID] [--instance-key K] [--no-wait]`, `... test <slug> --list [--include-ended]` | Open a test instance (a session on a copy of a state), or list them. |
+| `templates draft publish <slug> [--state ID] [--description T] [--default-lifetime L] [--acknowledge PATH]... [--no-auto-publish] [--wait]` | Publish the draft as the template's next version. |
+| `templates draft discard <slug> --yes [--wait]` | Delete the draft and end its live test instances. |
+
+Aliases: `ws` for `workspaces`, `ops` for `operations`, `secret` for `secrets`, `template` for `templates`.
+`shard workspaces files ...` and `shard workspaces operations ...` also work. `<id|key>` is tried as an id when it
+is a UUID. Otherwise, or if no workspace has that id, it is matched as an exact workspace key across every lifetime
+and purpose, so sessions, drafts and test instances resolve too. The live workspace wins over tombstones that ended
+sessions left with the same key.
+
+## Suspended workspaces
+
+`workspaces exec`, `files read|write|ls` and `workspaces changes` wake a suspended workspace: they
+resume it (or join the resume or open already running), wait until it runs, then run the request.
+A request made during a suspend or resume waits for the transition to finish. The request itself
+never runs twice, because the workspace refused it before doing anything.
+
+- `--wake-timeout <ms>` (or `SHARDFLUX_WAKE_TIMEOUT_MS`, default `120000`) bounds the wait. Past
+  it, `shard` exits 5 and names the operation and its state (for example `Operation <id> (open)
+  is still queued after 120000 ms`). The operation continues server side:
+  `shard operations wait <id>` keeps waiting.
+- A resume or open that fails exits 6.
+- `--no-wake` (or `SHARDFLUX_NO_WAKE=1`) turns this off. A workspace that is not running is then
+  refused at once (exit 1, `workspace_not_running`).
+
+## Timing
+
+`--timing` (0.3.0+) says where the time of an open or a wait went. After the call, `shard` prints the lifecycle
+timing that [`@shardflux/sdk`](https://www.npmjs.com/package/@shardflux/sdk) measured (its `formatTiming()`) on
+stderr. It is printed when the call fails, times out or is interrupted too, before the error, and the exit code does
+not change. A slow open reads, for example:
+
+```text
+$ shard ws open acme/demo --template python-node-browser --timing
+Workspace acme/demo (01a0e5a8-3edd-74ba-b489-d62b8925e342) is ready.
+...
+open 34.18 s, succeeded (workspace 01a0e5a8-3edd-74ba-b489-d62b8925e342, operation 01a0e5a8-3ef0-7ecb-975e-dff2d5ca6e33)
+  client: request 20.01 s (held) → capacity_pending 13.52 s (no_ready_host) → running 0.59 s → view 42 ms ∥ token 61 ms
+  server: queued 33.40 s, ran 0.62 s, total 34.02 s; start warm, boot to ready 79 ms
+  outside the server: 0.16 s
+```
+
+Here the time went to waiting for a host with capacity; the network and the VM start were fast.
+
+- **client**: phases on your clock. `request` is the API call; `(held)` means the API held it until the workspace
+  was ready, up to 20 s at a time. Then come the operation states seen while waiting, with the server's reason, and
+  reading the workspace.
+- **server**: the operation's own timing. `queued` runs until the operation began running, including any wait for
+  capacity; `ran` is the cell's work. Then the start or resume path the cell reported.
+- **outside the server**: your total minus the operation's, so network, polling and the final reads. A large value
+  with a small server total points at the connection, not at the workspace.
+- **retries**: transient failures that were retried.
+
+Which call is timed:
+
+- `workspaces open` and `templates draft open|test`: the open, including the wait unless `--no-wait`.
+- `workspaces suspend|resume|fork|delete|close|reset` and `templates draft state|discard`: with `--wait`, the request
+  and the whole wait; without it, the request.
+- `operations wait`: the wait.
+- `workspaces exec`, `files read|write|ls` and `workspaces changes`: the wake, when the command had to wake a
+  suspended workspace. Without a wake nothing is printed.
+
+With `--json`, stdout carries the timing as a `timing` field of the command's JSON instead: `action`, `outcome`,
+`workspace_id`, `operation_id`, `total_ms`, `phases` (`phase`, `reason`, `operation_id`, `start_ms`, `duration_ms`),
+`retries`, `server` (`queued_ms`, `run_ms`, `total_ms`, `start_path`, `resume_path`, `boot_to_ready_ms`, ...) and
+`outside_server_ms`. It is `null` when the command made no lifecycle call. On a failure the error document on stderr
+carries it: `{"error": {...}, "timing": {...}}`.
+
+`shard` does not stream progress while it waits. For live events, use the SDK's `onProgress`.
+
+## Secrets
+
+```sh
+printf %s "$OPENAI_API_KEY" | shard secrets create OPENAI_API_KEY     # value from standard input
+shard secrets create DATABASE_URL --from-file ./database-url.txt      # or from a file
+shard ws open acme/demo --template python-node-browser --secret OPENAI_API_KEY --secret DATABASE_URL
+shard ws exec acme/demo -- python3 agent.py                           # sees both as environment variables
+shard ws secrets acme/demo                                            # names and status, never values
+printf %s "$NEW_KEY" | shard secrets rotate OPENAI_API_KEY
+```
 
-Aliases: `ws` for `workspaces`, `ops` for `operations`. `shard workspaces files ...` and
-`shard workspaces operations ...` also work. `<id|key>` is tried as an id when it is a UUID;
-otherwise, or if no workspace has that id, it is matched as an exact workspace key.
+- Secret values are read only from standard input or `--from-file` (one trailing newline is
+  removed). `shard` refuses `--value`, `--password` and similar flags, and never prints a value.
+- Bound secrets reach every `exec` and terminal of the workspace. A name that is unknown, or a
+  secret the workspace may not use, is refused (exit 2, `secret_not_available` with the names).
+- Secrets are project secrets of the API key's project by default. `--org <id>` addresses
+  organization-wide secrets; those, and `secrets access-log`, belong to organization owners and
+  admins in the console, so a project API key gets 403 (exit 4).
+- `<id|NAME>` is tried as an id when it is a UUID; otherwise it is matched by name in the project
+  (or in the organization with `--org`).
 
 ## Output
 
@@ -82,8 +186,13 @@ otherwise, or if no workspace has that id, it is matched as an exact workspace k
   - `login`/`whoami` print `{api_url, organization_id, project_id, api_key:{id,key_id}, tool_permissions}`.
   - `exec` prints `{session_id, exit_code, term_signal, timed_out, canceled, stdout, stderr, truncated, reconnects}`.
   - `files read` prints `{path, bytes, content_base64}`; `files write` prints the write result.
+  - `secrets create`/`get`/`update` print the secret's metadata; `list`, `versions` and `access-log`
+    print `{data, next_cursor}`; `rotate` prints `{secret, version}`; `delete` prints
+    `{deleted, id, name, scope}`; `workspaces secrets` prints `{workspace_id, names, secrets}`.
 
   Errors go to stderr as `{"error": {code, message, status, request_id, ...}}`.
+- **`--timing`:** the timing goes to stderr after the output. With `--json` it is a `timing` field instead
+  (see "Timing").
 
 ## Exit codes
 
@@ -94,8 +203,8 @@ otherwise, or if no workspace has that id, it is matched as an exact workspace k
 | 2 | usage error: bad arguments, or input the API rejected as `validation_failed` |
 | 3 | not found: workspace, operation or route |
 | 4 | authentication or authorization: missing, malformed, revoked or insufficient key |
-| 5 | timeout: waiting gave up; the operation continues server side (`shard operations wait <id>`) |
-| 6 | the awaited operation ended `failed` or `canceled` |
+| 5 | timeout: waiting gave up (`--timeout`, or `--wake-timeout` while waking a workspace); the operation continues server side (`shard operations wait <id>`) |
+| 6 | the awaited operation ended `failed` or `canceled` (also a resume or open that failed while waking a workspace) |
 | 130 | interrupted (Ctrl-C). Waits stop at once, and exec sends a cancel to the session. |
 | exec | the command's own code: 124 if it timed out, 128+N if killed by signal N. Failures before the command ran use the codes above; use `--json` to tell them apart. |
 

package/dist/args.d.ts

@@ -1,4 +1,4 @@
-export declare const CLI_VERSION = "0.1.0";
+export declare const CLI_VERSION = "0.3.0";
 export interface OptionSpec {
     type: 'string' | 'boolean';
     short?: string;
@@ -32,8 +32,15 @@ export declare function parsePositiveInt(text: string, option: string, max?: num
 /** ["A=1", "B=x=y"] -> { A: "1", B: "x=y" }. */
 export declare function parseEnvPairs(pairs: readonly string[]): Record<string, string>;
 export declare const UUID: RegExp;
+/** Secret names (environment-variable safe; the API's SECRET_NAME_PATTERN). */
+export declare const SECRET_NAME: RegExp;
 /** Validates the API base URL: https, or http only to a loopback address (the key is a bearer credential). */
 export declare function resolveApiUrl(flag: string | undefined, env: string | undefined): string;
+export declare const DEFAULT_WAKE_TIMEOUT_MS = 120000;
+/** Wake on use: --wake / --no-wake, else SHARDFLUX_NO_WAKE (1/true/yes/on disables), else on. */
+export declare function resolveWake(flag: boolean | undefined, noWakeEnv: string | undefined): boolean;
+/** The wake/transition budget per call in ms: --wake-timeout, else SHARDFLUX_WAKE_TIMEOUT_MS, else 120000. */
+export declare function resolveWakeTimeout(flag: string | undefined, env: string | undefined): number;
 export type Values = Record<string, string | boolean | string[] | undefined>;
 export type Parsed = {
     kind: 'help';
@@ -49,6 +56,8 @@ export type Parsed = {
         apiUrl: string | undefined;
         json: boolean;
         agentLabel: string | undefined;
+        wake: boolean | undefined;
+        wakeTimeout: string | undefined;
     };
 };
 /**