@shardflux/cli 0.1.0 → 0.2.0

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,8 +56,8 @@ 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]` | 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. |
@@ -63,13 +65,70 @@ every run.
 | `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 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. |
+| `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]` | 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`).
+
+## Secrets
 
-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.
+```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
+```
+
+- 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,6 +141,9 @@ 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, ...}}`.
 
@@ -94,8 +156,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.2.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;
     };
 };
 /**

package/dist/args.js

@@ -10,11 +10,13 @@
  */
 import { parseArgs } from 'node:util';
 import { UsageError } from "./errors.js";
-export const CLI_VERSION = '0.1.0';
+export const CLI_VERSION = '0.2.0';
 export const GLOBAL_OPTIONS = {
     'api-url': { type: 'string', value: '<url>', description: 'API base URL (default $SHARDFLUX_API_URL, else https://api.shardflux.dev).' },
     json: { type: 'boolean', description: 'Print machine-readable JSON on stdout (errors as JSON on stderr).' },
     'agent-label': { type: 'string', value: '<label>', description: 'Attribution label for workspace tool tokens (default $SHARDFLUX_AGENT_LABEL, else "cli").' },
+    wake: { type: 'boolean', description: 'Resume a suspended workspace when exec/files/changes use it (default; --no-wake or SHARDFLUX_NO_WAKE=1 fails with workspace_not_running instead).' },
+    'wake-timeout': { type: 'string', value: '<ms>', description: 'Longest wait in milliseconds for the workspace to wake or finish a transition (default $SHARDFLUX_WAKE_TIMEOUT_MS, else 120000); then exit 5.' },
     help: { type: 'boolean', short: 'h', description: 'Show help.' },
     version: { type: 'boolean', short: 'V', description: 'Print the version.' },
 };
@@ -28,6 +30,39 @@ const WAIT = {
     timeout: { type: 'string', value: '<duration>', description: 'Give up waiting after this long (e.g. 90s, 5m; default 5m). The operation continues server side.' },
 };
 const REF = { name: 'id|key', required: true };
+const SLUG = { name: 'slug', required: true };
+const PAGE = {
+    all: { type: 'boolean', description: 'Fetch every page.' },
+    limit: { type: 'string', value: '<n>', description: 'Page size.' },
+    cursor: { type: 'string', value: '<cursor>', description: 'Continue from a previous page.' },
+};
+/** Options of a version produced by save-as-template or a draft publish (contracts §19.8). */
+const SAVE = {
+    description: { type: 'string', value: '<text>', description: 'Version description (default: the source version’s).' },
+    'default-lifetime': { type: 'string', value: '<persistent|session>', description: 'Default lifetime of workspaces opened from the new version.' },
+    'default-idle-timeout': { type: 'string', value: '<duration>', description: 'Idle timeout of its session workspaces (60s-24h; default: the platform’s 10m).' },
+    acknowledge: { type: 'string', multiple: true, value: '<path>', description: 'Absolute path the credential scan may report without failing the build (repeatable, up to 200).' },
+    'auto-publish': { type: 'boolean', description: 'Publish the version once registered (default; --no-auto-publish leaves it for an owner/admin).' },
+    wait: { type: 'boolean', description: 'Wait until the build is published and registered (or fails).' },
+    timeout: { type: 'string', value: '<duration>', description: 'Give up waiting after this long (default 30m). The build continues server side.' },
+};
+const LIFETIME_FILTER = {
+    lifetime: { type: 'string', value: '<persistent|session|any>', description: 'Lifetime filter (default persistent: sessions are hidden).' },
+    purpose: { type: 'string', value: '<standard|template_draft|template_test|any>', description: 'Purpose filter (default standard: template drafts and test instances are hidden).' },
+};
+const SECRET_REF = { name: 'id|name', required: true };
+const SECRET_SCOPE = {
+    org: { type: 'string', value: '<organization-id>', description: 'Organization-wide secrets of this organization (owners/admins; project API keys get 403). Default: the API key’s project.' },
+};
+const SECRET_VALUE = {
+    'from-file': { type: 'string', value: '<file>', description: 'Read the value from this file. Default: standard input (pipe it in). One trailing newline is removed. Values are never accepted as arguments.' },
+};
+const SECRET_PERMISSIONS = {
+    tool: { type: 'string', multiple: true, value: '<tool>', description: 'Tool that receives the value at session start (repeatable; exec, pty, files, process, git, browser). Default exec and pty.' },
+    'allow-workspace': { type: 'string', multiple: true, value: '<workspace-id>', description: 'Only these workspaces may use it (repeatable). Default: any workspace of the allowed projects.' },
+    'allow-project': { type: 'string', multiple: true, value: '<project-id>', description: 'Organization secrets: projects whose workspaces may use it (repeatable). Default: none until granted.' },
+    'all-projects': { type: 'boolean', description: 'Organization secrets: every project of the organization may use it.' },
+};
 export const COMMANDS = [
     {
         path: ['login'],
@@ -51,11 +86,27 @@ export const COMMANDS = [
         positionals: [{ name: 'key', required: true }],
         options: {
             template: { type: 'string', value: '<slug>', description: 'Template slug (required), e.g. python-node-browser.' },
+            secret: {
+                type: 'string',
+                multiple: true,
+                value: '<NAME>',
+                description: 'Bind this secret name (repeatable): injected as an environment variable into every exec and terminal. Replaces the binding of an existing workspace; omit to leave it unchanged.',
+            },
+            lifetime: {
+                type: 'string',
+                value: '<persistent|session>',
+                description: 'session: the workspace is discarded when the session ends ("shard ws close" or the idle timeout) and the key then opens a new one. Default: the template’s default, else persistent.',
+            },
             ...CAPS,
             wait: { type: 'boolean', description: 'Wait until ready (default; --no-wait returns at once).' },
             timeout: { type: 'string', value: '<duration>', description: 'Give up waiting after this long (default 5m). The start continues server side.' },
         },
-        examples: ['shard workspaces open acme/demo --template python-node-browser', 'shard ws open acme/demo --template python-node-browser --no-wait --json'],
+        examples: [
+            'shard workspaces open acme/demo --template python-node-browser',
+            'shard ws open job-42 --template python-node-browser --lifetime session',
+            'shard ws open acme/demo --template python-node-browser --secret OPENAI_API_KEY --secret DATABASE_URL',
+            'shard ws open acme/demo --template python-node-browser --no-wait --json',
+        ],
     },
     {
         path: ['workspaces', 'list'],
@@ -64,7 +115,8 @@ export const COMMANDS = [
         options: {
             state: { type: 'string', value: '<state>', description: 'Observed state filter (running, suspended, creating, ...).' },
             prefix: { type: 'string', value: '<key-prefix>', description: 'Only keys starting with this prefix.' },
-            'include-deleted': { type: 'boolean', description: 'Include deleted workspaces (tombstones).' },
+            ...LIFETIME_FILTER,
+            'include-deleted': { type: 'boolean', description: 'Include deleted workspaces and ended sessions (tombstones).' },
             all: { type: 'boolean', description: 'Fetch every page.' },
             limit: { type: 'string', value: '<n>', description: 'Page size, 1-200 (default 50).' },
             cursor: { type: 'string', value: '<cursor>', description: 'Continue from a previous page.' },
@@ -98,7 +150,58 @@ export const COMMANDS = [
         positionals: [REF],
         options: { yes: { type: 'boolean', description: 'Required: confirm the deletion.' }, ...WAIT },
     },
+    {
+        path: ['workspaces', 'close'],
+        summary: 'End a session workspace now (it is deleted; the key then opens a new workspace)',
+        description: 'Sessions only: a persistent workspace is refused with conflict (not_session); suspend or delete it instead. Repeating returns the same delete operation.',
+        positionals: [REF],
+        options: { ...WAIT },
+    },
+    {
+        path: ['workspaces', 'reset'],
+        summary: 'Wipe every change in a layered workspace and restart it on its template',
+        description: 'Keeps the key, id, template version, caps, secret bindings and volume attachments; processes are gone. A suspended workspace stays suspended and boots blank on its next resume. The previous state stays restorable for 7 days (the operation result names the recovery checkpoint).',
+        positionals: [REF],
+        options: { yes: { type: 'boolean', description: 'Required: confirm that every change is wiped.' }, ...WAIT },
+    },
+    {
+        path: ['workspaces', 'save-as-template'],
+        summary: 'Save a layered workspace as the next version of an organization template',
+        description: 'Everything in the workspace becomes template content (minus the sf-scrub.v1 list: machine identity, histories, credentials, .env files, caches), stored as one new layer on the workspace’s template. A running workspace is captured briefly and keeps running.',
+        positionals: [REF],
+        options: {
+            template: { type: 'string', value: '<slug>', description: 'Organization template to save into (required; created when absent).' },
+            'display-name': { type: 'string', value: '<name>', description: 'Template name when this save creates the template.' },
+            checkpoint: { type: 'string', value: '<checkpoint-id>', description: 'Save this committed checkpoint of the workspace instead of its current state.' },
+            ...SAVE,
+        },
+        examples: ['shard ws save-as-template acme/demo --template acme-dev --description "node 22 + repo deps" --wait'],
+    },
+    {
+        path: ['workspaces', 'changes'],
+        summary: 'List what a layered workspace changed against its template',
+        description: 'Served by the cell gateway from the running workspace (needs the files tool). added, modified, metadata (with --hash), deleted, replaced (opaque directory).',
+        positionals: [REF],
+        options: {
+            path: { type: 'string', value: '<prefix>', description: 'Only entries at or below this absolute path (default /).' },
+            hash: { type: 'boolean', description: 'Hash regular files up to 16 MiB (reports metadata-only changes).' },
+            summary: { type: 'boolean', description: 'Also print totals over everything under --path.' },
+            ...PAGE,
+            limit: { type: 'string', value: '<n>', description: 'Page size, 1-1000 (default 1000).' },
+        },
+    },
     { path: ['workspaces', 'sessions'], summary: 'List the attributed agent sessions (tool-token principals and labels) of a workspace', positionals: [REF], options: {} },
+    {
+        path: ['workspaces', 'secrets'],
+        summary: 'Show (or replace) the secret names bound to a workspace',
+        description: 'Bound secrets are injected as environment variables into every exec and terminal of the workspace. Status: available, not_allowed (starts are refused until the secret’s permissions allow this workspace) or deleted. Values are never shown.',
+        positionals: [REF],
+        options: {
+            set: { type: 'string', multiple: true, value: '<NAME>', description: 'Replace the binding with these names (repeatable).' },
+            clear: { type: 'boolean', description: 'Remove every bound name.' },
+        },
+        examples: ['shard ws secrets acme/demo', 'shard ws secrets acme/demo --set OPENAI_API_KEY --set DATABASE_URL', 'shard ws secrets acme/demo --clear'],
+    },
     {
         path: ['files', 'read'],
         summary: 'Print (or save) a file from a workspace',
@@ -132,6 +235,160 @@ export const COMMANDS = [
         },
     },
     { path: ['operations', 'get'], summary: 'Show one operation', positionals: [{ name: 'operation-id', required: true }], options: {} },
+    {
+        path: ['secrets', 'create'],
+        summary: 'Create a secret; the value is read from standard input or --from-file, never from arguments',
+        description: 'Project secret of the API key’s project by default, or an organization-wide secret with --org. The value (UTF-8 text, up to 64 KiB) is encrypted and never shown again. Bind it to workspaces with "shard ws open --secret NAME" or "shard ws secrets <ws> --set NAME".',
+        positionals: [{ name: 'name', required: true }],
+        options: { ...SECRET_SCOPE, ...SECRET_VALUE, description: { type: 'string', value: '<text>', description: 'Description (up to 500 characters).' }, ...SECRET_PERMISSIONS },
+        examples: ['printf %s "$OPENAI_API_KEY" | shard secrets create OPENAI_API_KEY', 'shard secrets create DATABASE_URL --from-file ./database-url.txt --description "Staging database"'],
+    },
+    {
+        path: ['secrets', 'list'],
+        summary: 'List secrets (metadata only; never values)',
+        positionals: [],
+        options: {
+            ...SECRET_SCOPE,
+            'include-deleted': { type: 'boolean', description: 'Include deleted secrets.' },
+            all: { type: 'boolean', description: 'Fetch every page.' },
+            limit: { type: 'string', value: '<n>', description: 'Page size, 1-200 (default 50).' },
+            cursor: { type: 'string', value: '<cursor>', description: 'Continue from a previous page.' },
+        },
+    },
+    { path: ['secrets', 'get'], summary: 'Show one secret’s metadata (never the value)', positionals: [SECRET_REF], options: { ...SECRET_SCOPE } },
+    {
+        path: ['secrets', 'update'],
+        summary: 'Change a secret’s description or usage permissions (applies from the next session start)',
+        positionals: [SECRET_REF],
+        options: {
+            ...SECRET_SCOPE,
+            description: { type: 'string', value: '<text>', description: 'New description.' },
+            ...SECRET_PERMISSIONS,
+            'any-workspace': { type: 'boolean', description: 'Remove the workspace restriction (any workspace of the allowed projects).' },
+            'clear-projects': { type: 'boolean', description: 'Organization secrets: no project may use it (until granted again).' },
+        },
+    },
+    {
+        path: ['secrets', 'rotate'],
+        summary: 'Store a new value as the next version (standard input or --from-file); older values are erased',
+        positionals: [SECRET_REF],
+        options: { ...SECRET_SCOPE, ...SECRET_VALUE },
+        examples: ['printf %s "$NEW_TOKEN" | shard secrets rotate API_TOKEN'],
+    },
+    {
+        path: ['secrets', 'versions'],
+        summary: 'List a secret’s versions, newest first (metadata only)',
+        positionals: [SECRET_REF],
+        options: { ...SECRET_SCOPE, limit: { type: 'string', value: '<n>', description: 'Page size, 1-200 (default 50).' } },
+    },
+    {
+        path: ['secrets', 'delete'],
+        summary: 'Delete a secret: its values are erased and it is removed from every workspace binding',
+        positionals: [SECRET_REF],
+        options: { ...SECRET_SCOPE, yes: { type: 'boolean', description: 'Required: confirm the deletion.' } },
+    },
+    {
+        path: ['secrets', 'access-log'],
+        summary: 'Show which sessions resolved a secret (owners/admins; project API keys get 403)',
+        positionals: [SECRET_REF],
+        options: {
+            ...SECRET_SCOPE,
+            outcome: { type: 'string', value: '<outcome>', description: 'granted, denied or failed.' },
+            workspace: { type: 'string', value: '<workspace-id>', description: 'Only this workspace.' },
+            limit: { type: 'string', value: '<n>', description: 'Page size, 1-200 (default 50).' },
+        },
+    },
+    {
+        path: ['templates', 'list'],
+        summary: 'List the templates this project can open (platform and organization)',
+        positionals: [],
+        options: {
+            owner: { type: 'string', value: '<platform|organization>', description: 'Only platform or only organization templates.' },
+            'include-archived': { type: 'boolean', description: 'Include archived templates.' },
+            ...PAGE,
+            limit: { type: 'string', value: '<n>', description: 'Page size, 1-200 (default 50).' },
+        },
+    },
+    {
+        path: ['templates', 'files'],
+        summary: 'List one directory of a template version’s file tree (or show one entry with --stat)',
+        description: 'Needs a version with a file list (versions from before file lists answer conflict file_list_unavailable). File contents are not served: open a draft or test instance for that.',
+        positionals: [SLUG, { name: 'version', required: true }, { name: 'path' }],
+        options: {
+            stat: { type: 'boolean', description: 'Show the entry at <path> itself instead of listing it.' },
+            owner: { type: 'string', value: '<platform|organization>', description: 'Pick the platform template even when an organization template shadows its slug.' },
+            ...PAGE,
+            limit: { type: 'string', value: '<n>', description: 'Page size, 1-1000 (default 200).' },
+        },
+        examples: ['shard templates files python-node-browser 5 /usr/local/bin', 'shard templates files acme-dev 3 /etc/hostname --stat'],
+    },
+    {
+        path: ['templates', 'diff'],
+        summary: 'Diff two versions of a template (added, removed, changed, type_changed, metadata)',
+        positionals: [SLUG],
+        options: {
+            from: { type: 'string', value: '<version|base>', description: 'Older version, or "base" (the --to version’s build base). Required.' },
+            to: { type: 'string', value: '<version>', description: 'Newer version (required).' },
+            prefix: { type: 'string', value: '<path>', description: 'Only paths starting with this absolute prefix.' },
+            change: { type: 'string', value: '<kind>', description: 'Only added, removed, changed, type_changed or metadata.' },
+            owner: { type: 'string', value: '<platform|organization>', description: 'Pick the platform template even when an organization template shadows its slug.' },
+            ...PAGE,
+            limit: { type: 'string', value: '<n>', description: 'Page size, 1-1000 (default 200).' },
+        },
+        examples: ['shard templates diff acme-dev --from 2 --to 3', 'shard templates diff acme-dev --from base --to 3 --prefix /home/user'],
+    },
+    {
+        path: ['templates', 'draft', 'open'],
+        summary: 'Open the draft of an organization template (a layered workspace to edit live)',
+        description: 'One live draft per template. Edit it with "shard ws exec|files ... <draft key>", capture states, open test instances, then publish it as the next version.',
+        positionals: [SLUG],
+        options: {
+            base: { type: 'string', value: '<slug@version>', description: 'Version to start from (default: the template’s latest published version; required for a new template).' },
+            ...CAPS,
+            wait: { type: 'boolean', description: 'Wait until ready (default; --no-wait returns at once).' },
+            timeout: { type: 'string', value: '<duration>', description: 'Give up waiting after this long (default 5m).' },
+        },
+        examples: ['shard templates draft open acme-dev --base python-node-browser@5'],
+    },
+    { path: ['templates', 'draft', 'status'], summary: 'Show a template’s draft: workspace, base version, states and live test instances', positionals: [SLUG], options: {} },
+    {
+        path: ['templates', 'draft', 'state'],
+        summary: 'Capture a state of the running draft (or list its states with --list)',
+        positionals: [SLUG],
+        options: {
+            label: { type: 'string', value: '<text>', description: 'Label of the captured state.' },
+            list: { type: 'boolean', description: 'List the draft’s states instead of capturing one.' },
+            ...WAIT,
+        },
+    },
+    {
+        path: ['templates', 'draft', 'test'],
+        summary: 'Open a test instance of a draft state (a disposable session workspace), or list them with --list',
+        description: 'Its writes never reach the draft. It ends with "shard ws close <key>", when idle, or when the draft is discarded.',
+        positionals: [SLUG],
+        options: {
+            state: { type: 'string', value: '<state-id>', description: 'Draft state to test (default: a fresh capture of the running draft).' },
+            'instance-key': { type: 'string', value: '<key>', description: 'Workspace key of the test instance (default sf:test:<slug>:<random>).' },
+            list: { type: 'boolean', description: 'List the draft’s test instances instead of opening one.' },
+            'include-ended': { type: 'boolean', description: 'With --list: include ended test instances.' },
+            ...CAPS,
+            wait: { type: 'boolean', description: 'Wait until ready (default; --no-wait returns at once).' },
+            timeout: { type: 'string', value: '<duration>', description: 'Give up waiting after this long (default 5m).' },
+        },
+    },
+    {
+        path: ['templates', 'draft', 'publish'],
+        summary: 'Publish the draft as the template’s next version',
+        description: 'Refused (conflict draft_stale) when the template got a version from elsewhere since the draft was opened. The draft stays open afterwards.',
+        positionals: [SLUG],
+        options: { state: { type: 'string', value: '<state-id>', description: 'State to publish (default: the draft’s current state).' }, ...SAVE },
+    },
+    {
+        path: ['templates', 'draft', 'discard'],
+        summary: 'Discard the draft (it is deleted and its live test instances end)',
+        positionals: [SLUG],
+        options: { yes: { type: 'boolean', description: 'Required: confirm the discard.' }, ...WAIT },
+    },
     {
         path: ['operations', 'wait'],
         summary: 'Wait for an operation to finish (exit 0 succeeded, 6 failed/canceled, 5 timeout)',
@@ -143,8 +400,10 @@ const GROUPS = {
     workspaces: 'Open, inspect and manage workspaces',
     files: 'Read, write and list files in a workspace',
     operations: 'Inspect and wait for lifecycle operations',
+    secrets: 'Manage secrets (values are write-only) and bind them to workspaces',
+    templates: 'Browse templates (file tree, diff) and develop organization templates in a draft',
 };
-const ALIASES = { ws: 'workspaces', workspace: 'workspaces', ops: 'operations', operation: 'operations', file: 'files' };
+const ALIASES = { ws: 'workspaces', workspace: 'workspaces', ops: 'operations', operation: 'operations', file: 'files', secret: 'secrets', template: 'templates' };
 /** Canonical command words: aliases resolved, `workspaces files|operations` folded to the top-level group. */
 export function normalizeWords(words) {
     const w = words.map((x) => ALIASES[x] ?? x);
@@ -202,6 +461,8 @@ export function parseEnvPairs(pairs) {
     return out;
 }
 export const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/** Secret names (environment-variable safe; the API's SECRET_NAME_PATTERN). */
+export const SECRET_NAME = /^[A-Z_][A-Z0-9_]{0,127}$/;
 const LOOPBACK = new Set(['localhost', '127.0.0.1', '[::1]', '::1']);
 /** Validates the API base URL: https, or http only to a loopback address (the key is a bearer credential). */
 export function resolveApiUrl(flag, env) {
@@ -220,8 +481,37 @@ export function resolveApiUrl(flag, env) {
         throw new UsageError('API URL must not contain credentials, a query or a fragment');
     return u.toString().replace(/\/+$/, '');
 }
-const FORBIDDEN_KEY_FLAG = /^--?(api-?key|apikey|key|token|secret)(=.*)?$/i;
-const GLOBAL_VALUE_FLAGS = new Set(['--api-url', '--agent-label']);
+export const DEFAULT_WAKE_TIMEOUT_MS = 120_000;
+const MAX_WAKE_TIMEOUT_MS = 7 * 24 * 3600 * 1000;
+const TRUTHY = new Set(['1', 'true', 'yes', 'on']);
+const FALSY = new Set(['', '0', 'false', 'no', 'off']);
+/** Wake on use: --wake / --no-wake, else SHARDFLUX_NO_WAKE (1/true/yes/on disables), else on. */
+export function resolveWake(flag, noWakeEnv) {
+    if (flag !== undefined)
+        return flag;
+    const v = (noWakeEnv ?? '').trim().toLowerCase();
+    if (TRUTHY.has(v))
+        return false;
+    if (FALSY.has(v))
+        return true;
+    throw new UsageError(`SHARDFLUX_NO_WAKE must be 1 (or true) to turn wake on use off, or 0/empty (got "${noWakeEnv}")`);
+}
+/** The wake/transition budget per call in ms: --wake-timeout, else SHARDFLUX_WAKE_TIMEOUT_MS, else 120000. */
+export function resolveWakeTimeout(flag, env) {
+    if (flag !== undefined)
+        return parsePositiveInt(flag, 'wake-timeout', MAX_WAKE_TIMEOUT_MS);
+    const v = env?.trim();
+    if (!v)
+        return DEFAULT_WAKE_TIMEOUT_MS;
+    if (!/^\d+$/.test(v) || Number(v) < 1 || Number(v) > MAX_WAKE_TIMEOUT_MS) {
+        throw new UsageError(`SHARDFLUX_WAKE_TIMEOUT_MS must be an integer number of milliseconds between 1 and ${MAX_WAKE_TIMEOUT_MS} (got "${env}")`);
+    }
+    return Number(v);
+}
+const FORBIDDEN_KEY_FLAG = /^--?(api-?key|apikey|key|token|secret|value|secret-value|password)(=.*)?$/i;
+/** `--secret NAME` binds a secret by name on `workspaces open`; anything else shaped like --secret is refused. */
+const SECRET_NAME_FLAG = /^--secret(?:=(.*))?$/;
+const GLOBAL_VALUE_FLAGS = new Set(['--api-url', '--agent-label', '--wake-timeout']);
 function toParseArgsOptions(opts) {
     const out = {};
     for (const [name, o] of Object.entries(opts))
@@ -235,10 +525,30 @@ function toParseArgsOptions(opts) {
 export function parseCommandLine(argv) {
     const terminator = argv.indexOf('--');
     const head = terminator < 0 ? argv : argv.slice(0, terminator);
-    for (const a of head) {
-        if (FORBIDDEN_KEY_FLAG.test(a)) {
-            throw new UsageError('shard reads the API key only from the SHARDFLUX_API_KEY environment variable; never pass it on the command line (shell history and process listings would expose it)');
+    const leading = [];
+    for (let i = 0; i < head.length && leading.length < 2; i += 1) {
+        const a = head[i];
+        if (!a.startsWith('-'))
+            leading.push(a);
+        else if (GLOBAL_VALUE_FLAGS.has(a))
+            i += 1;
+    }
+    const opensWorkspace = key(normalizeWords(leading)) === 'workspaces open';
+    for (let i = 0; i < head.length; i += 1) {
+        const a = head[i];
+        if (!FORBIDDEN_KEY_FLAG.test(a))
+            continue;
+        const named = SECRET_NAME_FLAG.exec(a);
+        if (named && opensWorkspace) {
+            const name = named[1] ?? head[i + 1];
+            if (name !== undefined && SECRET_NAME.test(name))
+                continue;
+            throw new UsageError('--secret takes a secret NAME (^[A-Z_][A-Z0-9_]*$) to bind, never a value; create the secret with "shard secrets create NAME" (value on standard input)');
+        }
+        if (/^--?(value|secret-value|password)(=.*)?$/i.test(a)) {
+            throw new UsageError('shard never accepts secret values on the command line (shell history and process listings would expose them); pipe the value on standard input or use --from-file');
         }
+        throw new UsageError('shard reads the API key only from the SHARDFLUX_API_KEY environment variable; never pass it on the command line (shell history and process listings would expose it)');
     }
     // Pick the command words (the leading non-option words that form a known command path).
     const words = [];
@@ -323,6 +633,8 @@ export function parseCommandLine(argv) {
             apiUrl: typeof values['api-url'] === 'string' ? values['api-url'] : undefined,
             json: values.json === true,
             agentLabel: typeof values['agent-label'] === 'string' ? values['agent-label'] : undefined,
+            wake: typeof values.wake === 'boolean' ? values.wake : undefined,
+            wakeTimeout: typeof values['wake-timeout'] === 'string' ? values['wake-timeout'] : undefined,
         },
     };
 }
@@ -380,9 +692,11 @@ export function topHelp() {
         ...optionLines(GLOBAL_OPTIONS),
         '',
         'Environment:',
-        '  SHARDFLUX_API_KEY      project API key (sfk_...), required; never pass it as an argument',
-        '  SHARDFLUX_API_URL      API base URL (default https://api.shardflux.dev)',
-        '  SHARDFLUX_AGENT_LABEL  attribution label for tool tokens (default cli)',
+        '  SHARDFLUX_API_KEY          project API key (sfk_...), required; never pass it as an argument',
+        '  SHARDFLUX_API_URL          API base URL (default https://api.shardflux.dev)',
+        '  SHARDFLUX_AGENT_LABEL      attribution label for tool tokens (default cli)',
+        '  SHARDFLUX_NO_WAKE          1: do not resume a suspended workspace on use (same as --no-wake)',
+        '  SHARDFLUX_WAKE_TIMEOUT_MS  longest wait in ms for a workspace to wake or finish a transition (default 120000; --wake-timeout overrides)',
         '',
         'Exit codes:',
         ...EXIT_CODE_HELP,

package/dist/commands.d.ts

@@ -16,11 +16,19 @@ export interface Ctx {
     json: boolean;
     apiUrl: string;
     agentLabel: string;
+    /** Wake a suspended workspace on use (--no-wake / SHARDFLUX_NO_WAKE=1 turn it off). */
+    wake: boolean;
+    /** Bound on lifecycle waits per cell call, wakes included (--wake-timeout / SHARDFLUX_WAKE_TIMEOUT_MS). */
+    wakeTimeoutMs: number;
     signal: AbortSignal;
     cloud(): Shardflux;
 }
 export type Handler = (ctx: Ctx, values: Values, positionals: string[]) => Promise<number>;
-/** `<id|key>`: a UUID is tried as an id first; anything else (or an unknown UUID) as an exact workspace key. */
+/**
+ * `<id|key>`: a UUID is tried as an id first; anything else (or an unknown UUID) as an exact workspace key, across every
+ * lifetime and purpose (sessions, drafts and test instances are hidden from the default list), preferring the live
+ * workspace over tombstones of ended sessions that had the same key (contracts §19.11).
+ */
 export declare function resolveWorkspace(ctx: Ctx, ref: string): Promise<Workspace>;
 /** The exit code `shard exec` returns for a finished command. */
 export declare function execExitCode(r: Pick<RunResult, 'exitCode' | 'termSignal' | 'timedOut'>): number;