@shardflux/cli 0.4.0 → 0.5.0

package/dist/args.d.ts

@@ -1,4 +1,4 @@
-export declare const CLI_VERSION = "0.4.0";
+export declare const CLI_VERSION = "0.5.0";
 export interface OptionSpec {
     type: 'string' | 'boolean';
     short?: string;
@@ -12,6 +12,11 @@ export interface PositionalSpec {
     required?: boolean;
     /** Collects every remaining argument (only the last positional). */
     variadic?: boolean;
+    /**
+     * With `variadic`: free text, the remaining arguments joined with spaces (`shard feedback it hung`), shown as
+     * `<name...>`; no `--` needed. Optional unless `required` (the handler may take it from elsewhere, e.g. --from-file).
+     */
+    words?: boolean;
 }
 export interface CommandSpec {
     path: string[];
@@ -22,8 +27,9 @@ export interface CommandSpec {
     examples?: string[];
 }
 export declare const GLOBAL_OPTIONS: Record<string, OptionSpec>;
+/** Every command: the account plane first (sign in, set up), then the project-key commands. */
 export declare const COMMANDS: CommandSpec[];
-/** Canonical command words: aliases resolved, `workspaces files|operations` folded to the top-level group. */
+/** Canonical command words: aliases resolved, `workspaces files|operations|executions` folded to the top-level group. */
 export declare function normalizeWords(words: string[]): string[];
 export declare function findCommand(words: string[]): CommandSpec | undefined;
 /** "90s", "5m", "1.5h", "250ms"; a bare number is seconds. */
@@ -67,6 +73,12 @@ export type Parsed = {
 export declare function parseCommandLine(argv: readonly string[]): Parsed;
 export declare function usageLine(c: CommandSpec): string;
 export declare function commandHelp(c: CommandSpec): string;
-export declare function groupHelp(group: string): string;
+/** Help of a group (`auth`) or a sub-group (`auth totp`): its commands with their summaries. */
+export declare function groupHelp(prefix: string | readonly string[]): string;
 export declare const EXIT_CODE_HELP: string[];
+/** The top help's sections: every command's group (first word) is in exactly one (args.test.ts checks). */
+export declare const HELP_SECTIONS: readonly {
+    title: string;
+    groups: readonly string[];
+}[];
 export declare function topHelp(): string;

package/dist/args.js

@@ -5,16 +5,18 @@
  *   shard [global options] <command> [options] [arguments]
  *
  * `workspaces` may be written `ws`; `operations` may be written `ops`; the
- * `files` and `operations` groups are also reachable under `workspaces`
- * (`shard workspaces files read ...` == `shard files read ...`).
+ * `files`, `operations` and `executions` groups are also reachable under
+ * `workspaces` (`shard workspaces files read ...` == `shard files read ...`).
+ * The account plane's commands (0.5.0) are in account-args.ts.
  */
 import { parseArgs } from 'node:util';
+import { ACCOUNT_COMMANDS } from "./account-args.js";
 import { UsageError } from "./errors.js";
-export const CLI_VERSION = '0.4.0';
+export const CLI_VERSION = '0.5.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").' },
+    'agent-label': { type: 'string', value: '<label>', description: 'Attribution label for workspace tool tokens, and the reporting agent of shard feedback (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.' },
@@ -36,6 +38,14 @@ const TIMING = {
 const WAKE_TIMING = {
     timing: { type: 'boolean', description: 'Print where the time went when the command had to wake the workspace (stderr; with --json a "timing" field, null without a wake).' },
 };
+/** `--if-revision` (0.5.0) of the mutating files commands: the tree revision a file-first write applies to (contracts §29.8). */
+const IF_REVISION = {
+    'if-revision': {
+        type: 'string',
+        value: '<n>',
+        description: 'File-first: apply only while the workspace’s tree is at revision n (from "shard ws get", an earlier write or an execution), else fail with tree_revision_mismatch and change nothing. The new tree revision is printed after the write.',
+    },
+};
 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 (a start waiting for capacity until its deadline, 15 minutes after it began; then it fails with capacity_unavailable).' },
@@ -69,6 +79,30 @@ const INPUTS = {
     '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 };
+/** Feedback categories, in the order the API documents them (contract: POST /v1/feedback). */
+const FEEDBACK_HELP = [
+    ['bug', 'something failed or behaved wrongly'],
+    ['confusing', 'an error, doc, name or output was unclear or misleading'],
+    ['missing', 'a capability, option or template you needed does not exist'],
+    ['idea', 'a suggestion or improvement'],
+    ['praise', 'something worked well'],
+    ['other', 'anything else (the default)'],
+];
+/**
+ * Why `shard feedback` exists, for the coding agents that drive shard: the same words as the top-level help and the
+ * MCP server's send_feedback tool. It has to make an agent actually send feedback while it works.
+ */
+const FEEDBACK_WHY = [
+    'Sends your message straight to the Shardflux founder, who reads every one. Agents: use it actively while you work,',
+    'not once at the end. Send a short note the moment:',
+    '- something fails unexpectedly, an error or doc is unclear, an option is missing, or you needed a workaround;',
+    '- your user complains or is frustrated about Shardflux or the workflow around it (slowness, cost or limits,',
+    '  confusing setup, a missing feature, a workaround): paraphrase it, with what they were trying to do;',
+    '- your user asked for something Shardflux could not do, or made awkward.',
+    'Short and frequent beats polished; include the request id and error code (a failed shard command prints a',
+    'ready-made "feedback:" line to fill in). No need to ask first, but tell your user you sent it. Leave out private',
+    'data about the user and secrets or code they did not mean to share; paraphrase, never paste transcripts.',
+];
 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).' },
@@ -86,21 +120,68 @@ const SECRET_PERMISSIONS = {
     '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 = [
+const KEY_COMMANDS = [
     {
         path: ['login'],
-        summary: 'Verify SHARDFLUX_API_KEY and show its organization, project and tool permissions',
-        description: 'shard never stores the key: it is read from SHARDFLUX_API_KEY on every run.',
+        summary: 'Verify the project API key (SHARDFLUX_API_KEY, else the saved one) and show its organization, project and tools',
+        description: 'Checks a key; it stores nothing. To sign in to your account (and save a key with "shard setup") use "shard auth login".',
         positionals: [],
         options: {},
     },
-    { path: ['whoami'], summary: 'Show the principal behind SHARDFLUX_API_KEY', positionals: [], options: {} },
-    { path: ['version'], summary: 'Print the CLI and SDK versions', positionals: [], options: {} },
+    { path: ['whoami'], summary: 'Show the principal behind the project API key (SHARDFLUX_API_KEY, else the saved one)', positionals: [], options: {} },
+    {
+        path: ['version'],
+        summary: 'Print the CLI and SDK versions and whether a newer shard is available',
+        description: 'The update status comes from GET /v1/client-versions, asked at most once a day (cached in the config directory). --check asks now, also when SHARDFLUX_NO_UPDATE_CHECK is set.',
+        positionals: [],
+        options: { check: { type: 'boolean', description: 'Ask the API now instead of using the daily cache.' } },
+    },
+    {
+        path: ['feedback'],
+        summary: 'Tell the Shardflux founder what failed, confused you or is missing (agents: as you work)',
+        description: [
+            ...FEEDBACK_WHY,
+            '',
+            'The message is the remaining arguments joined with spaces; quote it (or put it after --) when it contains shell',
+            'characters or words starting with -. For long reports and logs use --from-file (- reads standard input). 1-8000',
+            'characters. Anything shaped like an API key is redacted before it is stored or emailed; leave other secrets out.',
+            'Name the reporting agent with --agent-label or SHARDFLUX_AGENT_LABEL (e.g. claude-code, codex, cursor).',
+            '',
+            'Categories:',
+            ...FEEDBACK_HELP.map(([c, d]) => `  ${c.padEnd(10)} ${d}`),
+        ].join('\n'),
+        positionals: [{ name: 'message', variadic: true, words: true }],
+        options: {
+            category: { type: 'string', value: '<bug|confusing|missing|idea|praise|other>', description: 'Kind of feedback (default other; see Categories).' },
+            workspace: { type: 'string', value: '<id|key>', description: 'The workspace it is about.' },
+            'request-id': { type: 'string', value: '<id>', description: 'request_id from the error, so the founder can find the logs.' },
+            'error-code': { type: 'string', value: '<code>', description: 'The error code you saw, e.g. capacity_unavailable.' },
+            command: { type: 'string', value: '<text>', description: 'What you ran, e.g. "shard ws exec acme/demo -- npm test".' },
+            'from-file': { type: 'string', value: '<file|->', description: 'Read the message from this file, or - for standard input (long reports, logs); instead of <message...>.' },
+        },
+        examples: [
+            'shard feedback --category bug --request-id req-5c7744b2bb5c457b86b76101 --error-code capacity_unavailable "ws open failed twice in 10 min; expected a start within a minute"',
+            'shard feedback --category confusing --command "shard ws exec acme/demo -- npm test" exit 137 with no message, took a while to see it was the memory cap',
+            'shard feedback --category missing no way to copy a file between two workspaces, piped files read into files write instead',
+            'npm test 2>&1 | tail -n 60 | shard feedback --category bug --workspace acme/demo --from-file -',
+        ],
+    },
     {
         path: ['usage'],
-        summary: 'Show the organization usage summary for the current period',
+        summary: 'Show the organization usage summary for the current period (or the estimate, a time series, one workspace)',
+        description: 'Default: the summary (meters, allowances, caps). --estimate: the subscription fee, usage charges and projected allowance use at period end. --series: usage over time from the ledger (hour: at most 31 days, day: at most 400 days per request). --workspace: the same series for one workspace (the dashboard’s per-workspace usage).',
         positionals: [],
-        options: { org: { type: 'string', value: '<organization-id>', description: 'Organization (default: the API key’s organization).' } },
+        options: {
+            org: { type: 'string', value: '<organization-id>', description: 'Organization (default: the API key’s organization).' },
+            estimate: { type: 'boolean', description: 'Show the period estimate instead of the summary.' },
+            series: { type: 'boolean', description: 'Show usage over time instead of the summary.' },
+            workspace: { type: 'string', value: '<id|key>', description: 'Show usage over time of this workspace.' },
+            from: { type: 'string', value: '<time>', description: 'With --series/--workspace: start (RFC 3339; default the current period’s start).' },
+            to: { type: 'string', value: '<time>', description: 'With --series/--workspace: end (RFC 3339; default now).' },
+            granularity: { type: 'string', value: '<hour|day>', description: 'With --series/--workspace: bucket size (default: the API’s).' },
+            meter: { type: 'string', value: '<meter>', description: 'With --series/--workspace: only this meter (e.g. cpu_seconds).' },
+        },
+        examples: ['shard usage', 'shard usage --estimate', 'shard usage --series --granularity day', 'shard usage --workspace acme/demo --meter cpu_seconds'],
     },
     {
         path: ['workspaces', 'open'],
@@ -120,6 +201,11 @@ 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.',
             },
+            mode: {
+                type: 'string',
+                value: '<processful|file-first>',
+                description: 'file-first: the workspace is a versioned file tree with no VM between commands; each "shard ws exec" runs in a fresh VM and keeps the files it changed under /home/user as the next tree revision. Ready at once, never suspended, persistent, needs a layered template version. Default: processful for a new key, the stored mode for an existing one (a mode never changes).',
+            },
             ...INPUTS,
             ...CAPS,
             wait: { type: 'boolean', description: 'Wait until ready (default; --no-wait returns at once). Ready includes the template’s start commands and services.' },
@@ -133,6 +219,7 @@ export const COMMANDS = [
             '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',
+            'shard ws open acme/agent-7 --template python-node-browser --mode file-first',
         ],
     },
     {
@@ -153,17 +240,33 @@ export const COMMANDS = [
     { 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',
-        description: 'Runs argv directly (no shell; use `-- bash -lc "..."` for shell syntax). Output is streamed as it arrives and resumes from byte offsets after dropped connections; Ctrl-C stops waiting and cancels the command.',
+        summary: 'Run a command in a workspace; prints its output and exits with its exit code',
+        description: 'Runs argv directly (no shell; use `-- bash -lc "..."` for shell syntax). Processful workspaces: output is streamed as it arrives and resumes from byte offsets after dropped connections; Ctrl-C stops waiting and cancels the command. File-first workspaces: the command runs as an execution in a fresh VM on the latest tree revision; its output is printed when it ended, and the files it changed under /home/user become the next tree revision (-v lists them). An execution cannot be canceled: Ctrl-C stops waiting and names the command that fetches its result later. A failed or lost execution (nothing published) exits 6.',
         positionals: [REF, { name: 'command', required: true, variadic: true }],
         options: {
-            cwd: { type: 'string', value: '<dir>', description: 'Working directory (absolute).' },
+            cwd: { type: 'string', value: '<dir>', description: 'Working directory (absolute; under /home/user on a file-first workspace).' },
             env: { type: 'string', multiple: true, value: '<K=V>', description: 'Environment variable (repeatable).' },
             timeout: { type: 'string', value: '<duration>', description: 'Kill the command after this long (exit code 124).' },
             stdin: { type: 'string', value: '<file|->', description: 'Send this file (or - for standard input) to the command’s stdin (max 1 MiB).' },
+            'execution-id': {
+                type: 'string',
+                value: '<id>',
+                description: 'File-first: the execution’s id (8-128 of A-Z a-z 0-9 . _ : -, starting with a letter or digit; default a fresh ex-<uuid>). Running the same command again with the same id returns its recorded result instead of running it twice, so scripts can repeat the call safely.',
+            },
+            'output-limit': { type: 'string', value: '<bytes>', description: 'File-first: keep at most this many bytes of stdout and of stderr each (1-16777216; default 1 MiB).' },
+            verbose: {
+                type: 'boolean',
+                short: 'v',
+                description: 'After the output, print on stderr what ran: file-first: execution id, state, base -> tree revision, replayed, timings and the changed paths (A|M|D path); processful: the session id and exit status.',
+            },
             ...WAKE_TIMING,
         },
-        examples: ['shard ws exec acme/demo -- python3 -V', 'shard ws exec acme/demo --cwd /home/user/app --env CI=1 -- bash -lc "npm test"'],
+        examples: [
+            'shard ws exec acme/demo -- python3 -V',
+            'shard ws exec acme/demo --cwd /home/user/app --env CI=1 -- bash -lc "npm test"',
+            'shard ws exec acme/agent-7 -v --execution-id build-42 --timeout 10m -- bash -lc "make -C /home/user/app"',
+            'shard ws exec acme/agent-7 --json -- python3 /home/user/report.py > result.json',
+        ],
     },
     { path: ['workspaces', 'suspend'], summary: 'Suspend a running workspace (durable checkpoint)', positionals: [REF], options: { ...WAIT } },
     { path: ['workspaces', 'resume'], summary: 'Resume a suspended workspace', positionals: [REF], options: { ...WAIT } },
@@ -246,8 +349,10 @@ export const COMMANDS = [
             from: { type: 'string', value: '<file|->', description: 'Local file to upload, or - for standard input (default -).' },
             append: { type: 'boolean', description: 'Append instead of replacing.' },
             parents: { type: 'boolean', description: 'Create missing parent directories (default; --no-parents to refuse).' },
+            ...IF_REVISION,
             ...WAKE_TIMING,
         },
+        examples: ['shard files write acme/demo /home/user/notes.txt --from notes.txt', 'printf "x = 1\\n" | shard files write acme/agent-7 /home/user/app/config.py --if-revision 4'],
     },
     {
         path: ['files', 'ls'],
@@ -255,6 +360,47 @@ export const COMMANDS = [
         positionals: [REF, { name: 'path', required: true }],
         options: { limit: { type: 'string', value: '<n>', description: 'Maximum entries (default 1000).' }, ...WAKE_TIMING },
     },
+    {
+        path: ['files', 'stat'],
+        summary: 'Show one path’s metadata in a workspace',
+        positionals: [REF, { name: 'path', required: true }],
+        options: { revision: { type: 'boolean', description: 'Also print the revision (SHA-256 of the content) of a regular file up to 256 MiB, as files patch --expected-revision takes it.' }, ...WAKE_TIMING },
+    },
+    {
+        path: ['files', 'search'],
+        summary: 'Search file contents under a directory (or in one file) in a workspace (like grep -rn)',
+        description: 'Prints path:line:column: text for each matching line, in path order. Binary files, symbolic links, files above 1 MiB and .git/node_modules directories are skipped. The search stops at --max matches, 10 s or 4 MiB of results (it then says why on stderr). A suspended workspace whose disk a host still holds is searched there without waking it.',
+        positionals: [REF, { name: 'path', required: true }, { name: 'pattern', required: true }],
+        options: {
+            regex: { type: 'boolean', description: 'The pattern is an RE2 regular expression (default: literal text).' },
+            'ignore-case': { type: 'boolean', short: 'i', description: 'Ignore case.' },
+            include: { type: 'string', multiple: true, value: '<glob>', description: 'Only matching files (repeatable; gitignore-style: "*.py" matches the name at any depth, "src/**/*.ts" the path relative to <path>).' },
+            exclude: { type: 'string', multiple: true, value: '<glob>', description: 'Skip matching files and directories (repeatable; "build/" matches directories only); replaces the default .git and node_modules exclusions.' },
+            max: { type: 'string', value: '<n>', description: 'Stop after this many matches, 1-5000 (default 200).' },
+            ...WAKE_TIMING,
+        },
+        examples: ['shard files search acme/demo /home/user/project TODO --include "**/*.py"', 'shard files search acme/demo /home/user/project "def \\w+_test" --regex --json'],
+    },
+    {
+        path: ['files', 'patch'],
+        summary: 'Edit a file in a workspace by replacing exact text, or replace its content, atomically',
+        description: 'Each --old must occur exactly once in the file (or use --replace-all); pairs apply in order, all or nothing. With --expected-revision the file must still have that revision (from files stat --revision or an earlier patch; "absent": it must not exist), else nothing changes and the command fails with revision_mismatch.',
+        positionals: [REF, { name: 'path', required: true }],
+        options: {
+            old: { type: 'string', multiple: true, value: '<text>', description: 'Exact text to replace (repeatable; pairs with --new in order).' },
+            new: { type: 'string', multiple: true, value: '<text>', description: 'Replacement text (repeatable; one per --old).' },
+            'replace-all': { type: 'boolean', description: 'Replace every occurrence of each --old instead of requiring exactly one.' },
+            'content-file': { type: 'string', value: '<file|->', description: 'Replace the whole file with this local UTF-8 file (- for standard input; up to 7 MiB, use files write for more) instead of --old/--new.' },
+            'expected-revision': { type: 'string', value: '<sha256|absent>', description: 'Fail unless the file currently has this revision.' },
+            ...IF_REVISION,
+            ...WAKE_TIMING,
+        },
+        examples: [
+            'shard files patch acme/demo /home/user/app.py --old "DEBUG = True" --new "DEBUG = False"',
+            'shard files patch acme/demo /home/user/app.py --content-file app.py --expected-revision "$(shard files stat acme/demo /home/user/app.py --revision --json | jq -r .revision)"',
+            'shard files patch acme/agent-7 /home/user/app.py --old "DEBUG = True" --new "DEBUG = False" --if-revision "$(shard ws get acme/agent-7 --json | jq .tree_revision)"',
+        ],
+    },
     {
         path: ['operations', 'list'],
         summary: 'List a workspace’s operations, newest first',
@@ -266,6 +412,16 @@ export const COMMANDS = [
         },
     },
     { path: ['operations', 'get'], summary: 'Show one operation', positionals: [{ name: 'operation-id', required: true }], options: {} },
+    {
+        path: ['executions', 'get'],
+        summary: 'Fetch the result of a file-first workspace’s execution (exit: its command’s code; 6 failed/lost; 5 still running)',
+        description: 'Prints the command’s stdout and stderr like "shard ws exec", then on stderr what ran: state, exit status, base -> tree revision and the changed paths (with --json one object instead). An execution still queued or running prints its state and exits 5: wait for it with --wait. Results are kept 7 days.',
+        positionals: [REF, { name: 'execution-id', required: true }],
+        options: {
+            wait: { type: 'string', value: '<duration>', description: 'While it runs, wait up to this long for it to end (e.g. 30s, 10m; default: answer at once).' },
+        },
+        examples: ['shard executions get acme/agent-7 build-42', 'shard ws executions get acme/agent-7 ex-6f1c2a9e-0d7b-4c1e-9a53-2b8e1f0c4d7a --wait 10m --json'],
+    },
     {
         path: ['secrets', 'create'],
         summary: 'Create a secret; the value is read from standard input or --from-file, never from arguments',
@@ -532,18 +688,57 @@ export const COMMANDS = [
         options: { timeout: { type: 'string', value: '<duration>', description: 'Give up after this long (default 5m).' }, ...TIMING },
     },
 ];
+/** Every command: the account plane first (sign in, set up), then the project-key commands. */
+export const COMMANDS = [...ACCOUNT_COMMANDS.filter((c) => c.path[0] !== 'templates'), ...KEY_COMMANDS, ...ACCOUNT_COMMANDS.filter((c) => c.path[0] === 'templates')];
 const GROUPS = {
+    auth: 'Create an account and sign in (the session is saved in the credentials file); passwords, email, two-factor authentication and sessions',
+    'auth password': 'Change or reset your password',
+    'auth email': 'Change your sign-in email',
+    'auth totp': 'Two-factor authentication with an authenticator app',
+    orgs: 'Organizations you belong to (signed in)',
+    projects: 'Projects of an organization (signed in)',
+    'api-keys': 'Project API keys (signed in; secrets are shown once)',
+    members: 'Members of an organization and their roles (signed in)',
+    invitations: 'Invite people to an organization and accept invitations (signed in)',
+    billing: 'Plans, upgrades (Stripe Checkout), the billing portal, invoices and usage alerts (signed in; plans is public)',
+    audit: 'The organization audit log and its export (signed in; owners and admins)',
+    account: 'Your account: data export and deletion (signed in)',
+    egress: 'Outbound network policies of the project and its workspaces (project API key)',
+    volumes: 'Shared volumes: persistent storage attached to workspaces (project API key)',
     workspaces: 'Open, inspect and manage workspaces',
-    files: 'Read, write and list files in a workspace',
+    files: 'Read, write, list, search and patch files in a workspace',
     operations: 'Inspect and wait for lifecycle operations',
+    executions: 'Fetch the results of file-first executions (the commands "shard ws exec" runs in file-first workspaces)',
     secrets: 'Manage secrets (values are write-only) and bind them to workspaces',
-    templates: 'Build templates from template.yaml, test and export versions, browse templates (file tree, diff) and develop them in a draft',
+    templates: 'Build templates from template.yaml, test and export versions, browse templates (file tree, diff), develop them in a draft, and publish or archive versions',
+};
+const ALIASES = {
+    ws: 'workspaces',
+    workspace: 'workspaces',
+    ops: 'operations',
+    operation: 'operations',
+    execution: 'executions',
+    file: 'files',
+    secret: 'secrets',
+    template: 'templates',
+    org: 'orgs',
+    organization: 'orgs',
+    organizations: 'orgs',
+    project: 'projects',
+    'api-key': 'api-keys',
+    keys: 'api-keys',
+    member: 'members',
+    invitation: 'invitations',
+    invite: 'invitations',
+    invites: 'invitations',
+    volume: 'volumes',
 };
-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. */
+/** Groups also reachable under `workspaces` (`shard workspaces files read ...` == `shard files read ...`). */
+const FOLDED = new Set(['files', 'operations', 'executions']);
+/** Canonical command words: aliases resolved, `workspaces files|operations|executions` folded to the top-level group. */
 export function normalizeWords(words) {
     const w = words.map((x) => ALIASES[x] ?? x);
-    if (w[0] === 'workspaces' && (w[1] === 'files' || w[1] === 'operations'))
+    if (w[0] === 'workspaces' && w[1] !== undefined && FOLDED.has(w[1]))
         return w.slice(1);
     return w;
 }
@@ -681,10 +876,13 @@ export function parseCommandLine(argv) {
                 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)) {
+        if (/^--?password(=.*)?$/i.test(a)) {
+            throw new UsageError(`shard never accepts secret values on the command line (shell history and process listings would expose them); passwords are read from standard input (printf '%s\\n' "$PASSWORD" | shard ...) or typed at the prompt`);
+        }
+        if (/^--?(value|secret-value)(=.*)?$/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)');
+        throw new UsageError('shard reads the API key only from the SHARDFLUX_API_KEY environment variable or its credentials file (shard setup), and a session only from SHARDFLUX_SESSION_TOKEN or shard auth login; never pass one 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 = [];
@@ -725,16 +923,15 @@ export function parseCommandLine(argv) {
             }
             return { kind: 'help', text: topHelp() };
         }
-        const group = normalizeWords(words)[0];
         const stray = rest.find((r) => !r.startsWith('-'));
         if (stray !== undefined)
             throw new UsageError(`unknown command "${[...normalizeWords(words), stray].join(' ')}"`);
-        return { kind: 'help', text: groupHelp(group) };
+        return { kind: 'help', text: groupHelp(normalizeWords(words)) };
     }
     let parsed;
     try {
         parsed = parseArgs({
-            args: rest,
+            args: command.positionals.some((p) => p.name === 'link|token') ? emailedTokensAsPositionals(rest, command) : rest,
             options: toParseArgsOptions({ ...GLOBAL_OPTIONS, ...command.options }),
             allowPositionals: true,
             allowNegative: true,
@@ -753,7 +950,9 @@ export function parseCommandLine(argv) {
     const specs = command.positionals;
     const variadic = specs.at(-1)?.variadic === true;
     const required = specs.filter((s) => s.required && !s.variadic).length;
-    if (positionals.length < required || (variadic && positionals.length < specs.length)) {
+    // Free text (`words`) is required only when marked so; `exec`'s command always is.
+    const variadicRequired = variadic && (specs.at(-1).words !== true || specs.at(-1).required === true);
+    if (positionals.length < required || (variadicRequired && positionals.length < specs.length)) {
         const missing = specs[Math.min(positionals.length, specs.length - 1)];
         throw new UsageError(`missing <${missing.name}> for "shard ${command.path.join(' ')}"`);
     }
@@ -774,6 +973,22 @@ export function parseCommandLine(argv) {
         },
     };
 }
+/**
+ * An emailed token is 43 base64url characters and begins with `-` one time in 64 (`--` one in 4096): passed bare to a
+ * command that takes `<link|token>`, parseArgs would reject it as an unknown option. A word that long, of base64url
+ * characters only and not one of the command's options, is the token: it is moved behind `--`.
+ */
+const EMAILED_TOKEN_WORD = /^-[A-Za-z0-9_-]{39,199}$/;
+function emailedTokensAsPositionals(rest, command) {
+    const end = rest.indexOf('--');
+    const head = end < 0 ? [...rest] : rest.slice(0, end);
+    const tail = end < 0 ? [] : rest.slice(end + 1);
+    const options = new Set(Object.entries({ ...GLOBAL_OPTIONS, ...command.options }).flatMap(([name, o]) => [`--${name}`, `--no-${name}`, ...(o.short ? [`-${o.short}`] : [])]));
+    const tokens = head.filter((a) => EMAILED_TOKEN_WORD.test(a) && !options.has(a));
+    if (tokens.length === 0)
+        return [...rest];
+    return [...head.filter((a) => !tokens.includes(a)), '--', ...tokens, ...tail];
+}
 // ---- help ----------------------------------------------------------------------------------
 function optionLines(opts) {
     const rows = Object.entries(opts).map(([name, o]) => [`${o.short ? `-${o.short}, ` : '    '}--${name}${o.value ? ` ${o.value}` : ''}`, o.description]);
@@ -781,7 +996,7 @@ function optionLines(opts) {
     return rows.map(([l, d]) => `  ${l.padEnd(w)}  ${d}`);
 }
 export function usageLine(c) {
-    const pos = c.positionals.map((p) => (p.variadic ? `-- <${p.name}> [args...]` : p.required ? `<${p.name}>` : `[${p.name}]`));
+    const pos = c.positionals.map((p) => (p.variadic ? (p.words ? `<${p.name}...>` : `-- <${p.name}> [args...]`) : p.required ? `<${p.name}>` : `[${p.name}]`));
     const opts = Object.keys(c.options).length > 0 ? ' [options]' : '';
     return `shard ${c.path.join(' ')}${opts}${pos.length ? ` ${pos.join(' ')}` : ''}`;
 }
@@ -796,43 +1011,68 @@ export function commandHelp(c) {
         lines.push('', 'Examples:', ...c.examples.map((e) => `  ${e}`));
     return lines.join('\n') + '\n';
 }
-export function groupHelp(group) {
-    const cmds = COMMANDS.filter((c) => c.path[0] === group);
+/** Help of a group (`auth`) or a sub-group (`auth totp`): its commands with their summaries. */
+export function groupHelp(prefix) {
+    const words = typeof prefix === 'string' ? [prefix] : [...prefix];
+    const group = words.join(' ');
+    const cmds = COMMANDS.filter((c) => words.every((w, i) => c.path[i] === w));
     const w = Math.max(...cmds.map((c) => usageLine(c).length));
-    return [`Usage: shard ${group} <command> [options]`, '', `${GROUPS[group] ?? ''}.`, '', 'Commands:', ...cmds.map((c) => `  ${usageLine(c).padEnd(w)}  ${c.summary}`), ...(group === 'workspaces' ? ['', 'Also: shard workspaces files <read|write|ls> ... and shard workspaces operations <list|get|wait> ...'] : []), '', `Run "shard ${group} <command> --help" for details.`].join('\n') + '\n';
+    return [`Usage: shard ${group} <command> [options]`, '', `${GROUPS[group] ?? GROUPS[words[0]] ?? ''}.`, '', 'Commands:', ...cmds.map((c) => `  ${usageLine(c).padEnd(w)}  ${c.summary}`), ...(group === 'workspaces' ? ['', 'Also: shard workspaces files <read|write|ls|stat|search|patch> ..., shard workspaces operations <list|get|wait> ... and shard workspaces executions get ...'] : []), '', `Run "shard ${group} <command> --help" for details.`].join('\n') + '\n';
 }
 export const EXIT_CODE_HELP = [
     '  0    success',
     '  1    error (API refusal such as conflict or quota, network, protocol)',
     '  2    usage error (bad arguments, or input the API rejected as invalid)',
     '  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 (retryable=true in the error: it may succeed later, e.g. capacity_unavailable)',
+    '  4    authentication/authorization (missing, malformed, revoked or insufficient key or session; step-up or second factor needed)',
+    '  5    timeout (waiting gave up; the operation, execution or checkout continues server side)',
+    '  6    operation failed or canceled, or a file-first execution failed or was lost (retryable=true in the error: it may succeed later, e.g. capacity_unavailable); a checkout that expired',
     '  130  interrupted (Ctrl-C)',
-    '  exec: the command’s own exit code (124 if it timed out, 128+N if killed by signal N)',
+    '  exec, executions get: the command’s own exit code (124 if it timed out, 128+N if killed by signal N); executions get: 5 while it still runs',
+];
+/** The top help's sections: every command's group (first word) is in exactly one (args.test.ts checks). */
+export const HELP_SECTIONS = [
+    { title: 'Account (a user session: shard auth login)', groups: ['auth', 'setup', 'env', 'orgs', 'projects', 'api-keys', 'members', 'invitations', 'billing', 'audit', 'account'] },
+    { title: 'Workspaces (a project API key: SHARDFLUX_API_KEY, else the one shard setup saved)', groups: ['login', 'whoami', 'usage', 'workspaces', 'files', 'operations', 'executions', 'secrets', 'volumes', 'egress'] },
+    { title: 'Templates (publish and archive use the session; the rest the API key)', groups: ['templates'] },
+    { title: 'Other', groups: ['feedback', 'version'] },
 ];
 export function topHelp() {
     const w = Math.max(...COMMANDS.map((c) => usageLine(c).length));
+    const sections = HELP_SECTIONS.flatMap((s) => ['', `${s.title}:`, ...s.groups.flatMap((g) => COMMANDS.filter((c) => c.path[0] === g)).map((c) => `  ${usageLine(c).padEnd(w)}  ${c.summary}`)]);
     return [
         `shard ${CLI_VERSION} — the Shardflux command line (built on @shardflux/sdk)`,
         '',
         'Usage: shard [global options] <command> [options] [arguments]',
         '',
-        'Commands:',
-        ...COMMANDS.map((c) => `  ${usageLine(c).padEnd(w)}  ${c.summary}`),
+        'Feedback: shard feedback [options] <message...>',
+        ...FEEDBACK_WHY.map((l) => `  ${l}`),
+        '  shard feedback --category bug --request-id req-5c7744b2bb5c457b86b76101 "ws open waited 40 s in capacity_pending; expected under 5 s"',
+        '  shard feedback --category confusing "user was frustrated that ws open needs a template slug they had to look up; they expected a default"',
+        '',
+        'Start here (everything the web app does, from a terminal; a person only opens the emailed link and pays in Checkout):',
+        `  printf '%s\\n' "$PASSWORD" | shard auth register --email you@example.com`,
+        `  shard auth verify-email '<link from the email>'`,
+        `  printf '%s\\n' "$PASSWORD" | shard auth login --email you@example.com`,
+        '  shard setup                                   # organization, project and an API key, saved',
+        '  shard ws open demo --template python-node-browser',
+        ...sections,
         '',
-        'Aliases: ws = workspaces, ops = operations; "shard workspaces files|operations ..." also works.',
+        'Aliases: ws = workspaces, ops = operations, org = orgs, keys = api-keys; "shard workspaces files|operations|executions ..." also works.',
         '',
         'Global options:',
         ...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_...); default: the key shard setup saved. Never pass it as an argument',
+        '  SHARDFLUX_SESSION_TOKEN    user session (sfu_...) for account commands; default: the session shard auth login saved',
+        '  SHARDFLUX_API_URL          API base URL (default https://api.shardflux.dev); credentials are saved per API URL',
+        '  SHARDFLUX_CONFIG_DIR       where credentials.json and update-check.json live (default $XDG_CONFIG_HOME/shardflux, else ~/.config/shardflux; %APPDATA%\\shardflux on Windows)',
+        '  SHARDFLUX_NO_UPDATE_CHECK  1: never ask whether a newer shard exists (NO_UPDATE_NOTIFIER=1 too)',
+        '  SHARDFLUX_AGENT_LABEL      attribution label for tool tokens and the agent named in feedback (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)',
+        '  BROWSER                    program that opens URLs for --open (default xdg-open, open or start)',
         '',
         'Exit codes:',
         ...EXIT_CODE_HELP,

package/dist/bin.js

@@ -1,19 +1,8 @@
 #!/usr/bin/env node
 /**
- * `shard` executable. Ctrl-C aborts in-flight waits/streams cleanly (exit
- * 130); a second Ctrl-C exits at once. Output is flushed before exiting
- * (stdout/stderr pipes are asynchronous on macOS).
+ * `shard` executable: main() runs the CLI as this process (argv, stdio, environment). Ctrl-C aborts in-flight
+ * waits/streams cleanly (exit 130); a second Ctrl-C exits at once. Output is flushed before exiting (stdout/stderr
+ * pipes are asynchronous on macOS). The `shardflux` npm bundle calls main() with its own identity instead.
  */
-import { run } from "./main.js";
-const controller = new AbortController();
-let interrupts = 0;
-process.on('SIGINT', () => {
-    interrupts += 1;
-    if (interrupts > 1)
-        process.exit(130);
-    controller.abort(new Error('interrupted'));
-});
-const flush = (stream) => new Promise((resolve) => stream.write('', () => resolve()));
-const code = await run(process.argv.slice(2), { stdout: process.stdout, stderr: process.stderr, stdin: process.stdin, env: process.env }, { signal: controller.signal });
-await Promise.all([flush(process.stdout), flush(process.stderr)]);
-process.exit(code);
+import { main } from "./main.js";
+await main();

package/dist/browser.d.ts

@@ -0,0 +1,7 @@
+/** The command that would open `url` (exported for tests). */
+export declare function openerFor(url: string, env: Record<string, string | undefined>, platform?: NodeJS.Platform): {
+    command: string;
+    args: string[];
+};
+/** Starts the browser detached and returns whether it could be started; only http(s) URLs are opened. */
+export declare function openUrl(url: string, env: Record<string, string | undefined>): boolean;

package/dist/browser.js

@@ -0,0 +1,39 @@
+/**
+ * `--open` (0.5.0+): opens a URL in the default browser, best effort. The URL is always printed as well, so a
+ * failure to open changes nothing: no error, no exit code. $BROWSER (a program run with the URL as its only argument)
+ * wins; otherwise `open` (macOS), `rundll32 url.dll,FileProtocolHandler` (Windows) or `xdg-open` (elsewhere).
+ */
+import { spawn } from 'node:child_process';
+/** The command that would open `url` (exported for tests). */
+export function openerFor(url, env, platform = process.platform) {
+    const browser = env.BROWSER?.trim();
+    if (browser)
+        return { command: browser, args: [url] };
+    if (platform === 'darwin')
+        return { command: 'open', args: [url] };
+    if (platform === 'win32')
+        return { command: 'rundll32', args: ['url.dll,FileProtocolHandler', url] };
+    return { command: 'xdg-open', args: [url] };
+}
+/** Starts the browser detached and returns whether it could be started; only http(s) URLs are opened. */
+export function openUrl(url, env) {
+    let u;
+    try {
+        u = new URL(url);
+    }
+    catch {
+        return false;
+    }
+    if (u.protocol !== 'https:' && u.protocol !== 'http:')
+        return false;
+    const { command, args } = openerFor(u.toString(), env);
+    try {
+        const child = spawn(command, args, { stdio: 'ignore', detached: true, env });
+        child.on('error', () => undefined);
+        child.unref();
+        return true;
+    }
+    catch {
+        return false;
+    }
+}