@shardflux/cli 0.8.1 → 0.10.0

package/dist/args.js

@@ -12,7 +12,7 @@
 import { parseArgs } from 'node:util';
 import { ACCOUNT_COMMANDS } from "./account-args.js";
 import { UsageError } from "./errors.js";
-export const CLI_VERSION = '0.8.1';
+export const CLI_VERSION = '0.10.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).' },
@@ -32,9 +32,9 @@ const MEMORY_ALLOCATION = {
     'allocation-mode': {
         type: 'string',
         value: '<fixed|elastic>',
-        description: 'elastic: --memory-mib is a promise; the workspace holds --memory-held while idle and the host grows it when a command needs it (needs the elastic memory entitlement). Takes effect at the next VM start. Caps given without it make the workspace fixed; a command without caps keeps the stored layout.',
+        description: 'elastic: --memory-mib is the most the workspace may grow to; it holds --memory-held while idle and grows when a command needs more, and billing counts the memory it holds. fixed: a static allocation of --memory-mib. Send it with every caps flag to keep the mode you chose; a command without caps flags keeps the stored layout. Takes effect at the next VM start (shard ws resize changes a running or suspended workspace).',
     },
-    'memory-held': { type: 'string', value: '<mib>', description: 'With --allocation-mode elastic: memory held while idle, in MiB (at least 512, default 1024, at most --memory-mib).' },
+    'memory-held': { type: 'string', value: '<mib>', description: 'Elastic: memory held while idle, in MiB (at least 512, default 1024, at most --memory-mib).' },
 };
 /** `--timing` (0.3.0+): the SDK's lifecycle timing of the command's open, wait or wake (README "Timing"). */
 const TIMING = {
@@ -61,7 +61,16 @@ const WAIT = {
     ...TIMING,
 };
 const REF = { name: 'id|key', required: true };
+/** A TCP port inside the workspace (1-65535). */
+const PORT = { name: 'port', required: true };
 const SLUG = { name: 'slug', required: true };
+/** The screenshot after a computer action or batch (0.10.0+). */
+const COMPUTER_LOOK = {
+    screenshot: { type: 'string', value: '<file>', description: 'Take a screenshot after it and write it here.' },
+    settle: { type: 'string', value: '<ms>', description: 'Wait this long before that screenshot when the screen may change (0-10000, default 250).' },
+    format: { type: 'string', value: '<png|jpeg>', description: 'Screenshot format (default png).' },
+    quality: { type: 'string', value: '<1-100>', description: 'JPEG quality (default 80).' },
+};
 const PAGE = {
     all: { type: 'boolean', description: 'Fetch every page.' },
     limit: { type: 'string', value: '<n>', description: 'Page size.' },
@@ -216,6 +225,11 @@ const KEY_COMMANDS = [
                 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).',
             },
+            'computer-use': {
+                type: 'string',
+                value: '<on|off|inherit>',
+                description: 'Computer use (0.10.0+): on gives the workspace a desktop agents drive (shard ws computer); inherit follows the template. Default: unchanged (off for a new key unless its template turns it on).',
+            },
             ...INPUTS,
             ...CAPS,
             ...MEMORY_ALLOCATION,
@@ -252,6 +266,7 @@ const KEY_COMMANDS = [
     { path: ['workspaces', 'labels'], summary: 'Read or replace workspace labels', positionals: [REF], options: {
             set: { type: 'string', value: '<json>', description: 'Replace all labels; {} clears them.' },
         } },
+    { path: ['workspaces', 'hint'], summary: 'Stage a parked workspace ahead of an imminent tool call', positionals: [REF], options: {} },
     { path: ['workspaces', 'idle'], summary: 'Inspect idle status, set policy or declare a keepalive', positionals: [REF], options: {
             policy: { type: 'string', value: '<policy>', description: 'adaptive, never, fixed:<seconds>, or default to clear the override.' },
             keepalive: { type: 'string', value: '<seconds>', description: 'Declare ongoing work for this many seconds.' },
@@ -262,10 +277,20 @@ const KEY_COMMANDS = [
         description: 'Runs argv directly (no shell; use `-- bash -lc "..."` for shell syntax) and returns the session at once (JSON on stdout). Read it with "shard ws exec-read", stop it with "shard ws exec-cancel".',
         positionals: [REF, { name: 'command', required: true, variadic: true }],
         options: {
+            template: {
+                type: 'string',
+                value: '<slug>',
+                description: 'Open the key first (0.10.0+): the workspace is created from this template on first use (stderr says so) and resumed if suspended; "default" is the platform default template. Without it the key must already have a workspace.',
+            },
             'stdin-open': { type: 'boolean', description: 'Keep pipe stdin open for exec-input.' },
             'session-id': { type: 'string', value: '<id>', description: 'Caller-chosen id to deduplicate starts.' },
             cwd: { type: 'string', value: '<dir>', description: 'Absolute working directory.' },
             timeout: { type: 'string', value: '<duration>', description: 'Kill the command after this long (e.g. 30m, 2h; none unless set). The workspace stays awake until the command ends or this passes (1 hour when unset).' },
+            'resource-hint': {
+                type: 'string',
+                value: '<auto|light|heavy>',
+                description: 'Processful (0.9.0+): heavy gives an elastic workspace its memory before the command starts (a build, a test suite, an install); light starts it at once; auto (default) decides from the command.',
+            },
         },
         examples: ['shard ws exec-start acme/demo --session-id build-1 --timeout 2h -- bash -lc "make -C /home/user/app"', 'shard ws exec-read acme/demo build-1 --follow'],
     },
@@ -297,9 +322,14 @@ const KEY_COMMANDS = [
     {
         path: ['workspaces', 'exec'],
         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 runs to completion: Ctrl-C stops waiting and names the command that fetches its result later. A failed or lost execution (nothing published) exits 6, as does a command that could not start (a --cwd that is not a directory, a program not on PATH), with the workspace’s reason.',
+        description: 'Also `shard exec` (0.10.0+). With --template the key is opened first, so one command creates the workspace on first use: `shard exec acme/demo --template default -- python3 -V`. 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 runs to completion: Ctrl-C stops waiting and names the command that fetches its result later. A failed or lost execution (nothing published) exits 6, as does a command that could not start (a --cwd that is not a directory, a program not on PATH), with the workspace’s reason.',
         positionals: [REF, { name: 'command', required: true, variadic: true }],
         options: {
+            template: {
+                type: 'string',
+                value: '<slug>',
+                description: 'Open the key first (0.10.0+): the workspace is created from this template on first use (stderr says so) and resumed if suspended; "default" is the platform default template. Without it the key must already have a workspace.',
+            },
             cwd: { type: 'string', value: '<dir>', description: 'Working directory, an absolute path (default /home/user; under /home/user on a file-first workspace). A relative path is refused (invalid_cwd).' },
             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).' },
@@ -310,6 +340,11 @@ const KEY_COMMANDS = [
                 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).' },
+            'resource-hint': {
+                type: 'string',
+                value: '<auto|light|heavy>',
+                description: 'Processful (0.9.0+): heavy gives an elastic workspace its memory before the command starts (a build, a test suite, an install); light starts it at once; auto (default) decides from the command.',
+            },
             burst: {
                 type: 'boolean',
                 description: 'Processful: run this command on a larger, short-lived burst VM on the workspace’s host and apply its file changes back when it exits (needs the burst execution entitlement). Its processes and tmpfs content do not come back; the workspace’s own processes pause meanwhile. Not with --stdin; cannot be canceled.',
@@ -329,6 +364,7 @@ const KEY_COMMANDS = [
             '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',
             'shard ws exec acme/demo --burst --burst-vcpus 16 -v -- bash -lc "cd /home/user/app && go build ./..."',
+            'shard ws exec acme/demo --resource-hint heavy -- python3 train.py',
         ],
     },
     {
@@ -351,6 +387,23 @@ const KEY_COMMANDS = [
         positionals: [REF, { name: 'new-key', required: true }],
         options: { ...CAPS, ...MEMORY_ALLOCATION, ...WAIT },
     },
+    {
+        path: ['workspaces', 'resize'],
+        summary: 'Change a workspace’s memory, CPU or disk, running or suspended, without a restart (0.9.0+)',
+        description: 'Memory changes live and disks grow online; a suspended workspace gets its new size when it resumes, before its first call. CPU changes live within the vCPUs the workspace booted with; a larger CPU size applies at the next start. The new caps are stored, so every later start uses them. Prints per resource the change and when it applies: now, on resume or next start. Waits until the resize has finished.',
+        positionals: [REF],
+        options: {
+            memory: { type: 'string', value: '<mib>', description: 'Memory in MiB: the size of a fixed workspace, the most an elastic one may grow to.' },
+            held: { type: 'string', value: '<mib>', description: 'Elastic: the memory held while idle, in MiB (at most the memory size).' },
+            fixed: { type: 'boolean', description: 'Switch to a static allocation of the memory size.' },
+            elastic: { type: 'boolean', description: 'Switch to elastic memory: the workspace holds what its commands use and grows up to the memory size.' },
+            cpu: { type: 'string', value: '<millis>', description: 'CPU in millicores (1000 = one vCPU).' },
+            disk: { type: 'string', value: '<gib>', description: 'Disk in GiB (disks grow only).' },
+            timeout: { type: 'string', value: '<duration>', description: 'Give up waiting after this long (default 5m); the resize continues server side.' },
+            ...TIMING,
+        },
+        examples: ['shard ws resize acme/demo --memory 6144', 'shard ws resize acme/demo --memory 8192 --cpu 4000 --disk 40', 'shard ws resize acme/demo --elastic --held 1024', 'shard ws resize acme/demo --memory 4096 --fixed --json'],
+    },
     {
         path: ['workspaces', 'delete'],
         summary: 'Delete a workspace (tool access ends now; storage is cleaned up asynchronously)',
@@ -410,6 +463,231 @@ const KEY_COMMANDS = [
         },
         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: ['workspaces', 'port', 'expose'],
+        summary: 'Serve a port of a workspace at its own private HTTPS URL (0.9.0+)',
+        description: 'Requests to the URL reach TCP <port> inside the workspace; a request to a parked or suspended workspace wakes it and is answered once it runs. Every port is private: a request carries a port token (shard ws port token), a browser link’s session (shard ws port link) or arrives on the callback URL (shard ws port callback). The server inside the workspace listens on 0.0.0.0. Idempotent: an exposed port keeps its URL, tokens, links and callback URL. --json prints the API’s port object {port, url, created_at, callback}.',
+        positionals: [REF, PORT],
+        options: {},
+        examples: ['shard ws port expose acme/demo 3000', 'curl -H "Authorization: Bearer $(shard ws port token acme/demo 3000)" "$(shard ws port expose acme/demo 3000 --json | jq -r .url)/"'],
+    },
+    { path: ['workspaces', 'port', 'ls'], summary: 'List the exposed ports of a workspace and their URLs (0.9.0+)', positionals: [REF], options: {} },
+    {
+        path: ['workspaces', 'port', 'close'],
+        summary: 'Close an exposed port: its tokens, links and callback URL stop working at once (0.9.0+)',
+        description: 'Idempotent (also when the port is not exposed). Exposing the port again gives it new tokens, links and callback URL; the URL stays the same.',
+        positionals: [REF, PORT],
+        options: {},
+    },
+    {
+        path: ['workspaces', 'port', 'token'],
+        summary: 'Mint a port token and print it alone on stdout (0.9.0+)',
+        description: 'Send it as `Authorization: Bearer <token>` (or `X-Shardflux-Token: <token>` when the app reads Authorization itself) with requests to the port’s URL. Closing the port revokes it. --json prints {token, expires_at, url}.',
+        positionals: [REF, PORT],
+        options: { ttl: { type: 'string', value: '<duration>', description: 'Lifetime, 1m to 24h (e.g. 15m, 2h; default 1h).' } },
+        examples: ['TOKEN=$(shard ws port token acme/demo 3000 --ttl 15m)', 'shard ws port token acme/demo 3000 --json | jq -r .token'],
+    },
+    {
+        path: ['workspaces', 'port', 'link'],
+        summary: 'Create a link that opens the port in a browser and print it (0.9.0+)',
+        description: 'Opening the link starts a browser session for the port (until it expires) and lands on --path. Anyone with the link can open the port until then: share it like a password. --json prints {url, expires_at}.',
+        positionals: [REF, PORT],
+        options: {
+            ttl: { type: 'string', value: '<duration>', description: 'Lifetime of the link and its browser session, 1m to 7d (default 24h).' },
+            path: { type: 'string', value: '<path>', description: 'Where the link lands: a path starting with one / (query allowed; default /).' },
+        },
+        examples: ['shard ws port link acme/demo 3000 --path /dashboard', 'open "$(shard ws port link acme/demo 3000)"'],
+    },
+    {
+        path: ['workspaces', 'port', 'callback'],
+        summary: 'Create (or replace) the port’s callback URL for webhooks and OAuth redirects, or revoke it (0.9.0+)',
+        description: 'Register the printed URL plus your own path with GitHub, Slack, Stripe or an OAuth provider: a request to <url><rest> reaches /<rest> of the port (query kept) without a token header and wakes the workspace like any request. The URL is shown only once; creating it again replaces it (the previous one stops working). --json prints {url, created_at}.',
+        positionals: [REF, PORT],
+        options: { revoke: { type: 'boolean', description: 'Revoke the port’s callback URL instead (idempotent).' } },
+        examples: ['shard ws port callback acme/demo 3000', 'shard ws port callback acme/demo 3000 --revoke'],
+    },
+    // ---- computer use (0.10.0; contracts §45) ----
+    {
+        path: ['workspaces', 'computer', 'status'],
+        summary: 'Show whether the workspace desktop runs, its size and its viewers (0.10.0+)',
+        description: 'Never starts the desktop. Needs computer use on for the workspace (shard ws computer enable). --json prints {running, display, width, height, started_at, session, streams}.',
+        positionals: [REF],
+        options: {},
+    },
+    {
+        path: ['workspaces', 'computer', 'screenshot'],
+        summary: 'Save a screenshot of the workspace desktop (0.10.0+)',
+        description: 'Starts the desktop when it does not run. Writes the image to --out (default screenshot.png, or screenshot.jpg with --format jpeg). --json prints {out, format, width, height, bytes}.',
+        positionals: [REF],
+        options: {
+            out: { type: 'string', value: '<file>', description: 'Where to write the image (default screenshot.png).' },
+            format: { type: 'string', value: '<png|jpeg>', description: 'Image format (default png).' },
+            quality: { type: 'string', value: '<1-100>', description: 'JPEG quality (default 80).' },
+        },
+        examples: ['shard ws computer screenshot acme/demo --out desktop.png', 'shard ws computer screenshot acme/demo --format jpeg --quality 60'],
+    },
+    {
+        path: ['workspaces', 'computer', 'act'],
+        summary: 'Run a batch of computer actions on the workspace desktop (0.10.0+)',
+        description: 'The actions are a JSON array of Claude computer toolset members with their parameters, e.g. [{"action":"left_click","coordinate":[640,400]},{"action":"type","text":"hello"}]; - reads it from standard input. They run in order; the first failure stops the batch and the rest are reported skipped. --screenshot saves a screenshot taken after the last action. --json prints the full result (images base64).',
+        positionals: [REF, { name: 'actions-json', required: true }],
+        options: { ...COMPUTER_LOOK },
+        examples: [
+            `shard ws computer act acme/demo '[{"action":"key","text":"ctrl+l"},{"action":"type","text":"example.com\\n"}]' --screenshot after.png`,
+            'echo \'[{"action":"cursor_position"}]\' | shard ws computer act acme/demo -',
+        ],
+    },
+    {
+        path: ['workspaces', 'computer', 'click'],
+        summary: 'Click on the workspace desktop (0.10.0+)',
+        description: 'At <x> <y> (screen pixels from the top-left of a screenshot), or at the pointer without them. --button right|middle, --count 2|3 for a double or triple click (left button), --mods holds modifier keys (e.g. shift, ctrl+shift).',
+        positionals: [REF, { name: 'x' }, { name: 'y' }],
+        options: {
+            button: { type: 'string', value: '<left|right|middle>', description: 'Mouse button (default left).' },
+            count: { type: 'string', value: '<1|2|3>', description: 'Clicks: 2 is a double click, 3 a triple click (left button; default 1).' },
+            mods: { type: 'string', value: '<keys>', description: 'Modifier keys held during the click, e.g. shift or ctrl+shift.' },
+            ...COMPUTER_LOOK,
+        },
+        examples: ['shard ws computer click acme/demo 640 400 --screenshot after.png', 'shard ws computer click acme/demo 200 120 --count 2'],
+    },
+    {
+        path: ['workspaces', 'computer', 'type'],
+        summary: 'Type text on the workspace desktop (0.10.0+)',
+        description: 'Types into the focused window, Unicode included (up to 20,000 characters); - reads the text from standard input. A newline presses Return.',
+        positionals: [REF, { name: 'text|-', required: true }],
+        options: { ...COMPUTER_LOOK },
+        examples: ['shard ws computer type acme/demo "hello world"', 'cat notes.txt | shard ws computer type acme/demo -'],
+    },
+    {
+        path: ['workspaces', 'computer', 'key'],
+        summary: 'Press keys on the workspace desktop (0.10.0+)',
+        description: 'One key or combination, or several separated by spaces: Return, Escape, ctrl+s, alt+Tab, ctrl+shift+t, F5, Page_Down.',
+        positionals: [REF, { name: 'keys', required: true }],
+        options: {
+            repeat: { type: 'string', value: '<n>', description: 'Press it n times (1-100).' },
+            ...COMPUTER_LOOK,
+        },
+        examples: ['shard ws computer key acme/demo ctrl+l', 'shard ws computer key acme/demo Tab --repeat 3 --screenshot form.png'],
+    },
+    {
+        path: ['workspaces', 'computer', 'scroll'],
+        summary: 'Scroll on the workspace desktop (0.10.0+)',
+        description: 'Scrolls up, down, left or right by --amount wheel clicks (default 3), at <x> <y> or at the pointer.',
+        positionals: [REF, { name: 'up|down|left|right', required: true }, { name: 'x' }, { name: 'y' }],
+        options: {
+            amount: { type: 'string', value: '<n>', description: 'Wheel clicks (1-100, default 3).' },
+            mods: { type: 'string', value: '<keys>', description: 'Modifier keys held while scrolling, e.g. shift.' },
+            ...COMPUTER_LOOK,
+        },
+        examples: ['shard ws computer scroll acme/demo down 640 400 --amount 5'],
+    },
+    {
+        path: ['workspaces', 'computer', 'move'],
+        summary: 'Move the pointer on the workspace desktop (0.10.0+)',
+        positionals: [REF, { name: 'x', required: true }, { name: 'y', required: true }],
+        options: { ...COMPUTER_LOOK },
+    },
+    {
+        path: ['workspaces', 'computer', 'drag'],
+        summary: 'Drag with the left button on the workspace desktop (0.10.0+)',
+        description: 'Presses at <x1> <y1>, moves to <x2> <y2> and releases.',
+        positionals: [REF, { name: 'x1', required: true }, { name: 'y1', required: true }, { name: 'x2', required: true }, { name: 'y2', required: true }],
+        options: {
+            mods: { type: 'string', value: '<keys>', description: 'Modifier keys held during the drag, e.g. alt.' },
+            ...COMPUTER_LOOK,
+        },
+        examples: ['shard ws computer drag acme/demo 100 200 500 200'],
+    },
+    {
+        path: ['workspaces', 'computer', 'mouse-down'],
+        summary: 'Press the left mouse button and keep it down (0.10.0+)',
+        description: 'At the pointer (shard ws computer move first); shard ws computer mouse-up releases it.',
+        positionals: [REF],
+        options: { ...COMPUTER_LOOK },
+    },
+    {
+        path: ['workspaces', 'computer', 'mouse-up'],
+        summary: 'Release the left mouse button (0.10.0+)',
+        positionals: [REF],
+        options: { ...COMPUTER_LOOK },
+    },
+    {
+        path: ['workspaces', 'computer', 'hold-key'],
+        summary: 'Hold keys down for some seconds on the workspace desktop (0.10.0+)',
+        positionals: [REF, { name: 'keys', required: true }, { name: 'seconds', required: true }],
+        options: { ...COMPUTER_LOOK },
+        examples: ['shard ws computer hold-key acme/demo shift 2'],
+    },
+    {
+        path: ['workspaces', 'computer', 'zoom'],
+        summary: 'Save an enlarged view of part of the workspace desktop (0.10.0+)',
+        description: 'The region <x0> <y0> <x1> <y1> (screen pixels, x0 < x1, y0 < y1), scaled up to the screen width. --json prints {out, format, width, height, bytes}.',
+        positionals: [REF, { name: 'x0', required: true }, { name: 'y0', required: true }, { name: 'x1', required: true }, { name: 'y1', required: true }],
+        options: {
+            out: { type: 'string', value: '<file>', description: 'Where to write the image (default zoom.png).' },
+            format: { type: 'string', value: '<png|jpeg>', description: 'Image format (default png).' },
+            quality: { type: 'string', value: '<1-100>', description: 'JPEG quality (default 80).' },
+        },
+        examples: ['shard ws computer zoom acme/demo 0 0 640 200 --out toolbar.png'],
+    },
+    {
+        path: ['workspaces', 'computer', 'cursor'],
+        summary: 'Print where the pointer is on the workspace desktop (0.10.0+)',
+        positionals: [REF],
+        options: {},
+    },
+    {
+        path: ['workspaces', 'computer', 'wait'],
+        summary: 'Wait on the workspace desktop, then optionally take a screenshot (0.10.0+)',
+        description: 'For a page or program that is still loading: shard ws computer wait <ws> 2 --screenshot after.png.',
+        positionals: [REF, { name: 'seconds', required: true }],
+        options: { ...COMPUTER_LOOK },
+    },
+    {
+        path: ['workspaces', 'computer', 'start'],
+        summary: 'Start the workspace desktop (0.10.0+)',
+        description: 'A no-op while it runs. The size applies to a start: 640x480 to 2560x1600 (default 1280x800).',
+        positionals: [REF],
+        options: {
+            width: { type: 'string', value: '<px>', description: 'Screen width (640-2560).' },
+            height: { type: 'string', value: '<px>', description: 'Screen height (480-1600).' },
+        },
+    },
+    { path: ['workspaces', 'computer', 'stop'], summary: 'Stop the workspace desktop; its windows close (0.10.0+)', positionals: [REF], options: {} },
+    {
+        path: ['workspaces', 'computer', 'stream'],
+        summary: 'Print a private link to watch the workspace desktop live (0.10.0+)',
+        description: 'Starts the viewer in the workspace, exposes its port and signs a link to it (inbound ports). View only unless --interactive. Anyone with the link can open it until it expires: share it like a password. --stop ends every view instead. --json prints {url, expires_at, port, interactive}.',
+        positionals: [REF],
+        options: {
+            interactive: { type: 'boolean', description: 'Let the viewer use the mouse and keyboard.' },
+            ttl: { type: 'string', value: '<duration>', description: 'Lifetime of the link, 1m to 7d (default 24h).' },
+            stop: { type: 'boolean', description: 'End every view and close the viewer ports.' },
+        },
+        examples: ['open "$(shard ws computer stream acme/demo)"', 'shard ws computer stream acme/demo --stop'],
+    },
+    {
+        path: ['workspaces', 'computer', 'enable'],
+        summary: 'Switch computer use on for a workspace (0.10.0+)',
+        description: 'Tool tokens then carry the computer tool; the platform starts the desktop on the first computer call. --json prints {enabled, workspace, template, available}.',
+        positionals: [REF],
+        options: {},
+    },
+    { path: ['workspaces', 'computer', 'disable'], summary: 'Switch computer use off for a workspace (0.10.0+)', positionals: [REF], options: {} },
+    {
+        path: ['workspaces', 'computer', 'inherit'],
+        summary: 'Let a workspace follow its template’s computer use switch (0.10.0+)',
+        positionals: [REF],
+        options: {},
+    },
+    {
+        path: ['templates', 'computer-use'],
+        summary: 'Switch computer use on or off for every workspace of one of your templates (0.10.0+)',
+        description: 'A workspace may override it (shard ws computer enable|disable). Platform templates keep it off: switch a workspace on instead.',
+        positionals: [SLUG, { name: 'on|off', required: true }],
+        options: {},
+        examples: ['shard templates computer-use my-desktop-agent on'],
+    },
     {
         path: ['files', 'read'],
         summary: 'Print (or save) a file from a workspace',
@@ -785,6 +1063,7 @@ const GROUPS = {
     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',
+    'workspaces port': 'Serve ports of a workspace at private HTTPS URLs: expose, list, close, tokens, browser links and callback URLs (0.9.0+)',
     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)',
@@ -811,12 +1090,15 @@ const ALIASES = {
     invite: 'invitations',
     invites: 'invitations',
     volume: 'volumes',
+    ports: 'port',
 };
 /** 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. */
+/** Top-level shortcuts for a whole command path (0.10.0+): `shard exec` is `shard workspaces exec`. */
+const SHORTCUTS = { exec: ['workspaces', 'exec'] };
 export function normalizeWords(words) {
-    const w = words.map((x) => ALIASES[x] ?? x);
+    const w = words.flatMap((x, i) => (i === 0 ? SHORTCUTS[x] : undefined) ?? [ALIASES[x] ?? x]);
     if (w[0] === 'workspaces' && w[1] !== undefined && FOLDED.has(w[1]))
         return w.slice(1);
     return w;
@@ -1111,7 +1393,7 @@ export const EXIT_CODE_HELP = [
 ];
 /** 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: 'Account (a user session: shard signup or shard auth login)', groups: ['signup', 'verify', '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'] },

package/dist/commands.d.ts

@@ -96,9 +96,23 @@ export declare function principal(ctx: Ctx): Promise<{
         id: string;
         key_id: string;
     };
-    tool_permissions: ("git" | "exec" | "files" | "pty" | "process" | "browser")[];
+    tool_permissions: ("git" | "exec" | "files" | "pty" | "process" | "browser" | "computer")[];
 }>;
 /** The exit code `shard exec` returns for a finished command. */
 export declare function execExitCode(r: Pick<RunResult, 'exitCode' | 'termSignal' | 'timedOut'>): number;
+/**
+ * A lifecycle call a file-first workspace does not have (suspend, resume, fork, reset,
+ * save-as-template), refused before any request as the SDK's workspace handle does: NotSupportedForModeError, printed
+ * with its hint like the API's own refusal.
+ */
+/** `<port>` of the port commands: a TCP port number, 1-65535. */
+export declare function portArg(text: string): number;
+/** `--ttl <duration>` of port tokens and links: whole seconds within the API's bounds (undefined: the API's default). */
+export declare function ttlSeconds(values: Values, b: {
+    option: string;
+    min: number;
+    max: number;
+    range: string;
+}): number | undefined;
 /** The project-key commands; handlers.ts adds the account plane's. */
 export declare const KEY_HANDLERS: Record<string, Handler>;