@shardflux/cli 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -3,7 +3,53 @@
 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)
+## 0.4.0 (not yet published; npm `latest` is 0.3.1)
+
+Needs `@shardflux/sdk` 0.7.0 or later. New dependency: `yaml` (template.yaml).
+
+### Template editor (contracts §24)
+
+- `shard templates build <file> [--slug] [--display-name] [--description] [--publish] [--acknowledge PATH]... [--wait]
+  [--timeout] [--timing]`: builds a template from template.yaml. Local `from` files and folders are uploaded (folders
+  as the reproducible tar the SDKs pack; bytes the organization has are not sent again), then the recipe v2 build is
+  created. Progress on stderr; `--wait` follows the build (exit 6 failed or canceled, 5 timeout); `--timing` prints
+  packing, uploads, the request, the wait and the build's queued and run time (a `timing` field with `--json`). The
+  slug defaults to the directory holding the file. The version stays unpublished unless `--publish`.
+- `shard templates init --base <slug[@version]> [--out] [--force]`: a starter template.yaml.
+- `shard templates export <slug>@<version> [--out]`: the template.yaml a version was built from (exit 3 for a version
+  without a recipe).
+- `shard templates get <slug>`: versions, what open resolves to, the open version's settings.
+- `shard templates test <slug>@<version> [--input NAME=value]...`: a test instance of a version, published or not.
+- `shard templates builds list|get|log|cancel`.
+- `shard templates languages --base <slug>@<version>` and `shard templates packages search <apt|pip|npm> <query>`.
+- `shard workspaces open --input NAME=value` (repeatable) and `--input-file` (NAME=value lines or a JSON object);
+  `shard workspaces inputs <ws>`.
+- `shard workspaces get` (and the ready output of `open`) shows the startup of the template's start commands and
+  services; a failed step shows its exit code, reason and output tail.
+- A template file `shard` cannot read or pack is a usage error (exit 2); a storage refusal of an upload is
+  `upload_failed` (exit 1); a build wait that runs out is `timeout` (exit 5).
+- `buildText` names a recipe v2 build's recipe sha256, its build network and denied hosts, and points at
+  `shard templates builds get`.
+
+## 0.3.1 (2026-09-28)
+
+Needs `@shardflux/sdk` 0.6.2 or later.
+
+The API no longer lets a start (open, resume, fork) wait in `capacity_pending` forever: one that no host could admit
+15 minutes after it began fails with `capacity_unavailable` (retryable; nothing was started, a suspended workspace
+stays suspended).
+
+- A failed operation's error has `retryable` (the operation error's own flag): `retryable=true|false` in the error line,
+  `"retryable"` in the `--json` error document, next to `details.error_code`. `details.reason` carries the operation
+  error's reason (for `capacity_unavailable`, why no host fit, e.g. `no_ready_hosts`), printed after the message.
+- A retryable failure gets a hint to retry later. Exit codes are unchanged (6 for any failed operation); `shard` does
+  not retry.
+- A `--timeout` that ends while the start waits for capacity names the time it gives up (the SDK's message).
+- Help and README: `--timeout` and exit codes 5 and 6 describe the 15-minute limit.
+- `shard workspaces get` names the origin of a template version test instance (`template <id> version <n>`, contracts
+  §24.6) instead of reading it as a draft state.
+
+## 0.3.0 (2026-09-28)
 
 Needs `@shardflux/sdk` 0.6.0 or later.
 

package/README.md

@@ -56,9 +56,10 @@ 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> [--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 open <key> --template <slug> [--secret NAME]... [--input NAME=value]... [--input-file F] [--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 (the template's start commands and services included) unless you pass `--no-wait`. `--secret` binds secret names (replacing the binding of an existing workspace). `--input` (0.4.0+) passes the template's text inputs (replacing those of an existing workspace); `--input-file` reads `NAME=value` lines or a JSON object. `--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 get <id\|key>` | One workspace (deleted ones included), with the startup of its template's start commands and services (0.4.0+): a failed step shows its exit code, reason and output tail. |
+| `workspaces inputs <id\|key>` | The workspace's text inputs (0.4.0+). |
 | `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. |
@@ -79,6 +80,14 @@ every run.
 | `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 get <slug> [--owner O] [--include-archived]` | One template (0.4.0+): its versions, what open resolves to, and the open version's settings (env, inputs, start commands, services, defaults). |
+| `templates init --base <slug[@version]> [--out F] [--force]` | Write a starter `template.yaml` on a base (0.4.0+). |
+| `templates build <file> [--slug S] [--display-name N] [--description T] [--publish] [--acknowledge PATH]... [--wait] [--timeout 30m] [--timing]` | Build a template from `template.yaml` (0.4.0+): local files and folders are uploaded, then the build is created. See [Build a template](#build-a-template-from-templateyaml). |
+| `templates export <slug>@<version> [--out F] [--force]` | The `template.yaml` a version was built from, ready to build again (0.4.0+). |
+| `templates test <slug>@<version> [--input NAME=value]... [--instance-key K] [caps] [--no-wait] [--timing]` | A test instance of a version, published or not: a session workspace that runs its start commands and services (0.4.0+). |
+| `templates builds list [--template S] [--state S] [--all]`, `templates builds get\|log\|cancel <build-id>` | The organization's template builds, one build, its full log (`--out F`), or cancel it (0.4.0+). |
+| `templates languages --base <slug>@<version>` | The languages and versions a base offers `build.languages` (0.4.0+). |
+| `templates packages search <apt\|pip\|npm> <query> [--base slug@version] [--limit N]` | Package names for `build.packages` (0.4.0+). apt searches the base's index and needs `--base`. |
 | `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`. |
@@ -94,6 +103,51 @@ is a UUID. Otherwise, or if no workspace has that id, it is matched as an exact
 and purpose, so sessions, drafts and test instances resolve too. The live workspace wins over tombstones that ended
 sessions left with the same key.
 
+## Build a template from template.yaml
+
+(0.4.0+) A template is a recipe v2: a base, what the build adds (languages, packages, files, build steps) and the
+settings a workspace gets when it opens (environment, inputs, start commands, services). `template.yaml` is that
+document; a file entry may name a local `from` path (relative to the file), which `shard` uploads.
+
+```sh
+shard templates init --base ubuntu-24.04            # writes template.yaml on the base's current version
+$EDITOR template.yaml
+shard templates languages --base ubuntu-24.04@1    # what build.languages offers there
+shard templates packages search apt ffmpeg --base ubuntu-24.04@1
+shard templates build template.yaml --slug acme-dev --wait --timing
+shard templates test acme-dev@1 --input PROJECT_NAME=demo
+shard templates build template.yaml --slug acme-dev --publish --wait
+shard ws open acme/main --template acme-dev --input PROJECT_NAME=acme
+```
+
+```yaml
+base: ubuntu-24.04@1
+build:
+  languages: [{ id: python }]
+  packages: { apt: [jq], pip: { packages: [pandas==2.3.2] } }
+  files:
+    - { from: ./app, to: /home/user/app, owner: user }              # a folder: uploaded as a tar
+    - { from: ./settings.toml, to: /home/user/.config/acme/settings.toml, owner: user, mode: "0600" }
+  steps:
+    - { name: install, run: pip install -e /home/user/app, user: user }
+settings:
+  env: { APP_ENV: development }
+  inputs: { PROJECT_NAME: { kind: text, required: true } }
+  start: [{ name: seed, when: create, run: python -m app.seed, user: user, cwd: /home/user/app }]
+```
+
+- Folders are packed as a reproducible tar (the same bytes as the SDKs pack), so the same folder gives the same
+  upload and the same `recipe_sha256`. Bytes the organization already has are not sent again. Progress lines go to
+  stderr (`packed`, `uploaded` or `already uploaded`, then the build's states with `--wait`).
+- The version stays unpublished unless you pass `--publish`: try it with `shard templates test <slug>@<version>`.
+  Without `--slug` the template slug is the name of the directory holding the file.
+- `--wait` follows the build until it is registered or fails (exit 6 when it failed or was canceled, 5 when
+  `--timeout` ran out; the build continues). A build whose network refused a host lists it under `denied hosts`: add
+  it to `build.network.extra_hosts` and build again.
+- `--timing` prints where the time went: packing, uploads, the request, the wait, and the build's queued and run time.
+- A file `shard` cannot read or pack (a symlink that leaves the folder, a device) is refused before any request (exit
+  2). The API's refusals (`upload_missing`, `language_unavailable`, `invalid_settings`, ...) exit 2 with the reason.
+
 ## Suspended workspaces
 
 `workspaces exec`, `files read|write|ls` and `workspaces changes` wake a suspended workspace: they
@@ -106,6 +160,21 @@ never runs twice, because the workspace refused it before doing anything.
   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.
+
+## Starts that wait for capacity
+
+An open, resume or fork that no host can admit yet waits in `capacity_pending` for at most 15
+minutes. If `--timeout` ends first, the timeout error names the time it gives up. A start still
+pending then fails with `capacity_unavailable`: nothing was started, and a suspended
+workspace stays suspended. `shard` exits 6 as for any failed operation, and the error says
+`retryable=true` (with `--json`, `"retryable": true`) with a hint to retry later:
+
+```text
+error: Operation 01a0df37-b3a9-7a14-a3e7-11395c349c39 (open) failed: capacity_unavailable (no_ready_hosts) [code=operation_failed operation_id=01a0df37-b3a9-7a14-a3e7-11395c349c39 retryable=true]
+hint: no host could admit it before its deadline; nothing was started. Retry later.
+```
+
+`shard` does not retry it for you. A definitive failure has `retryable=false`.
 - `--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`).
 
@@ -139,7 +208,8 @@ Here the time went to waiting for a host with capacity; the network and the VM s
 
 Which call is timed:
 
-- `workspaces open` and `templates draft open|test`: the open, including the wait unless `--no-wait`.
+- `workspaces open`, `templates test` and `templates draft open|test`: the open, including the wait unless `--no-wait`.
+- `templates build` (0.4.0+): packing, uploads, the request and the wait, then the build's own queued and run time.
 - `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.
@@ -179,7 +249,7 @@ printf %s "$NEW_KEY" | shard secrets rotate OPENAI_API_KEY
 
 - **Human (default):** aligned tables and key/value blocks on stdout. Errors go to stderr as
   `error: <message> (<reason>) [code=... status=... request_id=... operation_id=...]`, with a
-  hint when there is one.
+  hint when there is one. A failed operation adds `retryable=true|false` (0.3.1+).
 - **`--json`:** stdout carries the API's own objects:
   - `workspaces open`/`get` print the workspace view; `list` prints `{data, next_cursor}`.
   - Lifecycle commands print the operation; `fork` prints `{operation, workspace}`.
@@ -190,7 +260,9 @@ printf %s "$NEW_KEY" | shard secrets rotate OPENAI_API_KEY
     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, ...}}`.
+  Errors go to stderr as `{"error": {code, message, status, request_id, ...}}`. A failed operation is
+  `{"error": {"code": "operation_failed", "message", "operation_id", "retryable", "details": {"error_code",
+  "reason"}, "operation"}}`; `retryable` (0.3.1+) is the operation error's own flag.
 - **`--timing`:** the timing goes to stderr after the output. With `--json` it is a `timing` field instead
   (see "Timing").
 
@@ -203,8 +275,8 @@ printf %s "$NEW_KEY" | shard secrets rotate OPENAI_API_KEY
 | 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 (`--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) |
+| 5 | timeout: waiting gave up (`--timeout`, or `--wake-timeout` while waking a workspace); the operation continues server side (`shard operations wait <id>`), a start waiting for capacity for at most 15 minutes |
+| 6 | the awaited operation ended `failed` or `canceled` (also a resume or open that failed while waking a workspace). `retryable=true` in the error means it may succeed later (`capacity_unavailable`) |
 | 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.3.0";
+export declare const CLI_VERSION = "0.4.0";
 export interface OptionSpec {
     type: 'string' | 'boolean';
     short?: string;

package/dist/args.js

@@ -10,7 +10,7 @@
  */
 import { parseArgs } from 'node:util';
 import { UsageError } from "./errors.js";
-export const CLI_VERSION = '0.3.0';
+export const CLI_VERSION = '0.4.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).' },
@@ -38,7 +38,7 @@ const WAKE_TIMING = {
 };
 const WAIT = {
     wait: { type: 'boolean', description: 'Wait until the operation finishes.' },
-    timeout: { type: 'string', value: '<duration>', description: 'Give up waiting after this long (e.g. 90s, 5m; default 5m). The operation continues server side.' },
+    timeout: { type: 'string', value: '<duration>', description: 'Give up waiting after this long (e.g. 90s, 5m; default 5m). The operation continues server side (a start waiting for capacity until its deadline, 15 minutes after it began; then it fails with capacity_unavailable).' },
     ...TIMING,
 };
 const REF = { name: 'id|key', required: true };
@@ -58,6 +58,17 @@ const SAVE = {
     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.' },
 };
+/** Open-time text inputs of a template version (0.4.0; contracts §24.3). */
+const INPUTS = {
+    input: {
+        type: 'string',
+        multiple: true,
+        value: '<NAME=value>',
+        description: 'Text input of the template version (repeatable): in the environment of every exec, terminal, start command and service. Replaces the inputs of an existing workspace; omit to leave them unchanged. Not for credentials: those are secret inputs (stored secrets).',
+    },
+    'input-file': { type: 'string', value: '<file>', description: 'Read text inputs from a file: NAME=value lines (# comments), or a JSON object. --input wins for a name in both.' },
+};
+const BUILD_ID = { name: 'build-id', required: true };
 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).' },
@@ -109,14 +120,16 @@ export const COMMANDS = [
                 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.',
             },
+            ...INPUTS,
             ...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.' },
+            wait: { type: 'boolean', description: 'Wait until ready (default; --no-wait returns at once). Ready includes the template’s start commands and services.' },
+            timeout: { type: 'string', value: '<duration>', description: 'Give up waiting after this long (default 5m). The start continues server side; one waiting for capacity gives up 15 minutes after it began (capacity_unavailable, retryable).' },
             ...TIMING,
         },
         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 acme-notebook --input PROJECT_NAME=demo --input LOG_LEVEL=debug',
             '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',
             'shard ws open acme/demo --template python-node-browser --timing',
@@ -136,7 +149,8 @@ export const COMMANDS = [
             cursor: { type: 'string', value: '<cursor>', description: 'Continue from a previous page.' },
         },
     },
-    { path: ['workspaces', 'get'], summary: 'Show one workspace', positionals: [REF], options: {} },
+    { path: ['workspaces', 'get'], summary: 'Show one workspace (state, template, startup)', positionals: [REF], options: {} },
+    { path: ['workspaces', 'inputs'], summary: 'Show the text inputs of a workspace (secret inputs are bound secrets: shard ws secrets)', positionals: [REF], options: {} },
     {
         path: ['workspaces', 'exec'],
         summary: 'Run a command in a workspace; streams its output and exits with its exit code',
@@ -326,6 +340,109 @@ export const COMMANDS = [
             limit: { type: 'string', value: '<n>', description: 'Page size, 1-200 (default 50).' },
         },
     },
+    {
+        path: ['templates', 'get'],
+        summary: 'Show a template: its versions, what open resolves to, and the settings of its open version',
+        positionals: [SLUG],
+        options: {
+            owner: { type: 'string', value: '<platform|organization>', description: 'Pick the platform template even when an organization template shadows its slug.' },
+            'include-archived': { type: 'boolean', description: 'Include archived versions.' },
+        },
+    },
+    {
+        path: ['templates', 'init'],
+        summary: 'Write a template.yaml that starts from a base template',
+        description: 'The file is the recipe v2 document (contracts §24.1): languages, packages, files (local "from" paths are uploaded by "shard templates build"), build steps, and the settings a workspace gets when it opens (env, inputs, start commands, services, defaults). Edit it, then build it.',
+        positionals: [],
+        options: {
+            base: { type: 'string', value: '<slug[@version]>', description: 'Base template (required), e.g. ubuntu-24.04; without @version, the version open resolves to now.' },
+            out: { type: 'string', value: '<file>', description: 'Where to write it (default template.yaml).' },
+            force: { type: 'boolean', description: 'Overwrite an existing file.' },
+        },
+        examples: ['shard templates init --base ubuntu-24.04', 'shard templates init --base python-node-browser@7 --out acme/template.yaml'],
+    },
+    {
+        path: ['templates', 'build'],
+        summary: 'Build a template from template.yaml: upload its local files and folders, then build it',
+        description: 'Folders named by "from" are packed as a reproducible tar and uploaded with files unless the organization already has the same bytes. The version stays unpublished (test it with "shard templates test") unless --publish. Progress goes to stderr.',
+        positionals: [{ name: 'file', required: true }],
+        options: {
+            slug: { type: 'string', value: '<slug>', description: 'Organization template to build into (default: the name of the directory holding the file). Created by the first build.' },
+            'display-name': { type: 'string', value: '<name>', description: 'Template name when this build creates the template.' },
+            description: { type: 'string', value: '<text>', description: 'Version description.' },
+            publish: { type: 'boolean', description: 'Publish the version once it is registered (new workspaces of the slug then use it). Default: leave it unpublished.' },
+            acknowledge: { type: 'string', multiple: true, value: '<path>', description: 'Absolute path the credential scan may report without failing the build (repeatable, up to 200).' },
+            wait: { type: 'boolean', description: 'Wait until the build is registered (or fails).' },
+            timeout: { type: 'string', value: '<duration>', description: 'Give up waiting after this long (default 30m). The build continues server side.' },
+            timing: { type: 'boolean', description: 'Print where the time went on stderr: packing, uploads, the request, the wait, and the build’s queued and run time (with --json: a "timing" field).' },
+        },
+        examples: ['shard templates build template.yaml --wait', 'shard templates build acme/template.yaml --slug acme-dev --publish --wait --timing'],
+    },
+    {
+        path: ['templates', 'export'],
+        summary: 'Print (or save) the template.yaml a version was built from, ready to build again',
+        description: 'Versions saved from a workspace (or a draft) and platform versions have no recipe: change their settings through a draft publish instead.',
+        positionals: [{ name: 'slug@version', required: true }],
+        options: {
+            out: { type: 'string', value: '<file>', description: 'Write to this file instead of stdout.' },
+            force: { type: 'boolean', description: 'Overwrite an existing --out file.' },
+            owner: { type: 'string', value: '<platform|organization>', description: 'Pick the platform template even when an organization template shadows its slug.' },
+        },
+        examples: ['shard templates export acme-dev@3 --out template.yaml'],
+    },
+    {
+        path: ['templates', 'test'],
+        summary: 'Open a test instance of a version, published or not (a disposable session workspace)',
+        description: 'Runs the version’s start commands and services like a new workspace. It ends with "shard ws close <key>" or when idle. Owners, admins and API keys with a tool permission.',
+        positionals: [{ name: 'slug@version', required: true }],
+        options: {
+            'instance-key': { type: 'string', value: '<key>', description: 'Workspace key of the test instance (default sf:test:<slug>:<random>).' },
+            ...INPUTS,
+            ...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).' },
+            ...TIMING,
+        },
+        examples: ['shard templates test acme-dev@4 --input PROJECT_NAME=demo'],
+    },
+    {
+        path: ['templates', 'builds', 'list'],
+        summary: 'List the organization’s template builds, newest first',
+        positionals: [],
+        options: {
+            template: { type: 'string', value: '<slug>', description: 'Only builds of this template.' },
+            state: { type: 'string', value: '<state>', description: 'queued, building, testing, publishing, published, failed or canceled.' },
+            ...PAGE,
+            limit: { type: 'string', value: '<n>', description: 'Page size, 1-200 (default 50).' },
+        },
+    },
+    { path: ['templates', 'builds', 'get'], summary: 'Show one template build (state, registration, denied hosts, failure)', positionals: [BUILD_ID], options: {} },
+    {
+        path: ['templates', 'builds', 'log'],
+        summary: 'Print (or save) a build’s full log',
+        positionals: [BUILD_ID],
+        options: { out: { type: 'string', value: '<file>', description: 'Write to this file instead of stdout.' } },
+    },
+    { path: ['templates', 'builds', 'cancel'], summary: 'Cancel a template build (queued: at once; running: honoured until publishing starts)', positionals: [BUILD_ID], options: {} },
+    {
+        path: ['templates', 'languages'],
+        summary: 'List the languages (and versions) a base offers a template.yaml',
+        description: 'included: the base already has that version (nothing is installed). A version the base has another version of is left out. HOSTS is what an auto build network allows for it.',
+        positionals: [],
+        options: { base: { type: 'string', value: '<slug@version>', description: 'The base (required), e.g. ubuntu-24.04@1.' } },
+        examples: ['shard templates languages --base ubuntu-24.04@1'],
+    },
+    {
+        path: ['templates', 'packages', 'search'],
+        summary: 'Search apt, pip or npm package names for a template.yaml',
+        description: 'apt searches the package index of a base (--base, required); pip returns names only; npm searches the registry.',
+        positionals: [{ name: 'ecosystem', required: true }, { name: 'query', required: true }],
+        options: {
+            base: { type: 'string', value: '<slug@version>', description: 'The base whose apt index to search (apt only).' },
+            limit: { type: 'string', value: '<n>', description: 'Results, 1-50 (default 20).' },
+        },
+        examples: ['shard templates packages search apt jq --base ubuntu-24.04@1', 'shard templates packages search npm typescript'],
+    },
     {
         path: ['templates', 'files'],
         summary: 'List one directory of a template version’s file tree (or show one entry with --stat)',
@@ -420,7 +537,7 @@ const GROUPS = {
     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',
+    templates: 'Build templates from template.yaml, test and export versions, browse templates (file tree, diff) and develop them in a draft',
 };
 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. */
@@ -691,7 +808,7 @@ export const EXIT_CODE_HELP = [
     '  3    not found (workspace, operation or route)',
     '  4    authentication/authorization (missing, malformed, revoked or insufficient key)',
     '  5    timeout (waiting gave up; the operation continues server side)',
-    '  6    operation failed or canceled',
+    '  6    operation failed or canceled (retryable=true in the error: it may succeed later, e.g. capacity_unavailable)',
     '  130  interrupted (Ctrl-C)',
     '  exec: the command’s own exit code (124 if it timed out, 128+N if killed by signal N)',
 ];