@shardflux/cli 0.9.0 → 0.10.0

package/CHANGELOG.md

@@ -1,12 +1,39 @@
 # Changelog
 
+Every command and option the README shows is available from the version named here. Breaking changes ship in minor
+releases and are marked **Breaking**.
+
+## 0.10.0 (not yet published)
+
+Needs `@shardflux/sdk` 0.15.0 or later.
+
+### One command per workspace
+
+Additive (contracts §46), with `@shardflux/sdk` 0.15.0.
+
+- `shard exec <key> --template <slug> -- <cmd>`: `--template` on `ws exec` and `ws exec-start` opens the key first,
+  so the workspace is created on first use (stderr: `created workspace <key> (template <slug>)`) and resumed if it is
+  suspended. Without `--template` the key must have a workspace, as before.
+- `shard exec` is a shortcut for `shard workspaces exec`.
+- `--template default` opens the platform default template (`python-node-browser`).
+
+### Computer use
+
+- `shard ws computer status|screenshot|act|start|stop|stream <key>`: the workspace desktop (contracts §45).
+  `screenshot --out F` writes the image; `act <json|->` runs a batch of computer toolset actions, prints one line per
+  action and exits 1 when one failed (`--screenshot F` saves the screen after it; `--json` prints the full result);
+  `stream [--interactive] [--ttl D]` prints a private link to watch it, `stream --stop` ends every view.
+- One command per mouse and keyboard action: `shard ws computer click [x y] [--button] [--count 2|3] [--mods]`,
+  `type <text|->`, `key <keys> [--repeat]`, `scroll <dir> [x y] [--amount]`, `move`, `drag`, `mouse-down`, `mouse-up`,
+  `hold-key`, `zoom <x0 y0 x1 y1> [--out F]`, `cursor`, `wait`. Every input command and `act` take `--screenshot F`,
+  `--settle MS` and `--format jpeg --quality N`; `screenshot` takes `--quality`.
+- `shard ws computer enable|disable|inherit <key>` and `shard ws open --computer-use on|off|inherit`: the workspace's
+  computer use switch; `shard templates computer-use <slug> on|off`: the switch for every workspace of a template.
+
 ## 0.9.0 — 2026-10-04 (not yet published)
 
 - `shard ws hint <workspace>` explicitly stages a parked workspace ahead of a VM tool call, without waiting for restore or resuming a suspended workspace.
 
-Every command and option the README shows is available from the version named here. Breaking changes ship in minor
-releases and are marked **Breaking**.
-
 ## 0.9.0 (not yet published)
 
 Needs `@shardflux/sdk` 0.14.0 or later.

package/README.md

@@ -42,8 +42,7 @@ password. With the Codex CLI signed in with ChatGPT on this machine, your email
 
 ```sh
 shard signup                                  # or: shard signup --email you@example.com
-shard workspaces open acme/demo --template python-node-browser
-shard ws exec acme/demo -- python3 -c 'print(40 + 2)'
+shard exec acme/demo --template default -- python3 -c 'print(40 + 2)'   # created on first use
 shard files write acme/demo /home/user/notes.txt --from notes.txt
 shard files read acme/demo /home/user/notes.txt
 shard ws suspend acme/demo --wait
@@ -116,8 +115,9 @@ terminal, `--json` on every command, secrets only on standard input, and documen
 2. **Verify the email** (an `--email` signup, to start the trial): `shard verify --json` emails a
    6-digit code; ask the person for it, then `shard verify <code>`. Nothing is signed out.
 3. **Set up again any time:** `shard setup --json` is idempotent.
-4. **Work:** `shard ws open <key> --template <slug> --json`, `shard ws exec <key> -- <cmd>`,
-   `shard files ...` use the saved key.
+4. **Work:** `shard exec <key> --template default -- <cmd>` creates the workspace on first use and runs the command
+   (0.10.0+); later commands reuse it. `shard ws open <key> --template <slug> --json`, `shard files ...` use the saved
+   key too.
 5. **A paid plan:** `shard billing plans`, then `shard billing upgrade <plan> --json` prints the Stripe
    Checkout URL; give it to the person, then `shard billing upgrade <plan> --wait` (or
    `shard billing status`) until it is active. The API activates a plan only when Stripe confirms the
@@ -385,8 +385,8 @@ shows the status; `shard version --check` asks now (`--json`: `{"cli", "sdk", "u
 | `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. A file-first workspace's state reads `running (file-first)` (0.5.0+). |
 | `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. Its mode, and a file-first workspace's tree revision (0.5.0+). Its memory (0.8.0+): `fixed 4096 MiB`, or `elastic: promised …, held …, plugged +… MiB`. The template version whose [immutable paths](#immutable-paths-080) it has mounted (0.8.0+): `immutable paths  v3 (mounted read-only)`. |
 | `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\|-] [-v] [--execution-id ID] [--output-limit N] [--resource-hint auto\|light\|heavy] [--burst [--burst-vcpus N] [--burst-memory MIB]] -- <cmd> [args...]` | Runs argv with no shell. Output is streamed (in the start request itself, 0.8.0+) and resumes from byte offsets after dropped connections. `shard` exits with the command's exit code. Ctrl-C cancels the command. `-v` (0.5.0+) then prints the session id and exit status on stderr, and the memory grow the command waited for on an elastic workspace (0.8.0+; `--json`: `memory_grow`). `--cwd` is an absolute path (default `/home/user`); a relative one is refused (`invalid_cwd`, exit 2). A command that could not start (a `--cwd` that is not a directory, a program not on `PATH`) exits 6 with the workspace's reason and a hint (0.5.1+; before, it exited 1 with no output). On a file-first workspace (0.5.0+) the command runs as an execution instead: see [File-first workspaces](#file-first-workspaces). `--burst` (0.8.0+): [burst execution](#burst-execution-080). `--resource-hint` (0.9.0+): [elastic memory](#elastic-memory-080). |
-| `workspaces exec-start <id\|key> [--session-id ID] [--cwd D] [--timeout T] [--stdin-open] [--resource-hint auto\|light\|heavy] -- <cmd> [args...]`, `workspaces exec-read <id\|key> <session-id> [--follow]`, `workspaces exec-cancel <id\|key> <session-id> [--grace D]` | Background commands (0.8.0+): start a command and return at once, read its output and state (`--follow` streams it to its exit and exits with its code; while it runs `exec-read` exits 5), stop it. See [Background commands](#background-commands-080). |
+| `workspaces exec <id\|key> [--template S] [--cwd D] [--env K=V]... [--timeout T] [--stdin F\|-] [-v] [--execution-id ID] [--output-limit N] [--resource-hint auto\|light\|heavy] [--burst [--burst-vcpus N] [--burst-memory MIB]] -- <cmd> [args...]` | Runs argv with no shell. `shard exec` is the same command (0.10.0+). `--template <slug>` (0.10.0+) opens the key first: the workspace is created on first use (stderr says so) and resumed if suspended; without it the key must have a workspace. Output is streamed (in the start request itself, 0.8.0+) and resumes from byte offsets after dropped connections. `shard` exits with the command's exit code. Ctrl-C cancels the command. `-v` (0.5.0+) then prints the session id and exit status on stderr, and the memory grow the command waited for on an elastic workspace (0.8.0+; `--json`: `memory_grow`). `--cwd` is an absolute path (default `/home/user`); a relative one is refused (`invalid_cwd`, exit 2). A command that could not start (a `--cwd` that is not a directory, a program not on `PATH`) exits 6 with the workspace's reason and a hint (0.5.1+; before, it exited 1 with no output). On a file-first workspace (0.5.0+) the command runs as an execution instead: see [File-first workspaces](#file-first-workspaces). `--burst` (0.8.0+): [burst execution](#burst-execution-080). `--resource-hint` (0.9.0+): [elastic memory](#elastic-memory-080). |
+| `workspaces exec-start <id\|key> [--template S] [--session-id ID] [--cwd D] [--timeout T] [--stdin-open] [--resource-hint auto\|light\|heavy] -- <cmd> [args...]`, `workspaces exec-read <id\|key> <session-id> [--follow]`, `workspaces exec-cancel <id\|key> <session-id> [--grace D]` | Background commands (0.8.0+): start a command and return at once, read its output and state (`--follow` streams it to its exit and exits with its code; while it runs `exec-read` exits 5), stop it. See [Background commands](#background-commands-080). |
 | `executions get <id\|key> <execution-id> [--wait D]` | The result of a file-first workspace's execution (0.5.0+): its output, then what ran. Exits with the command's code, 6 if the execution failed or was lost, 5 while it still runs. |
 | `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] [--if-revision N]` | Atomic write. The default source is stdin. `--if-revision` (0.5.0+): file-first workspaces only, see [Tree revisions](#tree-revisions). |
@@ -408,6 +408,7 @@ shows the status; `shard version --check` asks now (`--json`: `{"cli", "sdk", "u
 | `workspaces secrets <id\|key> [--set NAME]... [--clear]` | Show the secret names bound to the workspace and their status, or replace them. |
 | `workspaces port expose <id\|key> <port>`, `workspaces port ls <id\|key>`, `workspaces port close <id\|key> <port>` | Serve a port of the workspace at its own private HTTPS URL, list the exposed ports, close one (0.9.0+; see [Inbound ports](#inbound-ports-090)). |
 | `workspaces port token <id\|key> <port> [--ttl D]`, `workspaces port link <id\|key> <port> [--ttl D] [--path P]`, `workspaces port callback <id\|key> <port> [--revoke]` | A port token (printed alone), a link that opens the port in a browser, the port's callback URL for webhooks and OAuth redirects (0.9.0+). |
+| `workspaces computer status\|screenshot\|act\|start\|stop\|stream <id\|key>`, `workspaces computer click\|type\|key\|scroll\|move\|drag\|mouse-down\|mouse-up\|hold-key\|zoom\|cursor\|wait <id\|key> ...`, `workspaces computer enable\|disable\|inherit <id\|key>`, `templates computer-use <slug> on\|off` | The workspace desktop for computer use: its state, a screenshot (`--out F`), one command per mouse and keyboard action, a batch of actions (a JSON array), a private link to watch or use it (`stream [--interactive] [--ttl D]`, `--stop`), and the switch for a workspace or every workspace of a template (0.10.0+; see [Computer use](#computer-use-0100)). |
 | `secrets create <NAME> [--from-file F] [--description T] [--tool T]... [--allow-workspace ID]... [--org ID [--allow-project ID]... [--all-projects]]` | Create a secret. The value comes from standard input or `--from-file`, never from an argument. |
 | `secrets list [--org ID] [--include-deleted] [--all]`, `secrets get <id\|NAME>` | Secret metadata. Values are never shown. |
 | `secrets update <id\|NAME> [--description T] [--tool T]... [--allow-workspace ID]... [--any-workspace] [--allow-project ID]... [--all-projects] [--clear-projects]` | Change the description or usage permissions. |
@@ -751,6 +752,46 @@ shard ws port close acme/demo 3000
   again replaces the URL; `--revoke` removes it.
 - `close` stops the port's tokens, links and callback URL at once.
 
+## Computer use (0.10.0+)
+
+A desktop in the workspace for agents that operate GUI software: a screen, a mouse and a keyboard. Switch it on for a
+workspace (or every workspace of your template); the platform starts the desktop on the first computer command.
+
+```sh
+shard ws open acme/demo --template python-node-browser --computer-use on
+shard ws exec-start acme/demo -- chromium https://example.com     # opens on the desktop
+shard ws computer screenshot acme/demo --out desktop.png
+shard ws computer click acme/demo 640 400
+shard ws computer type acme/demo "hello" --screenshot after.png
+shard ws computer key acme/demo ctrl+s
+open "$(shard ws computer stream acme/demo)"                      # watch it live
+```
+
+| Command | Action |
+| --- | --- |
+| `click <ws> [x y] [--button left\|right\|middle] [--count 2\|3] [--mods keys]` | A click, double or triple click at a point or at the pointer |
+| `type <ws> <text\|->` | Types text (Unicode; `-` reads standard input) |
+| `key <ws> <keys> [--repeat n]` | Keys and combinations: `Return`, `ctrl+s`, `alt+Tab`, several separated by spaces |
+| `scroll <ws> up\|down\|left\|right [x y] [--amount n] [--mods keys]` | Wheel clicks (default 3) |
+| `move <ws> <x> <y>`, `drag <ws> <x1> <y1> <x2> <y2>` | Moves the pointer; drags with the left button |
+| `mouse-down <ws>`, `mouse-up <ws>`, `hold-key <ws> <keys> <seconds>` | Holds the left button or keys |
+| `zoom <ws> <x0> <y0> <x1> <y1> [--out F]` | Saves an enlarged view of a region |
+| `cursor <ws>`, `wait <ws> <seconds>` | Prints the pointer position; waits |
+| `act <ws> <json\|->` | Any of these in one batch: a JSON array of actions |
+
+Every input command takes `--screenshot F` (a screenshot after it, written to `F`), `--settle MS` (the wait before
+that screenshot, default 250) and `--format jpeg --quality N` for smaller images; `screenshot` and `zoom` take
+`--format` and `--quality` too.
+
+- The actions are Claude's computer toolset members with their parameters (`screenshot`, `zoom`, `left_click`,
+  `right_click`, `middle_click`, `double_click`, `triple_click`, `left_click_drag`, `mouse_move`, `left_mouse_down`,
+  `left_mouse_up`, `cursor_position`, `scroll`, `type`, `key`, `hold_key`, `wait`). Each command above and `act` print
+  one line per action and exit 1 when one failed (in a batch the rest are skipped).
+- `stream` prints a link to the viewer (view only unless `--interactive`; `--ttl` 1m to 7d, default 24h); anyone with
+  it can watch until it expires. `stream --stop` ends every view.
+- `ws computer enable|disable|inherit` sets the workspace's own switch (`inherit` follows the template);
+  `templates computer-use <slug> on|off` sets it for every workspace of one of your templates.
+
 ## Start deadlines
 
 A queued open, resume or fork (`capacity_pending`) has a deadline 15 minutes after it was created.

package/dist/args.d.ts

@@ -1,4 +1,4 @@
-export declare const CLI_VERSION = "0.9.0";
+export declare const CLI_VERSION = "0.10.0";
 export interface OptionSpec {
     type: 'string' | 'boolean';
     short?: string;
@@ -29,7 +29,6 @@ export interface CommandSpec {
 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|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. */

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.9.0';
+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).' },
@@ -64,6 +64,13 @@ 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.' },
@@ -218,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,
@@ -265,6 +277,11 @@ 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.' },
@@ -305,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).' },
@@ -484,6 +506,188 @@ const KEY_COMMANDS = [
         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',
@@ -891,8 +1095,10 @@ const ALIASES = {
 /** 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;

package/dist/commands.d.ts

@@ -96,7 +96,7 @@ 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;

package/dist/commands.js

@@ -346,6 +346,22 @@ async function waitOperation(ctx, operationId, timeoutMs) {
  * Runs an SDK call that waits itself (a waited open or lifecycle call). Ctrl-C reports the operation it was waiting
  * for, as the SDK observed it; a held open interrupted before the server answered has none yet (`unnamed`).
  */
+/**
+ * The workspace of `ws exec` / `exec-start`: with `--template <slug>` (0.10.0+) the key is opened first (created on first
+ * use, resumed if suspended; stderr says when it was created), else `<id|key>` must name an existing workspace.
+ */
+async function execTarget(ctx, values, ref) {
+    const template = str(values.template);
+    if (template === undefined)
+        return resolveWorkspace(ctx, ref);
+    const ws = await waited(ctx, 'the open continues server side (run the command again to keep waiting).', () => ctx
+        .cloud()
+        .workspace(ref, { template, agentLabel: ctx.agentLabel, wait: { timeoutMs: DEFAULT_WAIT_MS, signal: ctx.signal } })
+        .open());
+    if (ws.created === true && !ctx.json)
+        ctx.io.stderr.write(`created workspace ${ws.key} (template ${template})\n`);
+    return ws;
+}
 async function waited(ctx, unnamed, call) {
     try {
         return await call();
@@ -623,6 +639,71 @@ async function portWorkspace(ctx, ref) {
     requireProcessful(ws, 'inbound_ports', 'Serving a port');
     return ws;
 }
+/** The workspace of a computer command; a file-first workspace has no desktop (refused before any request). */
+/** --format/--quality of a desktop image (0.10.0+). */
+function imageOpts(values) {
+    const format = str(values.format);
+    if (format !== undefined && format !== 'png' && format !== 'jpeg')
+        throw new UsageError(`--format must be png or jpeg (got "${format}")`);
+    const quality = str(values.quality);
+    return { ...(format !== undefined ? { format } : {}), ...(quality !== undefined ? { quality: parsePositiveInt(quality, 'quality', 100) } : {}) };
+}
+/** --screenshot <file>, --settle and the image options: the screenshot after a computer action or batch. */
+function lookOpts(values) {
+    const shotTo = str(values.screenshot);
+    const settle = str(values.settle);
+    if (settle !== undefined && (!/^\d+$/.test(settle.trim()) || Number(settle) > 10_000))
+        throw new UsageError(`--settle must be 0 to 10000 milliseconds (got "${settle}")`);
+    return { shotTo, req: { screenshot: shotTo !== undefined, ...(settle !== undefined ? { settle_ms: Number(settle) } : {}), ...imageOpts(values) } };
+}
+/** A screen coordinate argument (pixels from the top-left). */
+function pixel(text, name) {
+    if (!/^\d+$/.test(text.trim()))
+        throw new UsageError(`<${name}> must be a whole number of pixels (got "${text}")`);
+    return Number(text);
+}
+/** <x> <y> as a coordinate; neither means at the pointer. */
+function pointAt(x, y) {
+    if (x === undefined)
+        return {};
+    if (y === undefined)
+        throw new UsageError('pass both <x> and <y>, or neither to act at the pointer');
+    return { coordinate: [pixel(x, 'x'), pixel(y, 'y')] };
+}
+const modsOf = (values) => (str(values.mods) !== undefined ? { text: str(values.mods) } : {});
+function secondsOf(text, name) {
+    if (!/^\d+(\.\d+)?$/.test(text.trim()) || Number(text) > 300)
+        throw new UsageError(`${name} must be 0 to 300 seconds (got "${text}")`);
+    return Number(text);
+}
+/** Runs computer actions as one batch and prints one line per action; exit 1 when one failed. */
+async function runComputer(ctx, ref, actions, look) {
+    const ws = await computerWorkspace(ctx, ref);
+    const r = await cellOf(ctx, ws).computer.act({ actions, ...look.req });
+    if (look.shotTo !== undefined && r.screenshot)
+        await writeFile(look.shotTo, Buffer.from(r.screenshot.data, 'base64'));
+    const lines = r.results.map((x, i) => {
+        const state = x.skipped ? 'skipped' : x.ok ? 'ok' : `failed: ${x.error?.message ?? ''}`;
+        return `${String(i + 1).padStart(3)}  ${x.action.padEnd(16)} ${state}${x.output ? `  ${x.output}` : ''}${x.image ? '  (image)' : ''}  ${x.took_ms} ms`;
+    });
+    const tail = `cursor ${r.cursor[0]},${r.cursor[1]} on a ${r.display.width}x${r.display.height} screen${look.shotTo !== undefined && r.screenshot ? `; screenshot written to ${look.shotTo}` : ''}`;
+    out(ctx, `${lines.join('\n')}${lines.length ? '\n' : ''}${tail}\n`, r);
+    return r.results.every((x) => x.ok) ? 0 : 1;
+}
+async function computerWorkspace(ctx, ref) {
+    const ws = await resolveWorkspace(ctx, ref);
+    requireProcessful(ws, 'computer_use', 'Computer use');
+    return ws;
+}
+async function setComputerUse(ctx, ref, enabled) {
+    const ws = await computerWorkspace(ctx, ref);
+    await ws.setComputerUse(enabled);
+    const cu = ws.computerUse;
+    const why = cu.workspace === null ? `following its template (${cu.template ? 'on' : 'off'})` : 'set on the workspace';
+    const note = !cu.available ? ' Its template version cannot run a desktop.' : '';
+    out(ctx, `Computer use is ${cu.enabled ? 'on' : 'off'} for ${ws.key}, ${why}.${note}\n`, cu);
+    return 0;
+}
 /** A port as the API sends it (`--json`). */
 const portJson = (p) => ({ port: p.port, url: p.url, created_at: p.createdAt, callback: p.callback ? { created_at: p.callback.createdAt } : null });
 function requireProcessful(ws, operation, what) {
@@ -768,7 +849,7 @@ export const KEY_HANDLERS = {
         const timeout = str(values.timeout);
         const timeoutMs = timeout === undefined ? undefined : parseDuration(timeout, 'timeout');
         const resourceHint = oneOf(values, 'resource-hint', RESOURCE_HINTS);
-        const ws = await resolveWorkspace(ctx, ref);
+        const ws = await execTarget(ctx, values, ref);
         const session = await cellOf(ctx, ws).exec.start({ argv, stdin_open: values['stdin-open'] === true,
             ...(resourceHint !== undefined ? { resource_hint: resourceHint } : {}),
             ...(str(values['session-id']) ? { session_id: str(values['session-id']) } : {}), ...(str(values.cwd) ? { cwd: str(values.cwd) } : {}),
@@ -858,6 +939,10 @@ export const KEY_HANDLERS = {
         const bind = secretNames(strs(values.secret), '--secret');
         const lifetime = oneOf(values, 'lifetime', LIFETIMES);
         const mode = modeFlag(values);
+        const cuText = str(values['computer-use']);
+        if (cuText !== undefined && !['on', 'off', 'inherit'].includes(cuText))
+            throw new UsageError(`--computer-use must be on, off or inherit (got "${cuText}")`);
+        const computerUse = cuText === undefined ? undefined : cuText === 'inherit' ? null : cuText === 'on';
         if (mode === 'file_first' && lifetime === 'session')
             throw new UsageError('a file-first workspace is persistent: --lifetime session is for processful workspaces');
         const inputs = await inputsFrom(ctx, values);
@@ -875,6 +960,7 @@ export const KEY_HANDLERS = {
             ...(inputs ? { inputs } : {}),
             ...(lifetime ? { lifetime } : {}),
             ...(mode ? { mode } : {}),
+            ...(computerUse !== undefined ? { computerUse } : {}),
             agentLabel: ctx.agentLabel,
             wait: values.wait === false ? false : { timeoutMs, signal: ctx.signal },
         }));
@@ -947,7 +1033,7 @@ export const KEY_HANDLERS = {
         const burst = burstOptions(values, stdinSource !== undefined);
         const resourceHint = oneOf(values, 'resource-hint', RESOURCE_HINTS);
         const stdin = stdinSource === undefined ? undefined : await readInput(ctx, stdinSource, MAX_STDIN, '--stdin');
-        const ws = await resolveWorkspace(ctx, ref);
+        const ws = await execTarget(ctx, values, ref);
         const cell = cellOf(ctx, ws);
         const cwd = str(values.cwd);
         if (ws.mode === 'file_first') {
@@ -1795,6 +1881,158 @@ export const KEY_HANDLERS = {
         }
         return 0;
     },
+    // ---- computer use (0.10.0; contracts §45) ----
+    async 'workspaces computer status'(ctx, _values, [ref]) {
+        const ws = await computerWorkspace(ctx, ref);
+        const st = await cellOf(ctx, ws).computer.status();
+        const views = [st.streams.view ? 'view only' : null, st.streams.interactive ? 'interactive' : null].filter(Boolean);
+        out(ctx, st.running
+            ? `Desktop of ${ws.key}: running ${st.width}x${st.height} since ${time(st.started_at ?? '')}; viewers: ${views.length ? views.join(', ') : 'none'}.\n`
+            : `Desktop of ${ws.key}: not running (the first computer call starts it).\n`, st);
+        return 0;
+    },
+    async 'workspaces computer screenshot'(ctx, values, [ref]) {
+        const img = imageOpts(values);
+        const dest = str(values.out) ?? (img.format === 'jpeg' ? 'screenshot.jpg' : 'screenshot.png');
+        const ws = await computerWorkspace(ctx, ref);
+        const r = await cellOf(ctx, ws).computer.act({ actions: [], screenshot: true, ...img });
+        if (!r.screenshot)
+            throw new ShardfluxProtocolError('the desktop returned no screenshot', 200, 'cell');
+        const bytes = Buffer.from(r.screenshot.data, 'base64');
+        await writeFile(dest, bytes);
+        out(ctx, `Wrote a ${r.screenshot.width}x${r.screenshot.height} screenshot of ${ws.key} to ${dest}.\n`, {
+            out: dest, format: r.screenshot.format, width: r.screenshot.width, height: r.screenshot.height, bytes: bytes.length,
+        });
+        return 0;
+    },
+    async 'workspaces computer act'(ctx, values, [ref, source]) {
+        const text = source === '-' ? Buffer.from(await readInput(ctx, '-', 1 << 20, 'actions')).toString('utf8') : source;
+        let actions;
+        try {
+            actions = JSON.parse(text);
+        }
+        catch {
+            throw new UsageError('<actions-json> must be a JSON array of actions, e.g. [{"action":"screenshot"}]');
+        }
+        if (!Array.isArray(actions))
+            throw new UsageError('<actions-json> must be a JSON array of actions');
+        return runComputer(ctx, ref, actions, lookOpts(values));
+    },
+    async 'workspaces computer click'(ctx, values, [ref, x, y]) {
+        const button = str(values.button) ?? 'left';
+        if (button !== 'left' && button !== 'right' && button !== 'middle')
+            throw new UsageError(`--button must be left, right or middle (got "${button}")`);
+        const count = str(values.count) !== undefined ? parsePositiveInt(str(values.count), 'count', 3) : 1;
+        if (count > 1 && button !== 'left')
+            throw new UsageError('--count 2 or 3 is a double or triple click of the left button');
+        const action = button === 'right' ? 'right_click' : button === 'middle' ? 'middle_click' : ['left_click', 'double_click', 'triple_click'][count - 1];
+        return runComputer(ctx, ref, [{ action, ...pointAt(x, y), ...modsOf(values) }], lookOpts(values));
+    },
+    async 'workspaces computer type'(ctx, values, [ref, source]) {
+        const text = source === '-' ? Buffer.from(await readInput(ctx, '-', 256 << 10, 'text')).toString('utf8') : source;
+        if (text === '')
+            throw new UsageError('<text> must not be empty');
+        return runComputer(ctx, ref, [{ action: 'type', text }], lookOpts(values));
+    },
+    async 'workspaces computer key'(ctx, values, [ref, keys]) {
+        const repeat = str(values.repeat) !== undefined ? parsePositiveInt(str(values.repeat), 'repeat', 100) : undefined;
+        return runComputer(ctx, ref, [{ action: 'key', text: keys, ...(repeat !== undefined ? { repeat } : {}) }], lookOpts(values));
+    },
+    async 'workspaces computer scroll'(ctx, values, [ref, direction, x, y]) {
+        if (direction !== 'up' && direction !== 'down' && direction !== 'left' && direction !== 'right') {
+            throw new UsageError(`expected up, down, left or right (got "${direction}")`);
+        }
+        const amount = str(values.amount) !== undefined ? parsePositiveInt(str(values.amount), 'amount', 100) : 3;
+        return runComputer(ctx, ref, [{ action: 'scroll', scroll_direction: direction, scroll_amount: amount, ...pointAt(x, y), ...modsOf(values) }], lookOpts(values));
+    },
+    async 'workspaces computer move'(ctx, values, [ref, x, y]) {
+        return runComputer(ctx, ref, [{ action: 'mouse_move', ...pointAt(x, y) }], lookOpts(values));
+    },
+    async 'workspaces computer drag'(ctx, values, [ref, x1, y1, x2, y2]) {
+        const start = pointAt(x1, y1).coordinate;
+        return runComputer(ctx, ref, [{ action: 'left_click_drag', start_coordinate: start, ...pointAt(x2, y2), ...modsOf(values) }], lookOpts(values));
+    },
+    async 'workspaces computer mouse-down'(ctx, values, [ref]) {
+        return runComputer(ctx, ref, [{ action: 'left_mouse_down' }], lookOpts(values));
+    },
+    async 'workspaces computer mouse-up'(ctx, values, [ref]) {
+        return runComputer(ctx, ref, [{ action: 'left_mouse_up' }], lookOpts(values));
+    },
+    async 'workspaces computer hold-key'(ctx, values, [ref, keys, seconds]) {
+        return runComputer(ctx, ref, [{ action: 'hold_key', text: keys, duration: secondsOf(seconds, '<seconds>') }], lookOpts(values));
+    },
+    async 'workspaces computer wait'(ctx, values, [ref, seconds]) {
+        return runComputer(ctx, ref, [{ action: 'wait', duration: secondsOf(seconds, '<seconds>') }], lookOpts(values));
+    },
+    async 'workspaces computer zoom'(ctx, values, [ref, x0, y0, x1, y1]) {
+        const img = imageOpts(values);
+        const region = [pixel(x0, 'x0'), pixel(y0, 'y0'), pixel(x1, 'x1'), pixel(y1, 'y1')];
+        const dest = str(values.out) ?? (img.format === 'jpeg' ? 'zoom.jpg' : 'zoom.png');
+        const ws = await computerWorkspace(ctx, ref);
+        const r = await cellOf(ctx, ws).computer.act({ actions: [{ action: 'zoom', region }], ...img });
+        const res = r.results[0];
+        if (!res?.ok || !res.image) {
+            out(ctx, `zoom failed: ${res?.error?.message ?? 'no image'}\n`, r);
+            return 1;
+        }
+        const bytes = Buffer.from(res.image.data, 'base64');
+        await writeFile(dest, bytes);
+        out(ctx, `Wrote a ${res.image.width}x${res.image.height} view of [${region.join(', ')}] on ${ws.key} to ${dest}.\n`, {
+            out: dest, format: res.image.format, width: res.image.width, height: res.image.height, bytes: bytes.length,
+        });
+        return 0;
+    },
+    async 'workspaces computer cursor'(ctx, _values, [ref]) {
+        const ws = await computerWorkspace(ctx, ref);
+        const r = await cellOf(ctx, ws).computer.act({ actions: [{ action: 'cursor_position' }] });
+        out(ctx, `${r.cursor[0]} ${r.cursor[1]}\n`, { x: r.cursor[0], y: r.cursor[1], display: r.display });
+        return 0;
+    },
+    async 'workspaces computer start'(ctx, values, [ref]) {
+        const width = str(values.width) !== undefined ? parsePositiveInt(str(values.width), '--width') : undefined;
+        const height = str(values.height) !== undefined ? parsePositiveInt(str(values.height), '--height') : undefined;
+        const ws = await computerWorkspace(ctx, ref);
+        const st = await cellOf(ctx, ws).computer.start({ ...(width !== undefined ? { width } : {}), ...(height !== undefined ? { height } : {}) });
+        out(ctx, `Desktop of ${ws.key}: running ${st.width}x${st.height}.\n`, st);
+        return 0;
+    },
+    async 'workspaces computer stop'(ctx, _values, [ref]) {
+        const ws = await computerWorkspace(ctx, ref);
+        await cellOf(ctx, ws).computer.stop();
+        out(ctx, `Stopped the desktop of ${ws.key}.\n`, { workspace_id: ws.id, stopped: true });
+        return 0;
+    },
+    async 'workspaces computer stream'(ctx, values, [ref]) {
+        const ws = await computerWorkspace(ctx, ref);
+        if (values.stop === true) {
+            await ws.computer.stopStream();
+            out(ctx, `Ended every view of the desktop of ${ws.key}.\n`, { workspace_id: ws.id, stopped: true });
+            return 0;
+        }
+        const ttl = ttlSeconds(values, PORT_LINK_TTL);
+        const s = await ws.computer.stream({ interactive: values.interactive === true, ...(ttl !== undefined ? { ttlSeconds: ttl } : {}) });
+        out(ctx, `${s.url}\n`, { url: s.url, expires_at: s.expiresAt, port: s.port, interactive: s.interactive });
+        if (!ctx.json) {
+            ctx.io.stderr.write(`${s.interactive ? 'Uses' : 'Watches'} the desktop of ${ws.key} until ${time(s.expiresAt)}; anyone with the link can open it until then.\n`);
+        }
+        return 0;
+    },
+    async 'workspaces computer enable'(ctx, _values, [ref]) {
+        return setComputerUse(ctx, ref, true);
+    },
+    async 'workspaces computer disable'(ctx, _values, [ref]) {
+        return setComputerUse(ctx, ref, false);
+    },
+    async 'workspaces computer inherit'(ctx, _values, [ref]) {
+        return setComputerUse(ctx, ref, null);
+    },
+    async 'templates computer-use'(ctx, _values, [slug, state]) {
+        if (state !== 'on' && state !== 'off')
+            throw new UsageError(`expected on or off (got "${state}")`);
+        const r = await ctx.cloud().templates.setComputerUse(slug, state === 'on');
+        out(ctx, `Computer use is ${r.enabled ? 'on' : 'off'} for the workspaces of ${slug} (a workspace's own setting wins).\n`, r);
+        return 0;
+    },
     async 'workspaces secrets'(ctx, values, [ref]) {
         const set = secretNames(strs(values.set), '--set');
         const clear = values.clear === true;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shardflux/cli",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "type": "module",
   "description": "shard: the Shardflux command line. Create an account, sign in, set up keys and billing, then open, run commands in, move files to, suspend, resume and fork persistent agent workspaces.",
   "license": "Apache-2.0",
@@ -44,7 +44,7 @@
   },
   "dependencies": {
     "yaml": "2.9.1",
-    "@shardflux/sdk": "^0.14.0"
+    "@shardflux/sdk": "^0.15.0"
   },
   "devDependencies": {
     "@eslint/js": "10.0.1",