@zocomputer/cli 0.2.1 → 0.2.2

package/README.md

@@ -6,6 +6,22 @@ see [runtime requirements](../README.md#set-up).
 
 ## Install or upgrade
 
+The standalone installer is implemented but awaits its first public release.
+Once published, macOS 15+ and Linux glibc 2.35+ users on arm64 or x64 can run:
+
+```sh
+curl -fsSL https://zo.computer/install.sh | sh
+export PATH="$HOME/.local/bin:$PATH"
+zo --version
+```
+
+It includes Node, verifies the archive, and keeps versions under
+`${XDG_DATA_HOME:-$HOME/.local/share}/zo/cli/` with a managed `~/.local/bin/zo`
+symlink. Re-run it to upgrade; `--version`, `--bin-dir`, and `--no-modify-path`
+control pinned installs, command placement and shell setup. Existing sign-ins
+are preserved. The [CLI guide](../../src/hostagent/system_api/docs/guides/cli.md)
+covers supported systems, PATH collisions, rollback and removal.
+
 Install the latest published version from npm:
 
 ```sh

package/dist/generated/commands.js

@@ -1,6 +1,6 @@
 // Generated by scripts/generate-commands.mjs. Do not edit.
 export const commandManifest = {
-    schemaDigest: "sha256:86eea2bc2e1d9b8d45c59a74750d572cc5c40f97b64786b2ef57dee9f77f9114",
+    schemaDigest: "sha256:3ea715bdec97fa1eee17b34583dc048bd5576ca2679b41cbc8f515f56a89e4ee",
     commands: [
         {
             action: "zo.activity.list",
@@ -355,8 +355,8 @@ export const commandManifest = {
             versions: [
                 {
                     version: 1,
-                    description: "Create a managed Postgres database and return it, usually already `available`. The required `idempotency_key` is ignored until central deduplication lands: a retried create can make a second database, so after an uncertain response (lost or timed out), list the workspace's databases before creating again.",
-                    inputJson: '{"additionalProperties":false,"properties":{"tags":{"default":[],"items":{"description":"A tag ID or name; unknown names are created, unknown IDs are refused.","maxLength":256,"minLength":1,"type":"string"},"maxItems":100,"title":"Tags","type":"array"},"workspace_id":{"maxLength":200,"minLength":1,"title":"Workspace Id","type":"string"},"idempotency_key":{"description":"Required but ignored: a retried create can make a second database.","maxLength":255,"minLength":1,"pattern":"^[!-~]{1,255}$","title":"Idempotency Key","type":"string"},"display_name":{"maxLength":120,"minLength":1,"title":"Display Name","type":"string"},"description":{"default":"","description":"What the database holds. Members and their agents choose a database from `zo.database.list` by it.","maxLength":2000,"title":"Description","type":"string"},"engine":{"const":"postgres","default":"postgres","title":"Engine","type":"string"},"postgres":{"additionalProperties":false,"default":{},"properties":{"major_version":{"default":18,"description":"One of the offered major versions. Fixed for the life of the database.","maximum":2147483647,"minimum":1,"title":"Major Version","type":"integer"},"compute":{"additionalProperties":false,"default":{},"properties":{"min_memory_mib":{"default":1024,"description":"The autoscaling floor while the compute is awake, one of the shapes `zo.database.list_configurations` offers. Equal to `max_memory_mib`, it fixes the size. Above 4,096, set `max_memory_mib` too.","maximum":2147483647,"minimum":1,"title":"Min Memory Mib","type":"integer"},"max_memory_mib":{"default":4096,"description":"The autoscaling ceiling, from the same shapes and at least `min_memory_mib`. CPU scales with memory.","maximum":2147483647,"minimum":1,"title":"Max Memory Mib","type":"integer"},"scale_to_zero":{"default":true,"description":"Whether the compute suspends when idle. `false` keeps it running at its minimum or above around the clock, and is billed for it, on plans whose offer includes `false`.","title":"Scale To Zero","type":"boolean"},"idle_timeout_seconds":{"default":300,"description":"Seconds without a call before the compute scales to zero, within the offered bounds. No effect while `scale_to_zero` is `false`.","maximum":2147483647,"minimum":1,"title":"Idle Timeout Seconds","type":"integer"}},"title":"DatabaseComputeInput","type":"object","required":[]}},"title":"DatabasePostgresInput","type":"object","required":[]},"region":{"default":"us","description":"One of the offered regions. Fixed at creation.","pattern":"^[a-z0-9][a-z0-9-]{0,31}$","title":"Region","type":"string"},"visibility":{"default":"workspace","description":"`workspace` (default): every member can see it and use it as their role allows. `protected`: only you, and whoever you share it with; workspace-wide grants don\'t reach it. Fixed at creation.","enum":["workspace","protected"],"title":"Visibility","type":"string"}},"required":["workspace_id","idempotency_key","display_name"],"title":"DatabaseCreateInput","type":"object"}',
+                    description: "Create a managed Postgres database and return it, usually already `available`. A retried create can make a second database, so after an uncertain response (lost or timed out), list the workspace's databases before creating again.",
+                    inputJson: '{"additionalProperties":false,"properties":{"tags":{"default":[],"items":{"description":"A tag ID or name; unknown names are created, unknown IDs are refused.","maxLength":256,"minLength":1,"type":"string"},"maxItems":100,"title":"Tags","type":"array"},"workspace_id":{"maxLength":200,"minLength":1,"title":"Workspace Id","type":"string"},"idempotency_key":{"anyOf":[{"maxLength":255,"minLength":1,"pattern":"^[!-~]{1,255}$","type":"string"},{"type":"null"}],"default":null,"deprecated":true,"description":"Ignored compatibility field. Omit it; supplying a key does not deduplicate this operation.","title":"Idempotency Key"},"display_name":{"maxLength":120,"minLength":1,"title":"Display Name","type":"string"},"description":{"default":"","description":"What the database holds. Members and their agents choose a database from `zo.database.list` by it.","maxLength":2000,"title":"Description","type":"string"},"engine":{"const":"postgres","default":"postgres","title":"Engine","type":"string"},"postgres":{"additionalProperties":false,"default":{},"properties":{"major_version":{"default":18,"description":"One of the offered major versions. Fixed for the life of the database.","maximum":2147483647,"minimum":1,"title":"Major Version","type":"integer"},"compute":{"additionalProperties":false,"default":{},"properties":{"min_memory_mib":{"default":1024,"description":"The autoscaling floor while the compute is awake, one of the shapes `zo.database.list_configurations` offers. Equal to `max_memory_mib`, it fixes the size. Above 4,096, set `max_memory_mib` too.","maximum":2147483647,"minimum":1,"title":"Min Memory Mib","type":"integer"},"max_memory_mib":{"default":4096,"description":"The autoscaling ceiling, from the same shapes and at least `min_memory_mib`. CPU scales with memory.","maximum":2147483647,"minimum":1,"title":"Max Memory Mib","type":"integer"},"scale_to_zero":{"default":true,"description":"Whether the compute suspends when idle. `false` keeps it running at its minimum or above around the clock, and is billed for it, on plans whose offer includes `false`.","title":"Scale To Zero","type":"boolean"},"idle_timeout_seconds":{"default":300,"description":"Seconds without a call before the compute scales to zero, within the offered bounds. No effect while `scale_to_zero` is `false`.","maximum":2147483647,"minimum":1,"title":"Idle Timeout Seconds","type":"integer"}},"title":"DatabaseComputeInput","type":"object","required":[]}},"title":"DatabasePostgresInput","type":"object","required":[]},"region":{"default":"us","description":"One of the offered regions. Fixed at creation.","pattern":"^[a-z0-9][a-z0-9-]{0,31}$","title":"Region","type":"string"},"visibility":{"default":"workspace","description":"`workspace` (default): every member can see it and use it as their role allows. `protected`: only you, and whoever you share it with; workspace-wide grants don\'t reach it. Fixed at creation.","enum":["workspace","protected"],"title":"Visibility","type":"string"}},"required":["workspace_id","display_name"],"title":"DatabaseCreateInput","type":"object"}',
                     resultKind: "inline",
                 },
             ],
@@ -732,7 +732,7 @@ export const commandManifest = {
                 {
                     version: 1,
                     description: "Create a managed machine from a machine image and return its current view. Describe what this machine is for in the user's terms.",
-                    inputJson: '{"additionalProperties":false,"properties":{"tags":{"default":[],"items":{"description":"A tag ID or name; unknown names are created, unknown IDs are refused.","maxLength":256,"minLength":1,"type":"string"},"maxItems":100,"title":"Tags","type":"array"},"workspace_id":{"title":"Workspace Id","type":"string"},"idempotency_key":{"maxLength":255,"minLength":1,"pattern":"^[!-~]{1,255}$","title":"Idempotency Key","type":"string"},"display_name":{"maxLength":120,"minLength":1,"title":"Display Name","type":"string"},"description":{"default":"","description":"Describe what this machine is for in the user\'s terms.","maxLength":2000,"title":"Description","type":"string"},"source":{"$ref":"#/$defs/MachineSourceInput"},"resources":{"$ref":"#/$defs/MachineResourcesInput"},"lifecycle":{"$ref":"#/$defs/MachineLifecycleInput"},"region":{"default":"us","pattern":"^[a-z0-9][a-z0-9-]{0,31}$","title":"Region","type":"string"},"init":{"default":"none","description":"Which process runs first at boot. `none` (default): nothing; the machine waits for exec. `image`: the init system inside the machine\'s image (systemd, OpenRC) becomes PID 1 and starts the services enabled on its disk. This does not choose the image; `source.machine_image_id` does. Debian and Ubuntu images need `systemd systemd-sysv` installed first. A unit restarts after a crash only when it sets `Restart=`. GPU machines require `none`.","enum":["none","image"],"title":"Init","type":"string"},"command":{"anyOf":[{"items":{"minLength":1,"type":"string"},"maxItems":64,"minItems":1,"type":"array"},{"type":"null"}],"default":null,"description":"Run these arguments as the main process on every boot, without a shell. Use [\\"sh\\", \\"-c\\", ...] for shell syntax. Find ENTRYPOINT and CMD on the image\'s registry page; Zo does not return them. Pass ENTRYPOINT then CMD. With `init: image`, the command must wait for services it needs. The machine stops when it exits; resume runs it again. It may run more than once after a lost create or resume response, so make it safe to rerun. Each argument is at most 4,096 UTF-8 bytes and all arguments total at most 65,536 bytes. A running command is not activity: set `idle_timeout_seconds` at least as long as the job. The maximum is published by `zo.machine.list_configurations`: 3,600 s for CPU machines and 86,400 s for GPU machines. Longer CPU jobs need Zo exec or file calls, or HTTP through a tunnel or connect token. After exit, `get` may show `running` for a few minutes until the stop is recorded. Zo reports no exit reason or code. Write a job\'s result to disk. A resume runs the command again, so to read it, clear the command, resume, then use `zo.machine.read_bytes`. With `init: image` and a command, a missing `/sbin/init` ends the generation as an exit stop, without `incompatible_image`.","title":"Command"},"environment":{"additionalProperties":{"maxLength":4096,"type":"string"},"default":{},"description":"Environment variables set, exactly as written, in the boot process and every command run on the machine. Plain strings, not secrets: they are part of the machine\'s configuration, which anyone who can read the machine sees. Names are upper-case letters, digits and underscores, and reserved names such as `PATH` or ones starting with `ZO_` are refused; at most 64 variables of at most 4096 characters each. A variable here wins over a connection in `credentials` that sets the same name.","maxProperties":64,"title":"Environment","type":"object"},"credentials":{"default":[],"description":"Connection IDs whose credentials the machine receives as environment variables, in the boot process and every command. Each slot of a listed connection sets the variable its definition names, with the variables the slot and the connection declare. The machine also needs a use grant on each connection (`zo.grant.create` with the machine as assignee); a listed connection without one delivers nothing. When two listed connections set the same variable, the later one in the list wins. At most 100 connections, each listed once.","items":{"maxLength":200,"minLength":1,"type":"string"},"maxItems":100,"title":"Credentials","type":"array"},"outbound_network_policies":{"default":[],"description":"Header rules: on HTTPS requests from the machine to a rule\'s hosts, Zo sets a header built from a connection\'s credential, and the credential never enters the machine. A rule names the connection (`credential`) and one of its definition\'s slots (`slot`). With only those two, it uses the hosts, header and format the slot declares in its `injections`. It may give its own `hosts`, `location` and `format`, all three together, only for a slot that declares an `environment_variable`. Formats: `bearer` (`Bearer <value>`), `basic` with a `username` (`Basic` with base64 of `<username>:<value>`) and `raw` (the value as stored). A rule sets its header only while the machine holds a use grant on the connection. Two rules can\'t set the same header on the same host, and all rules together set at most 25 header values. Requests to a host with a rule use HTTP/1.1.","items":{"$ref":"#/$defs/OutboundNetworkPolicy"},"maxItems":25,"title":"Outbound Network Policies","type":"array"},"visibility":{"default":"workspace","description":"`workspace` (default): every member can see and use it. `protected`: only you, and whoever you share it with; workspace-wide grants don\'t reach it. Fixed at creation.","enum":["workspace","protected"],"title":"Visibility","type":"string"}},"required":["workspace_id","idempotency_key","display_name","source","resources","lifecycle"],"title":"MachineCreateInput","type":"object","$defs":{"BasicFormat":{"additionalProperties":false,"properties":{"type":{"const":"basic","description":"`Basic` with base64 of `<username>:<value>`.","title":"Type","type":"string"},"username":{"pattern":"^[^:]{1,256}$","title":"Username","type":"string"}},"required":["type","username"],"title":"BasicFormat","type":"object"},"BearerFormat":{"additionalProperties":false,"properties":{"type":{"const":"bearer","description":"`Bearer <value>`.","title":"Type","type":"string"}},"required":["type"],"title":"BearerFormat","type":"object"},"GpuType":{"enum":["T4","L4","A10","L40S","A100","A100-40GB","A100-80GB","RTX-PRO-6000","H100","H100!","H200","B200","B200+","B300"],"type":"string"},"HeaderLocation":{"additionalProperties":false,"properties":{"type":{"const":"header","title":"Type","type":"string"},"name":{"description":"The header to set, such as `Authorization` or `X-API-Key`.","pattern":"^[A-Za-z0-9!#$%&\'*+.^_`|~-]{1,128}$","title":"Name","type":"string"}},"required":["type","name"],"title":"HeaderLocation","type":"object"},"MachineGpu":{"additionalProperties":false,"properties":{"type":{"$ref":"#/$defs/GpuType"},"count":{"maximum":8,"minimum":1,"title":"Count","type":"integer"}},"required":["type","count"],"title":"MachineGpu","type":"object"},"MachineLifecycleInput":{"additionalProperties":false,"properties":{"idle_timeout_seconds":{"anyOf":[{"maximum":86400,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Omit for 900 seconds on CPU. For GPU, the default is the smaller of 300 seconds and max_run_seconds. An explicit GPU idle timeout must not exceed max_run_seconds.","title":"Idle Timeout Seconds"},"max_run_seconds":{"maximum":86400,"minimum":1,"title":"Max Run Seconds","type":"integer"}},"required":["max_run_seconds"],"title":"MachineLifecycleInput","type":"object"},"MachineResourcesInput":{"additionalProperties":false,"properties":{"vcpus":{"description":"Whole vCPUs of CPU capacity; each is half a Modal physical core. A quarter is reserved; the full allocation can burst when capacity allows. Guest logical CPU count is separate.","maximum":2147483647,"minimum":1,"title":"Vcpus","type":"integer"},"memory_mib":{"maximum":2147483647,"minimum":1,"title":"Memory Mib","type":"integer"},"gpu":{"anyOf":[{"$ref":"#/$defs/MachineGpu"},{"type":"null"}],"default":null}},"required":["vcpus","memory_mib"],"title":"MachineResourcesInput","type":"object"},"MachineSourceInput":{"additionalProperties":false,"properties":{"machine_image_id":{"description":"The machine image to boot (from `zo.machine_image.import`). Separate from `init`, which only chooses what runs first at boot.","minLength":1,"title":"Machine Image Id","type":"string"}},"required":["machine_image_id"],"title":"MachineSourceInput","type":"object"},"OutboundNetworkPolicy":{"additionalProperties":false,"description":"Send one slot\'s credential as a header on HTTPS requests to some hosts.","properties":{"credential":{"description":"The connection ID.","maxLength":200,"minLength":1,"title":"Credential","type":"string"},"slot":{"description":"The connection definition\'s slot, by name.","maxLength":200,"minLength":1,"title":"Slot","type":"string"},"hosts":{"anyOf":[{"items":{"description":"An exact lowercase DNS name, such as `api.openai.com`: no wildcard, port or path.","maxLength":253,"pattern":"^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\\\\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)+$","type":"string"},"maxItems":20,"minItems":1,"type":"array"},{"type":"null"}],"default":null,"title":"Hosts"},"location":{"anyOf":[{"$ref":"#/$defs/HeaderLocation"},{"type":"null"}],"default":null},"format":{"anyOf":[{"discriminator":{"mapping":{"basic":"#/$defs/BasicFormat","bearer":"#/$defs/BearerFormat","raw":"#/$defs/RawFormat"},"propertyName":"type"},"oneOf":[{"$ref":"#/$defs/BearerFormat"},{"$ref":"#/$defs/BasicFormat"},{"$ref":"#/$defs/RawFormat"}]},{"type":"null"}],"default":null,"title":"Format"}},"required":["credential","slot"],"title":"OutboundNetworkPolicy","type":"object"},"RawFormat":{"additionalProperties":false,"properties":{"type":{"const":"raw","description":"The value as it is.","title":"Type","type":"string"}},"required":["type"],"title":"RawFormat","type":"object"}}}',
+                    inputJson: '{"additionalProperties":false,"properties":{"tags":{"default":[],"items":{"description":"A tag ID or name; unknown names are created, unknown IDs are refused.","maxLength":256,"minLength":1,"type":"string"},"maxItems":100,"title":"Tags","type":"array"},"workspace_id":{"title":"Workspace Id","type":"string"},"idempotency_key":{"anyOf":[{"maxLength":255,"minLength":1,"pattern":"^[!-~]{1,255}$","type":"string"},{"type":"null"}],"default":null,"deprecated":true,"description":"Ignored compatibility field. Omit it; supplying a key does not deduplicate this operation.","title":"Idempotency Key"},"display_name":{"maxLength":120,"minLength":1,"title":"Display Name","type":"string"},"description":{"default":"","description":"Describe what this machine is for in the user\'s terms.","maxLength":2000,"title":"Description","type":"string"},"source":{"$ref":"#/$defs/MachineSourceInput"},"resources":{"$ref":"#/$defs/MachineResourcesInput"},"lifecycle":{"$ref":"#/$defs/MachineLifecycleInput"},"region":{"default":"us","pattern":"^[a-z0-9][a-z0-9-]{0,31}$","title":"Region","type":"string"},"init":{"default":"none","description":"Which process runs first at boot. `none` (default): nothing; the machine waits for exec. `image`: the init system inside the machine\'s image (systemd, OpenRC) becomes PID 1 and starts the services enabled on its disk. This does not choose the image; `source.machine_image_id` does. Debian and Ubuntu images need `systemd systemd-sysv` installed first. A unit restarts after a crash only when it sets `Restart=`. GPU machines require `none`.","enum":["none","image"],"title":"Init","type":"string"},"command":{"anyOf":[{"items":{"minLength":1,"type":"string"},"maxItems":64,"minItems":1,"type":"array"},{"type":"null"}],"default":null,"description":"Run these arguments as the main process on every boot, without a shell. Use [\\"sh\\", \\"-c\\", ...] for shell syntax. Find ENTRYPOINT and CMD on the image\'s registry page; Zo does not return them. Pass ENTRYPOINT then CMD. With `init: image`, the command must wait for services it needs. The machine stops when it exits; resume runs it again. It may run more than once after a lost create or resume response, so make it safe to rerun. Each argument is at most 4,096 UTF-8 bytes and all arguments total at most 65,536 bytes. A running command is not activity: set `idle_timeout_seconds` at least as long as the job. The maximum is published by `zo.machine.list_configurations`: 3,600 s for CPU machines and 86,400 s for GPU machines. Longer CPU jobs need Zo exec or file calls, or HTTP through a tunnel or connect token. After exit, `get` may show `running` for a few minutes until the stop is recorded. Zo reports no exit reason or code. Write a job\'s result to disk. A resume runs the command again, so to read it, clear the command, resume, then use `zo.machine.read_bytes`. With `init: image` and a command, a missing `/sbin/init` ends the generation as an exit stop, without `incompatible_image`.","title":"Command"},"environment":{"additionalProperties":{"maxLength":4096,"type":"string"},"default":{},"description":"Environment variables set, exactly as written, in the boot process and every command run on the machine. Plain strings, not secrets: they are part of the machine\'s configuration, which anyone who can read the machine sees. Names are upper-case letters, digits and underscores, and reserved names such as `PATH` or ones starting with `ZO_` are refused; at most 64 variables of at most 4096 characters each. A variable here wins over a connection in `credentials` that sets the same name.","maxProperties":64,"title":"Environment","type":"object"},"credentials":{"default":[],"description":"Connection IDs whose credentials the machine receives as environment variables, in the boot process and every command. Each slot of a listed connection sets the variable its definition names, with the variables the slot and the connection declare. The machine also needs a use grant on each connection (`zo.grant.create` with the machine as assignee); a listed connection without one delivers nothing. When two listed connections set the same variable, the later one in the list wins. At most 100 connections, each listed once.","items":{"maxLength":200,"minLength":1,"type":"string"},"maxItems":100,"title":"Credentials","type":"array"},"outbound_network_policies":{"default":[],"description":"Header rules: on HTTPS requests from the machine to a rule\'s hosts, Zo sets a header built from a connection\'s credential, and the credential never enters the machine. A rule names the connection (`credential`) and one of its definition\'s slots (`slot`). With only those two, it uses the hosts, header and format the slot declares in its `injections`. It may give its own `hosts`, `location` and `format`, all three together, only for a slot that declares an `environment_variable`. Formats: `bearer` (`Bearer <value>`), `basic` with a `username` (`Basic` with base64 of `<username>:<value>`) and `raw` (the value as stored). A rule sets its header only while the machine holds a use grant on the connection. Two rules can\'t set the same header on the same host, and all rules together set at most 25 header values. Requests to a host with a rule use HTTP/1.1.","items":{"$ref":"#/$defs/OutboundNetworkPolicy"},"maxItems":25,"title":"Outbound Network Policies","type":"array"},"visibility":{"default":"workspace","description":"`workspace` (default): every member can see and use it. `protected`: only you, and whoever you share it with; workspace-wide grants don\'t reach it. Fixed at creation.","enum":["workspace","protected"],"title":"Visibility","type":"string"}},"required":["workspace_id","display_name","source","resources","lifecycle"],"title":"MachineCreateInput","type":"object","$defs":{"BasicFormat":{"additionalProperties":false,"properties":{"type":{"const":"basic","description":"`Basic` with base64 of `<username>:<value>`.","title":"Type","type":"string"},"username":{"pattern":"^[^:]{1,256}$","title":"Username","type":"string"}},"required":["type","username"],"title":"BasicFormat","type":"object"},"BearerFormat":{"additionalProperties":false,"properties":{"type":{"const":"bearer","description":"`Bearer <value>`.","title":"Type","type":"string"}},"required":["type"],"title":"BearerFormat","type":"object"},"GpuType":{"enum":["T4","L4","A10","L40S","A100","A100-40GB","A100-80GB","RTX-PRO-6000","H100","H100!","H200","B200","B200+","B300"],"type":"string"},"HeaderLocation":{"additionalProperties":false,"properties":{"type":{"const":"header","title":"Type","type":"string"},"name":{"description":"The header to set, such as `Authorization` or `X-API-Key`.","pattern":"^[A-Za-z0-9!#$%&\'*+.^_`|~-]{1,128}$","title":"Name","type":"string"}},"required":["type","name"],"title":"HeaderLocation","type":"object"},"MachineGpu":{"additionalProperties":false,"properties":{"type":{"$ref":"#/$defs/GpuType"},"count":{"maximum":8,"minimum":1,"title":"Count","type":"integer"}},"required":["type","count"],"title":"MachineGpu","type":"object"},"MachineLifecycleInput":{"additionalProperties":false,"properties":{"idle_timeout_seconds":{"anyOf":[{"maximum":86400,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Omit for 900 seconds on CPU. For GPU, the default is the smaller of 300 seconds and max_run_seconds. An explicit GPU idle timeout must not exceed max_run_seconds.","title":"Idle Timeout Seconds"},"max_run_seconds":{"maximum":86400,"minimum":1,"title":"Max Run Seconds","type":"integer"}},"required":["max_run_seconds"],"title":"MachineLifecycleInput","type":"object"},"MachineResourcesInput":{"additionalProperties":false,"properties":{"vcpus":{"description":"Whole vCPUs of CPU capacity; each is half a Modal physical core. A quarter is reserved; the full allocation can burst when capacity allows. Guest logical CPU count is separate.","maximum":2147483647,"minimum":1,"title":"Vcpus","type":"integer"},"memory_mib":{"maximum":2147483647,"minimum":1,"title":"Memory Mib","type":"integer"},"gpu":{"anyOf":[{"$ref":"#/$defs/MachineGpu"},{"type":"null"}],"default":null}},"required":["vcpus","memory_mib"],"title":"MachineResourcesInput","type":"object"},"MachineSourceInput":{"additionalProperties":false,"properties":{"machine_image_id":{"description":"The machine image to boot (from `zo.machine_image.import`). Separate from `init`, which only chooses what runs first at boot.","minLength":1,"title":"Machine Image Id","type":"string"}},"required":["machine_image_id"],"title":"MachineSourceInput","type":"object"},"OutboundNetworkPolicy":{"additionalProperties":false,"description":"Send one slot\'s credential as a header on HTTPS requests to some hosts.","properties":{"credential":{"description":"The connection ID.","maxLength":200,"minLength":1,"title":"Credential","type":"string"},"slot":{"description":"The connection definition\'s slot, by name.","maxLength":200,"minLength":1,"title":"Slot","type":"string"},"hosts":{"anyOf":[{"items":{"description":"An exact lowercase DNS name, such as `api.openai.com`: no wildcard, port or path.","maxLength":253,"pattern":"^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\\\\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)+$","type":"string"},"maxItems":20,"minItems":1,"type":"array"},{"type":"null"}],"default":null,"title":"Hosts"},"location":{"anyOf":[{"$ref":"#/$defs/HeaderLocation"},{"type":"null"}],"default":null},"format":{"anyOf":[{"discriminator":{"mapping":{"basic":"#/$defs/BasicFormat","bearer":"#/$defs/BearerFormat","raw":"#/$defs/RawFormat"},"propertyName":"type"},"oneOf":[{"$ref":"#/$defs/BearerFormat"},{"$ref":"#/$defs/BasicFormat"},{"$ref":"#/$defs/RawFormat"}]},{"type":"null"}],"default":null,"title":"Format"}},"required":["credential","slot"],"title":"OutboundNetworkPolicy","type":"object"},"RawFormat":{"additionalProperties":false,"properties":{"type":{"const":"raw","description":"The value as it is.","title":"Type","type":"string"}},"required":["type"],"title":"RawFormat","type":"object"}}}',
                     resultKind: "inline",
                 },
             ],
@@ -744,7 +744,7 @@ export const commandManifest = {
                 {
                     version: 1,
                     description: "Destroy a managed machine and return its current view.",
-                    inputJson: '{"additionalProperties":false,"properties":{"machine_id":{"title":"Machine Id","type":"string"},"expected_revision":{"exclusiveMinimum":0,"maximum":9007199254740991,"title":"Expected Revision","type":"integer"},"idempotency_key":{"maxLength":255,"minLength":1,"pattern":"^[!-~]{1,255}$","title":"Idempotency Key","type":"string"}},"required":["machine_id","expected_revision","idempotency_key"],"title":"MachineLifecycleActionInput","type":"object"}',
+                    inputJson: '{"additionalProperties":false,"properties":{"machine_id":{"title":"Machine Id","type":"string"},"expected_revision":{"exclusiveMinimum":0,"maximum":9007199254740991,"title":"Expected Revision","type":"integer"},"idempotency_key":{"anyOf":[{"maxLength":255,"minLength":1,"pattern":"^[!-~]{1,255}$","type":"string"},{"type":"null"}],"default":null,"deprecated":true,"description":"Ignored compatibility field. Omit it; supplying a key does not deduplicate this operation.","title":"Idempotency Key"}},"required":["machine_id","expected_revision"],"title":"MachineLifecycleActionInput","type":"object"}',
                     resultKind: "inline",
                 },
             ],
@@ -830,7 +830,7 @@ export const commandManifest = {
                 {
                     version: 1,
                     description: "Start a stopped managed machine again and return its current view.",
-                    inputJson: '{"additionalProperties":false,"properties":{"machine_id":{"title":"Machine Id","type":"string"},"expected_revision":{"exclusiveMinimum":0,"maximum":9007199254740991,"title":"Expected Revision","type":"integer"},"idempotency_key":{"maxLength":255,"minLength":1,"pattern":"^[!-~]{1,255}$","title":"Idempotency Key","type":"string"},"accept_recovery":{"default":false,"title":"Accept Recovery","type":"boolean"}},"required":["machine_id","expected_revision","idempotency_key"],"title":"MachineResumeInput","type":"object"}',
+                    inputJson: '{"additionalProperties":false,"properties":{"machine_id":{"title":"Machine Id","type":"string"},"expected_revision":{"exclusiveMinimum":0,"maximum":9007199254740991,"title":"Expected Revision","type":"integer"},"idempotency_key":{"anyOf":[{"maxLength":255,"minLength":1,"pattern":"^[!-~]{1,255}$","type":"string"},{"type":"null"}],"default":null,"deprecated":true,"description":"Ignored compatibility field. Omit it; supplying a key does not deduplicate this operation.","title":"Idempotency Key"},"accept_recovery":{"default":false,"title":"Accept Recovery","type":"boolean"}},"required":["machine_id","expected_revision"],"title":"MachineResumeInput","type":"object"}',
                     resultKind: "inline",
                 },
             ],
@@ -854,7 +854,7 @@ export const commandManifest = {
                 {
                     version: 1,
                     description: "Stop a managed machine, keeping its files, and return its current view.",
-                    inputJson: '{"additionalProperties":false,"properties":{"machine_id":{"title":"Machine Id","type":"string"},"expected_revision":{"exclusiveMinimum":0,"maximum":9007199254740991,"title":"Expected Revision","type":"integer"},"idempotency_key":{"maxLength":255,"minLength":1,"pattern":"^[!-~]{1,255}$","title":"Idempotency Key","type":"string"}},"required":["machine_id","expected_revision","idempotency_key"],"title":"MachineLifecycleActionInput","type":"object"}',
+                    inputJson: '{"additionalProperties":false,"properties":{"machine_id":{"title":"Machine Id","type":"string"},"expected_revision":{"exclusiveMinimum":0,"maximum":9007199254740991,"title":"Expected Revision","type":"integer"},"idempotency_key":{"anyOf":[{"maxLength":255,"minLength":1,"pattern":"^[!-~]{1,255}$","type":"string"},{"type":"null"}],"default":null,"deprecated":true,"description":"Ignored compatibility field. Omit it; supplying a key does not deduplicate this operation.","title":"Idempotency Key"}},"required":["machine_id","expected_revision"],"title":"MachineLifecycleActionInput","type":"object"}',
                     resultKind: "inline",
                 },
             ],
@@ -902,7 +902,7 @@ export const commandManifest = {
                 {
                     version: 1,
                     description: "Delete a machine image no machine uses and return the image view.",
-                    inputJson: '{"additionalProperties":false,"properties":{"machine_image_id":{"title":"Machine Image Id","type":"string"},"expected_revision":{"exclusiveMinimum":0,"maximum":9007199254740991,"title":"Expected Revision","type":"integer"},"idempotency_key":{"maxLength":255,"minLength":1,"pattern":"^[!-~]{1,255}$","title":"Idempotency Key","type":"string"}},"required":["machine_image_id","expected_revision","idempotency_key"],"title":"MachineImageDeleteInput","type":"object"}',
+                    inputJson: '{"additionalProperties":false,"properties":{"machine_image_id":{"title":"Machine Image Id","type":"string"},"expected_revision":{"exclusiveMinimum":0,"maximum":9007199254740991,"title":"Expected Revision","type":"integer"},"idempotency_key":{"anyOf":[{"maxLength":255,"minLength":1,"pattern":"^[!-~]{1,255}$","type":"string"},{"type":"null"}],"default":null,"deprecated":true,"description":"Ignored compatibility field. Omit it; supplying a key does not deduplicate this operation.","title":"Idempotency Key"}},"required":["machine_image_id","expected_revision"],"title":"MachineImageDeleteInput","type":"object"}',
                     resultKind: "inline",
                 },
             ],
@@ -926,7 +926,7 @@ export const commandManifest = {
                 {
                     version: 1,
                     description: "Import a registry image, pinned to its manifest digest, and return the image view. Describe what this machine image is for in the user's terms.",
-                    inputJson: '{"additionalProperties":false,"properties":{"display_name":{"maxLength":120,"minLength":1,"title":"Display Name","type":"string"},"description":{"default":"","description":"Describe what this machine image is for in the user\'s terms.","maxLength":2000,"title":"Description","type":"string"},"visibility":{"default":"workspace","description":"`workspace` (default): every member can see and use it. `protected`: only you, and whoever you share it with; workspace-wide grants don\'t reach it. Fixed at creation.","enum":["workspace","protected"],"title":"Visibility","type":"string"},"workspace_id":{"title":"Workspace Id","type":"string"},"idempotency_key":{"maxLength":255,"minLength":1,"pattern":"^[!-~]{1,255}$","title":"Idempotency Key","type":"string"},"source":{"$ref":"#/$defs/RegistrySourceInput"}},"required":["display_name","workspace_id","idempotency_key","source"],"title":"MachineImageImportInput","type":"object","$defs":{"RegistrySourceInput":{"additionalProperties":false,"properties":{"kind":{"const":"registry","title":"Kind","type":"string"},"ref":{"maxLength":1024,"minLength":1,"pattern":"^(?:[a-z0-9]+(?:[._-][a-z0-9]+)*(?::[0-9]{1,5})?/)?[a-z0-9]+(?:(?:[._]|__|-+)[a-z0-9]+)*(?:/[a-z0-9]+(?:(?:[._]|__|-+)[a-z0-9]+)*)*(?::[A-Za-z0-9_][A-Za-z0-9_.-]{0,127})?(?:@sha256:[0-9a-f]{64})?$","title":"Ref","type":"string"},"platform":{"const":"linux/amd64","default":"linux/amd64","title":"Platform","type":"string"}},"required":["kind","ref"],"title":"RegistrySourceInput","type":"object"}}}',
+                    inputJson: '{"additionalProperties":false,"properties":{"display_name":{"maxLength":120,"minLength":1,"title":"Display Name","type":"string"},"description":{"default":"","description":"Describe what this machine image is for in the user\'s terms.","maxLength":2000,"title":"Description","type":"string"},"visibility":{"default":"workspace","description":"`workspace` (default): every member can see and use it. `protected`: only you, and whoever you share it with; workspace-wide grants don\'t reach it. Fixed at creation.","enum":["workspace","protected"],"title":"Visibility","type":"string"},"workspace_id":{"title":"Workspace Id","type":"string"},"idempotency_key":{"anyOf":[{"maxLength":255,"minLength":1,"pattern":"^[!-~]{1,255}$","type":"string"},{"type":"null"}],"default":null,"deprecated":true,"description":"Ignored compatibility field. Omit it; supplying a key does not deduplicate this operation.","title":"Idempotency Key"},"source":{"$ref":"#/$defs/RegistrySourceInput"}},"required":["display_name","workspace_id","source"],"title":"MachineImageImportInput","type":"object","$defs":{"RegistrySourceInput":{"additionalProperties":false,"properties":{"kind":{"const":"registry","title":"Kind","type":"string"},"ref":{"maxLength":1024,"minLength":1,"pattern":"^(?:[a-z0-9]+(?:[._-][a-z0-9]+)*(?::[0-9]{1,5})?/)?[a-z0-9]+(?:(?:[._]|__|-+)[a-z0-9]+)*(?:/[a-z0-9]+(?:(?:[._]|__|-+)[a-z0-9]+)*)*(?::[A-Za-z0-9_][A-Za-z0-9_.-]{0,127})?(?:@sha256:[0-9a-f]{64})?$","title":"Ref","type":"string"},"platform":{"const":"linux/amd64","default":"linux/amd64","title":"Platform","type":"string"}},"required":["kind","ref"],"title":"RegistrySourceInput","type":"object"}}}',
                     resultKind: "inline",
                 },
             ],
@@ -1207,14 +1207,14 @@ export const commandManifest = {
                     version: 1,
                     description: "List subscriptions accessible to the caller in a workspace, optionally for one event definition.",
                     inputJson: '{"additionalProperties":false,"properties":{"workspace_id":{"title":"Workspace Id","type":"string"}},"required":["workspace_id"],"title":"SubscriptionListInput","type":"object"}',
-                    queryJson: '{"type":"object","additionalProperties":false,"properties":{"limit":{"type":"integer","minimum":1,"default":7,"description":"Rows per page, at most 7; a larger value is reduced to it."},"cursor":{"type":"string","minLength":1,"maxLength":5504,"description":"The previous page\'s next_cursor, sent with the same sort, filter and search."},"filter":{"additionalProperties":false,"properties":{"event_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Only subscriptions to this event definition.","title":"Event Id"},"handler":{"anyOf":[{"$ref":"#/$defs/SubscriptionHandlerRef"},{"type":"null"}],"default":null,"description":"Only subscriptions whose handler is this resource: its handler_resource_type and handler_resource_id, such as an Agent."}},"type":"object","required":[],"default":{}}},"required":[],"$defs":{"SubscriptionHandlerRef":{"additionalProperties":false,"properties":{"type":{"enum":["function","workflow","agent"],"title":"Type","type":"string"},"id":{"maxLength":200,"minLength":1,"title":"Id","type":"string"}},"required":["type","id"],"title":"SubscriptionHandlerRef","type":"object"}}}',
+                    queryJson: '{"type":"object","additionalProperties":false,"properties":{"limit":{"type":"integer","minimum":1,"default":100,"description":"Rows per page, at most 100; a larger value is reduced to it."},"cursor":{"type":"string","minLength":1,"maxLength":5504,"description":"The previous page\'s next_cursor, sent with the same sort, filter and search."},"filter":{"additionalProperties":false,"properties":{"event_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Only subscriptions to this event definition.","title":"Event Id"},"handler":{"anyOf":[{"$ref":"#/$defs/SubscriptionHandlerRef"},{"type":"null"}],"default":null,"description":"Only subscriptions whose handler is this resource: its handler_resource_type and handler_resource_id, such as an Agent."}},"type":"object","required":[],"default":{}}},"required":[],"$defs":{"SubscriptionHandlerRef":{"additionalProperties":false,"properties":{"type":{"enum":["function","workflow","agent"],"title":"Type","type":"string"},"id":{"maxLength":200,"minLength":1,"title":"Id","type":"string"}},"required":["type","id"],"title":"SubscriptionHandlerRef","type":"object"}}}',
                     resultKind: "inline",
                 },
                 {
                     version: 2,
                     description: "List subscriptions accessible to the caller in a workspace, optionally for one event definition.",
                     inputJson: '{"additionalProperties":false,"properties":{"workspace_id":{"title":"Workspace Id","type":"string"}},"required":["workspace_id"],"title":"SubscriptionListInput","type":"object"}',
-                    queryJson: '{"type":"object","additionalProperties":false,"properties":{"limit":{"type":"integer","minimum":1,"default":7,"description":"Rows per page, at most 7; a larger value is reduced to it."},"cursor":{"type":"string","minLength":1,"maxLength":5504,"description":"The previous page\'s next_cursor, sent with the same sort, filter and search."},"filter":{"additionalProperties":false,"properties":{"event_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Only subscriptions to this event definition.","title":"Event Id"},"handler":{"anyOf":[{"$ref":"#/$defs/SubscriptionHandlerRef"},{"type":"null"}],"default":null,"description":"Only subscriptions whose handler is this resource: its handler_resource_type and handler_resource_id, such as an Agent."}},"type":"object","required":[],"default":{}}},"required":[],"$defs":{"SubscriptionHandlerRef":{"additionalProperties":false,"properties":{"type":{"enum":["function","workflow","agent"],"title":"Type","type":"string"},"id":{"maxLength":200,"minLength":1,"title":"Id","type":"string"}},"required":["type","id"],"title":"SubscriptionHandlerRef","type":"object"}}}',
+                    queryJson: '{"type":"object","additionalProperties":false,"properties":{"limit":{"type":"integer","minimum":1,"default":100,"description":"Rows per page, at most 100; a larger value is reduced to it."},"cursor":{"type":"string","minLength":1,"maxLength":5504,"description":"The previous page\'s next_cursor, sent with the same sort, filter and search."},"filter":{"additionalProperties":false,"properties":{"event_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Only subscriptions to this event definition.","title":"Event Id"},"handler":{"anyOf":[{"$ref":"#/$defs/SubscriptionHandlerRef"},{"type":"null"}],"default":null,"description":"Only subscriptions whose handler is this resource: its handler_resource_type and handler_resource_id, such as an Agent."}},"type":"object","required":[],"default":{}}},"required":[],"$defs":{"SubscriptionHandlerRef":{"additionalProperties":false,"properties":{"type":{"enum":["function","workflow","agent"],"title":"Type","type":"string"},"id":{"maxLength":200,"minLength":1,"title":"Id","type":"string"}},"required":["type","id"],"title":"SubscriptionHandlerRef","type":"object"}}}',
                     resultKind: "inline",
                 },
             ],
@@ -1440,7 +1440,7 @@ export const commandManifest = {
                     version: 1,
                     description: 'List the workspace\'s tasks, most recently updated first. Filter by status, assignee (principals or "unassigned"), parent and blocked state. Summaries carry no body or comments.',
                     inputJson: '{"additionalProperties":false,"properties":{"workspace_id":{"maxLength":200,"minLength":1,"title":"Workspace Id","type":"string"},"parent":{"anyOf":[{"description":"The task\'s number (\\"42\\" or \\"#42\\") or its tsk_ ID.","pattern":"^(#?[1-9][0-9]{0,15}|tsk_[0-9A-Za-z]{16})$","type":"string"},{"type":"null"}],"default":null,"description":"Only this task\'s subtasks.","title":"Parent"}},"required":["workspace_id"],"title":"TaskListInput","type":"object"}',
-                    queryJson: '{"type":"object","additionalProperties":false,"properties":{"limit":{"type":"integer","minimum":1,"default":50,"description":"Rows per page, at most 200; a larger value is reduced to it."},"cursor":{"type":"string","minLength":1,"maxLength":5504,"description":"The previous page\'s next_cursor, sent with the same sort, filter and search."},"sort":{"type":"string","enum":["updated_at.desc","number.asc"],"default":"updated_at.desc"},"filter":{"additionalProperties":false,"properties":{"status":{"anyOf":[{"items":{"enum":["backlog","ready","in_progress","failed","done","cancelled"],"type":"string"},"maxItems":6,"minItems":1,"type":"array"},{"type":"null"}],"default":null,"description":"Tasks in any of these statuses.","title":"Status"},"assignee":{"anyOf":[{"items":{"$ref":"#/$defs/AssigneeFilter"},"maxItems":32,"minItems":1,"type":"array"},{"type":"null"}],"default":null,"description":"Tasks assigned to any of these; {\\"type\\": \\"unassigned\\"} matches tasks with no assignee.","title":"Assignee"},"is_blocked":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"Only blocked tasks, or only unblocked ones.","title":"Is Blocked"}},"type":"object","required":[],"default":{}}},"required":[],"$defs":{"AssigneeFilter":{"additionalProperties":false,"description":"A principal, or ``{\\"type\\": \\"unassigned\\"}`` for tasks with no assignee.","properties":{"type":{"enum":["user","agent","service_account","unassigned"],"title":"Type","type":"string"},"id":{"anyOf":[{"maxLength":200,"minLength":1,"type":"string"},{"type":"null"}],"default":null,"description":"The principal\'s ID; omitted for \\"unassigned\\".","title":"Id"}},"required":["type"],"title":"AssigneeFilter","type":"object"}}}',
+                    queryJson: '{"type":"object","additionalProperties":false,"properties":{"limit":{"type":"integer","minimum":1,"default":50,"description":"Rows per page, at most 200; a larger value is reduced to it."},"cursor":{"type":"string","minLength":1,"maxLength":5504,"description":"The previous page\'s next_cursor, sent with the same sort, filter and search."},"sort":{"type":"string","enum":["updated_at.desc","number.asc"],"default":"updated_at.desc"},"filter":{"additionalProperties":false,"properties":{"status":{"anyOf":[{"items":{"enum":["backlog","ready","in_progress","failed","done","cancelled"],"type":"string"},"maxItems":6,"minItems":1,"type":"array"},{"type":"null"}],"default":null,"description":"Tasks in any of these statuses.","title":"Status"},"assignee":{"anyOf":[{"items":{"$ref":"#/$defs/AssigneeFilter"},"maxItems":32,"minItems":1,"type":"array"},{"type":"null"}],"default":null,"description":"Tasks assigned to any of these; {\\"type\\": \\"unassigned\\"} matches tasks with no assignee.","title":"Assignee"},"is_blocked":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"Only blocked tasks, or only unblocked ones.","title":"Is Blocked"},"tags":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null,"description":"Tasks carrying any of these workspace tag IDs.","title":"Tags"}},"type":"object","required":[],"default":{}}},"required":[],"$defs":{"AssigneeFilter":{"additionalProperties":false,"description":"A principal, or ``{\\"type\\": \\"unassigned\\"}`` for tasks with no assignee.","properties":{"type":{"enum":["user","agent","service_account","unassigned"],"title":"Type","type":"string"},"id":{"anyOf":[{"maxLength":200,"minLength":1,"type":"string"},{"type":"null"}],"default":null,"description":"The principal\'s ID; omitted for \\"unassigned\\".","title":"Id"}},"required":["type"],"title":"AssigneeFilter","type":"object"}}}',
                     resultKind: "inline",
                 },
             ],

package/dist/main.d.ts

@@ -1,15 +1,2 @@
 #!/usr/bin/env node
-import { Profiles } from "./profiles.ts";
-import type { InvocationContext } from "./catalog.ts";
-import type { OutputOptions } from "./output.ts";
-import type { RpcOptions } from "./rpc.ts";
-export { parseGlobals } from "./argv.ts";
-export interface RunOptions extends OutputOptions {
-    profiles?: Profiles;
-    env?: NodeJS.ProcessEnv;
-    fetch?: InvocationContext["fetch"];
-    stdin?: RpcOptions["stdin"];
-    signal?: AbortSignal;
-}
-export declare function run(argv?: string[], runtime?: RunOptions): Promise<void>;
-export declare function execute(argv?: string[], runtime?: RunOptions): Promise<number>;
+export * from "./runner.ts";

package/dist/main.js

@@ -1,313 +1,8 @@
 #!/usr/bin/env node
-import { readFile, realpath } from "node:fs/promises";
-import { createInterface } from "node:readline/promises";
+import { realpath } from "node:fs/promises";
 import { pathToFileURL } from "node:url";
-import { AuthClient } from "./auth.js";
-import { commandOptions, parseGlobals } from "./argv.js";
-import { authorizedWorkspace, contextStatus, useContext } from "./context.js";
-import { CliError, record, safeText, throwIfInterrupted } from "./errors.js";
-import { Profiles, selectedWorkspace } from "./profiles.js";
-export { parseGlobals } from "./argv.js";
-const help = `Zo public command line client
-
-Usage: zo <command> [--profile <name>] [--workspace <id>] [--json]
-
-  login / logout       Sign in through your browser or revoke the sign-in
-  auth status / token  Inspect your identity or explicitly print an access token
-  context list/use/show Select an authorized workspace
-  actions list/describe Discover live action contracts
-  rpc <action>         Invoke any callable action from JSON
-  <resource> <action>  Invoke an installed built-in command
-  completion <shell>  Print bash, zsh or fish completion (offline)
-  --version            Show the installed CLI version
-
-Run zo <command> --help for options; for example, zo machine list --help.
-Use --profile to keep separate sign-ins. New profiles use production.
-ZO_SYSTEM_API_ACCESS_TOKEN overrides saved credentials; ZO_WORKSPACE_ID selects a workspace.
-`;
-const localHelp = {
-    login: "Usage: zo login [--profile <name>] [--workspace <id>] [--no-browser]\nPrint a sign-in URL and code, open your browser, and wait for approval.\nNew profiles use production. Browser consent approves workspaces and identities.\n--no-browser prints the URL without opening a browser; approve it on any device.\nInternal testing: --environment staging explicitly binds a separate profile to staging.\n",
-    logout: "Usage: zo logout [--profile <name>] [--local-only]\nRevoke the saved sign-in and pending replaced sign-ins. --local-only removes local credentials without revoking server access.\n",
-    auth: "Usage: zo auth status | token [--headers]\nStatus shows the current identity; token explicitly prints an access token.\n",
-    "auth status": "Usage: zo auth status [--profile <name>] [--workspace <id>] [--json]\nShow the approving person, sign-in expiry and effective identity in the selected workspace.\n",
-    "auth token": "Usage: zo auth token [--profile <name>] [--headers]\nExplicitly print a short-lived access token; --headers prints Authorization JSON.\n",
-    context: "Usage: zo context list | use <workspace-id> | show\nWorkspace selection does not change permissions.\n",
-    "context list": "Usage: zo context list [--profile <name>] [--json]\nList currently authorized workspaces and effective identities.\n",
-    "context use": "Usage: zo context use <workspace-id> [--profile <name>]\nValidate access and save the workspace as this profile's default.\n",
-    "context show": "Usage: zo context show [--profile <name>] [--workspace <id>] [--json]\nShow and validate the selected workspace and identity.\n",
-    actions: "Usage: zo actions list | describe <action> [--version <integer>] [--catalog scoped|all]\nRead the live catalog. --catalog all includes definitions beyond current availability.\n",
-    "actions list": "Usage: zo actions list [--catalog scoped|all] [--profile <name>] [--workspace <id>] [--json]\nList callable contracts from the live catalog; --catalog all includes definitions.\n",
-    "actions describe": "Usage: zo actions describe <action> [--version <integer>] [--catalog scoped|all] [--json]\nShow live input, output and query schemas. Omit --version to inspect every published version.\n",
-    rpc: "Usage: zo rpc <action> [--input <json> | --input-file <path|->] [--version <integer>]\n  --query <json>            Declared list-query options; one page per call\n  --idempotency-key <key>   Envelope key where the action supports it\n  --preview                Print the request without invoking\n  --envelope               Print the complete success envelope\n  --json                   Print exact result JSON\n  --profile <name> --workspace <id>\nThe live catalog supplies the default version. RPC preserves supplied inputs. Invocations are never retried.\n",
-    completion: "Usage: zo completion bash|zsh|fish\nPrint completion from installed metadata without credentials or network requests.\n",
-};
-function identity(session, workspace) {
-    const { type, id } = workspace.subject;
-    if (type === "user" &&
-        session.approving_subject?.type === "user" &&
-        session.approving_subject.id === id)
-        return "as you";
-    if (type === "service_account")
-        return `as service account ${safeText(id)}`;
-    return `as ${type} ${safeText(id)}`;
-}
-async function showHelp(args, stdout) {
-    if (!args.length) {
-        stdout.write(help);
-        return;
-    }
-    const path = args.slice(0, args.findIndex((arg) => arg.startsWith("--")) === -1
-        ? undefined
-        : args.findIndex((arg) => arg.startsWith("--")));
-    const key = path
-        .slice(0, ["auth", "context", "actions"].includes(path[0] ?? "") ? 2 : 1)
-        .join(" ");
-    if (Object.hasOwn(localHelp, key)) {
-        stdout.write(localHelp[key] ?? "");
-        return;
-    }
-    stdout.write((await import("./commands.js")).builtinHelp(path));
-}
-export async function run(argv = process.argv.slice(2), runtime = {}) {
-    const { args, options } = parseGlobals(argv);
-    const stdout = runtime.stdout ?? process.stdout;
-    const stderr = runtime.stderr ?? process.stderr;
-    const output = {
-        stdout,
-        stderr,
-        json: options.json,
-        envelope: options.envelope,
-    };
-    const env = runtime.env ?? process.env;
-    if (options.help || !args.length) {
-        await showHelp(args, stdout);
-        return;
-    }
-    if (args[0] === "--version") {
-        if (args.length !== 1)
-            throw new CliError("Usage: zo --version");
-        const manifest = JSON.parse(await readFile(new URL("../package.json", import.meta.url), "utf8"));
-        if (!record(manifest) || typeof manifest.version !== "string")
-            throw new CliError("The installed package has no version.", 5);
-        stdout.write(`${manifest.version}\n`);
-        return;
-    }
-    if (args[0] === "completion") {
-        if (args.length !== 2 || !args[1])
-            throw new CliError(localHelp.completion ?? "Invalid completion command.");
-        stdout.write((await import("./commands.js")).completionScript(args[1]));
-        return;
-    }
-    const local = ["login", "logout", "auth", "context"].includes(args[0] ?? "");
-    if (options.envelope && local)
-        throw new CliError("--envelope is only supported for action invocation.");
-    const controller = new AbortController();
-    const interrupt = () => controller.abort();
-    process.once("SIGINT", interrupt);
-    const signal = runtime.signal
-        ? AbortSignal.any([controller.signal, runtime.signal])
-        : controller.signal;
-    try {
-        throwIfInterrupted(signal);
-        const profiles = runtime.profiles ?? new Profiles();
-        const { writeJson } = await import("./output.js");
-        const writeLocalJson = (value) => {
-            throwIfInterrupted(signal);
-            writeJson(value, output);
-        };
-        if (args[0] === "login") {
-            const parsed = commandOptions(args.slice(1), ["environment"], ["no-browser"]);
-            const requested = parsed.values.get("environment");
-            if (requested !== undefined &&
-                requested !== "production" &&
-                requested !== "staging")
-                throw new CliError("--environment must be production or staging.");
-            const profile = await profiles.create(options.profile, requested, signal);
-            const auth = new AuthClient(profile, profiles.directory, {
-                env,
-                fetch: runtime.fetch,
-                signal,
-            });
-            const login = await auth.login({
-                noBrowser: parsed.flags.has("no-browser"),
-                signal,
-                announce: ({ url, userCode, browser }) => stderr.write(`${browser
-                    ? "Opening your browser to sign in. If it doesn't open, visit:"
-                    : "To sign in, visit this URL on any device:"}\n\n  ${url}\n\nCode: ${userCode}. Approve only if your browser shows the same code.\nWaiting for approval… (Ctrl-C to cancel)\n`),
-            });
-            stderr.write(`\nApproved in the browser. Sign-in saved for profile ${profile.name}.\n`);
-            if (login.cleanupPending)
-                stderr.write("A previous sign-in could not be revoked. Cleanup remains saved for the next login; the current sign-in is active. You can revoke the previous sign-in in Authorized apps.\n");
-            const session = await auth.session();
-            // Always list the approved workspaces, so a sign-in someone else
-            // approved shows up as workspaces or identities you don't recognize.
-            session.workspaces.forEach((workspace, index) => stderr.write(`${index + 1}. ${safeText(workspace.name)} (${workspace.workspace_id}), ${identity(session, workspace)}\n`));
-            const desired = options.workspace ?? env.ZO_WORKSPACE_ID ?? profile.workspaceId;
-            let chosen;
-            if (options.workspace !== undefined)
-                chosen = authorizedWorkspace(session, options.workspace).workspace_id;
-            else if (desired !== undefined) {
-                chosen = session.workspaces.find((workspace) => workspace.workspace_id === desired)?.workspace_id;
-                if (!chosen)
-                    stderr.write(env.ZO_WORKSPACE_ID !== undefined
-                        ? "ZO_WORKSPACE_ID is not authorized by the new sign-in. Choose a workspace, then update or unset ZO_WORKSPACE_ID (or use --workspace) before invoking.\n"
-                        : "The saved workspace is not authorized by the new sign-in. Choose a workspace explicitly; the previous selection is unchanged.\n");
-            }
-            else if (session.workspaces.length === 1)
-                chosen = session.workspaces[0]?.workspace_id;
-            if (!chosen &&
-                !runtime.stdin &&
-                process.stdin.isTTY &&
-                stderr.isTTY &&
-                session.workspaces.length > 0) {
-                const input = createInterface({
-                    input: process.stdin,
-                    output: process.stderr,
-                });
-                try {
-                    const answer = await input.question("Choose a workspace number: ", {
-                        signal,
-                    });
-                    if (/^[1-9][0-9]*$/.test(answer))
-                        chosen = session.workspaces[Number(answer) - 1]?.workspace_id;
-                }
-                finally {
-                    input.close();
-                }
-            }
-            if (!chosen) {
-                stderr.write("Select an authorized workspace with zo context use <workspace-id>.\n");
-                writeLocalJson({
-                    profile: profile.name,
-                    signed_in: true,
-                    workspace_id: null,
-                    selection_required: true,
-                });
-                return;
-            }
-            await profiles.select(profile, chosen, signal);
-            writeLocalJson({ profile: profile.name, workspace_id: chosen });
-            return;
-        }
-        const profile = await profiles.resolve(options.profile);
-        throwIfInterrupted(signal);
-        const auth = new AuthClient(profile, profiles.directory, {
-            env,
-            fetch: runtime.fetch,
-            signal,
-        });
-        if (args[0] === "logout") {
-            const parsed = commandOptions(args.slice(1), [], ["local-only"]);
-            const localOnly = parsed.flags.has("local-only");
-            await auth.logout(localOnly);
-            throwIfInterrupted(signal);
-            stderr.write(localOnly
-                ? "Local credentials removed. Server access was not revoked.\n"
-                : "Signed out; saved sign-ins revoked.\n");
-            return;
-        }
-        if (args[0] === "auth" && args[1] === "token") {
-            const parsed = commandOptions(args.slice(2), [], ["headers"]);
-            const token = await auth.accessToken();
-            throwIfInterrupted(signal);
-            if (parsed.flags.has("headers"))
-                writeLocalJson({ Authorization: `Bearer ${token}` });
-            else
-                stdout.write(`${token}\n`);
-            return;
-        }
-        if ((args[0] === "auth" && args[1] === "status") ||
-            (args[0] === "context" && args[1] === "show")) {
-            commandOptions(args.slice(2), []);
-            writeLocalJson(await contextStatus(profile, auth, options.workspace, env));
-            return;
-        }
-        if (args[0] === "context" && args[1] === "list") {
-            commandOptions(args.slice(2), []);
-            writeLocalJson((await auth.session()).workspaces);
-            return;
-        }
-        if (args[0] === "context" && args[1] === "use") {
-            if (args.length !== 3 || !args[2])
-                throw new CliError("Usage: zo context use <workspace-id>");
-            writeLocalJson(await useContext(profiles, profile, auth, args[2], signal));
-            return;
-        }
-        if (local)
-            throw new CliError("Unknown command. Run zo --help.");
-        const context = {
-            workspaceId: selectedWorkspace(profile, options.workspace, env),
-            apiOrigin: auth.binding.api,
-            accessToken: () => auth.accessToken(),
-            signal,
-            ...(runtime.fetch ? { fetch: runtime.fetch } : {}),
-        };
-        if (args[0] === "rpc") {
-            const action = args[1];
-            if (!action || action.startsWith("--"))
-                throw new CliError("Usage: zo rpc <action> [options]");
-            const parsed = commandOptions(args.slice(2), ["input", "input-file", "version", "query", "idempotency-key"], ["preview"]);
-            const { parseVersion } = await import("./catalog.js");
-            const version = parsed.values.get("version");
-            const result = await (await import("./rpc.js")).runRpc(context, {
-                action,
-                input: parsed.values.get("input"),
-                inputFile: parsed.values.get("input-file"),
-                query: parsed.values.get("query"),
-                version: version === undefined ? undefined : parseVersion(version),
-                idempotencyKey: parsed.values.get("idempotency-key"),
-                preview: parsed.flags.has("preview"),
-                stdin: runtime.stdin,
-            });
-            (await import("./output.js")).writeRpcResult(result, output);
-            return;
-        }
-        if (args[0] === "actions") {
-            const describe = args[1] === "describe";
-            if (args[1] !== "list" && !describe)
-                throw new CliError("Usage: zo actions list | describe <action>");
-            const action = describe ? args[2] : undefined;
-            if (describe && (!action || action.startsWith("--")))
-                throw new CliError("Usage: zo actions describe <action>");
-            if (options.envelope)
-                throw new CliError("--envelope is only supported for action invocation.");
-            const parsed = commandOptions(args.slice(describe ? 3 : 2), describe ? ["catalog", "version"] : ["catalog"]);
-            const mode = parsed.values.get("catalog") ?? "scoped";
-            if (mode !== "scoped" && mode !== "all")
-                throw new CliError("--catalog must be scoped or all.");
-            const { loadCatalog, listActions, describeAction, parseVersion } = await import("./catalog.js");
-            const version = parsed.values.get("version");
-            const parsedVersion = version === undefined ? undefined : parseVersion(version);
-            const { catalog } = await loadCatalog(context, { catalog: mode });
-            writeJson(action
-                ? describeAction(catalog, action, parsedVersion)
-                : listActions(catalog), output);
-            return;
-        }
-        const { matchBuiltinCommand, runBuiltin } = await import("./commands.js");
-        const command = matchBuiltinCommand(args);
-        if (!command)
-            throw new CliError("Unknown command. Run zo --help.");
-        const result = await runBuiltin(context, command.action, command.args, runtime.stdin);
-        (await import("./presentation.js")).writeBuiltinResult(command.action, result, { ...output, workspaceId: context.workspaceId });
-    }
-    finally {
-        process.removeListener("SIGINT", interrupt);
-    }
-}
-export async function execute(argv = process.argv.slice(2), runtime = {}) {
-    try {
-        await run(argv, runtime);
-        return 0;
-    }
-    catch (error) {
-        const { writeError } = await import("./output.js");
-        return writeError(error, {
-            ...runtime,
-            json: argv.some((arg) => arg === "--json"),
-        });
-    }
-}
+import { execute } from "./runner.js";
+export * from "./runner.js";
 if (process.argv[1] &&
     import.meta.url === pathToFileURL(await realpath(process.argv[1])).href)
     process.exitCode = await execute();

package/dist/runner.d.ts

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+import { Profiles } from "./profiles.ts";
+import type { InvocationContext } from "./catalog.ts";
+import type { OutputOptions } from "./output.ts";
+import type { RpcOptions } from "./rpc.ts";
+export { parseGlobals } from "./argv.ts";
+export interface RunOptions extends OutputOptions {
+    version?: string;
+    profiles?: Profiles;
+    env?: NodeJS.ProcessEnv;
+    fetch?: InvocationContext["fetch"];
+    stdin?: RpcOptions["stdin"];
+    signal?: AbortSignal;
+}
+export declare function run(argv?: string[], runtime?: RunOptions): Promise<void>;
+export declare function execute(argv?: string[], runtime?: RunOptions): Promise<number>;

package/dist/runner.js

@@ -0,0 +1,320 @@
+#!/usr/bin/env node
+import { readFile } from "node:fs/promises";
+import { createInterface } from "node:readline/promises";
+import { AuthClient } from "./auth.js";
+import { commandOptions, parseGlobals } from "./argv.js";
+import { authorizedWorkspace, contextStatus, useContext } from "./context.js";
+import { CliError, record, safeText, throwIfInterrupted } from "./errors.js";
+import { Profiles, selectedWorkspace } from "./profiles.js";
+export { parseGlobals } from "./argv.js";
+const help = `Zo public command line client
+
+Usage: zo <command> [--profile <name>] [--workspace <id>] [--json]
+
+  login / logout       Sign in through your browser or revoke the sign-in
+  auth status / token  Inspect your identity or explicitly print an access token
+  context list/use/show Select an authorized workspace
+  actions list/describe Discover live action contracts
+  rpc <action>         Invoke any callable action from JSON
+  <resource> <action>  Invoke an installed built-in command
+  completion <shell>  Print bash, zsh or fish completion (offline)
+  --version            Show the installed CLI version
+
+Run zo <command> --help for options; for example, zo machine list --help.
+Use --profile to keep separate sign-ins. New profiles use production.
+ZO_SYSTEM_API_ACCESS_TOKEN overrides saved credentials; ZO_WORKSPACE_ID selects a workspace.
+`;
+const localHelp = {
+    login: "Usage: zo login [--profile <name>] [--workspace <id>] [--no-browser]\nPrint a sign-in URL and code, open your browser, and wait for approval.\nNew profiles use production. Browser consent approves workspaces and identities.\n--no-browser prints the URL without opening a browser; approve it on any device.\nInternal testing: --environment staging explicitly binds a separate profile to staging.\n",
+    logout: "Usage: zo logout [--profile <name>] [--local-only]\nRevoke the saved sign-in and pending replaced sign-ins. --local-only removes local credentials without revoking server access.\n",
+    auth: "Usage: zo auth status | token [--headers]\nStatus shows the current identity; token explicitly prints an access token.\n",
+    "auth status": "Usage: zo auth status [--profile <name>] [--workspace <id>] [--json]\nShow the approving person, sign-in expiry and effective identity in the selected workspace.\n",
+    "auth token": "Usage: zo auth token [--profile <name>] [--headers]\nExplicitly print a short-lived access token; --headers prints Authorization JSON.\n",
+    context: "Usage: zo context list | use <workspace-id> | show\nWorkspace selection does not change permissions.\n",
+    "context list": "Usage: zo context list [--profile <name>] [--json]\nList currently authorized workspaces and effective identities.\n",
+    "context use": "Usage: zo context use <workspace-id> [--profile <name>]\nValidate access and save the workspace as this profile's default.\n",
+    "context show": "Usage: zo context show [--profile <name>] [--workspace <id>] [--json]\nShow and validate the selected workspace and identity.\n",
+    actions: "Usage: zo actions list | describe <action> [--version <integer>] [--catalog scoped|all]\nRead the live catalog. --catalog all includes definitions beyond current availability.\n",
+    "actions list": "Usage: zo actions list [--catalog scoped|all] [--profile <name>] [--workspace <id>] [--json]\nList callable contracts from the live catalog; --catalog all includes definitions.\n",
+    "actions describe": "Usage: zo actions describe <action> [--version <integer>] [--catalog scoped|all] [--json]\nShow live input, output and query schemas. Omit --version to inspect every published version.\n",
+    rpc: "Usage: zo rpc <action> [--input <json> | --input-file <path|->] [--version <integer>]\n  --query <json>            Declared list-query options; one page per call\n  --idempotency-key <key>   Envelope key where the action supports it\n  --preview                Print the request without invoking\n  --envelope               Print the complete success envelope\n  --json                   Print exact result JSON\n  --profile <name> --workspace <id>\nThe live catalog supplies the default version. RPC preserves supplied inputs. Invocations are never retried.\n",
+    completion: "Usage: zo completion bash|zsh|fish\nPrint completion from installed metadata without credentials or network requests.\n",
+};
+// Printed after login so a first-time caller, person or agent, knows the next
+// command and that one sign-in serves the CLI, HTTP and MCP alike.
+const nextSteps = "Calls act as the identity shown for each workspace, with its current permissions.\n" +
+    "Next: zo workspace get for a first call, then zo actions list to see what you can call.\n" +
+    "For HTTP or MCP, zo auth token --headers prints an Authorization header for this sign-in.\n";
+function identity(session, workspace) {
+    const { type, id } = workspace.subject;
+    if (type === "user" &&
+        session.approving_subject?.type === "user" &&
+        session.approving_subject.id === id)
+        return "as you";
+    if (type === "service_account")
+        return `as service account ${safeText(id)}`;
+    return `as ${type} ${safeText(id)}`;
+}
+async function showHelp(args, stdout) {
+    if (!args.length) {
+        stdout.write(help);
+        return;
+    }
+    const path = args.slice(0, args.findIndex((arg) => arg.startsWith("--")) === -1
+        ? undefined
+        : args.findIndex((arg) => arg.startsWith("--")));
+    const key = path
+        .slice(0, ["auth", "context", "actions"].includes(path[0] ?? "") ? 2 : 1)
+        .join(" ");
+    if (Object.hasOwn(localHelp, key)) {
+        stdout.write(localHelp[key] ?? "");
+        return;
+    }
+    stdout.write((await import("./commands.js")).builtinHelp(path));
+}
+export async function run(argv = process.argv.slice(2), runtime = {}) {
+    const { args, options } = parseGlobals(argv);
+    const stdout = runtime.stdout ?? process.stdout;
+    const stderr = runtime.stderr ?? process.stderr;
+    const output = {
+        stdout,
+        stderr,
+        json: options.json,
+        envelope: options.envelope,
+    };
+    const env = runtime.env ?? process.env;
+    if (options.help || !args.length) {
+        await showHelp(args, stdout);
+        return;
+    }
+    if (args[0] === "--version") {
+        if (args.length !== 1)
+            throw new CliError("Usage: zo --version");
+        if (runtime.version !== undefined) {
+            stdout.write(`${runtime.version}\n`);
+            return;
+        }
+        const manifest = JSON.parse(await readFile(new URL("../package.json", import.meta.url), "utf8"));
+        if (!record(manifest) || typeof manifest.version !== "string")
+            throw new CliError("The installed package has no version.", 5);
+        stdout.write(`${manifest.version}\n`);
+        return;
+    }
+    if (args[0] === "completion") {
+        if (args.length !== 2 || !args[1])
+            throw new CliError(localHelp.completion ?? "Invalid completion command.");
+        stdout.write((await import("./commands.js")).completionScript(args[1]));
+        return;
+    }
+    const local = ["login", "logout", "auth", "context"].includes(args[0] ?? "");
+    if (options.envelope && local)
+        throw new CliError("--envelope is only supported for action invocation.");
+    const controller = new AbortController();
+    const interrupt = () => controller.abort();
+    process.once("SIGINT", interrupt);
+    const signal = runtime.signal
+        ? AbortSignal.any([controller.signal, runtime.signal])
+        : controller.signal;
+    try {
+        throwIfInterrupted(signal);
+        const profiles = runtime.profiles ?? new Profiles();
+        const { writeJson } = await import("./output.js");
+        const writeLocalJson = (value) => {
+            throwIfInterrupted(signal);
+            writeJson(value, output);
+        };
+        if (args[0] === "login") {
+            const parsed = commandOptions(args.slice(1), ["environment"], ["no-browser"]);
+            const requested = parsed.values.get("environment");
+            if (requested !== undefined &&
+                requested !== "production" &&
+                requested !== "staging")
+                throw new CliError("--environment must be production or staging.");
+            const profile = await profiles.create(options.profile, requested, signal);
+            const auth = new AuthClient(profile, profiles.directory, {
+                env,
+                fetch: runtime.fetch,
+                signal,
+            });
+            const login = await auth.login({
+                noBrowser: parsed.flags.has("no-browser"),
+                signal,
+                announce: ({ url, userCode, browser }) => stderr.write(`${browser
+                    ? "Opening your browser to sign in. If it doesn't open, visit:"
+                    : "To sign in, visit this URL on any device:"}\n\n  ${url}\n\nCode: ${userCode}. Approve only if your browser shows the same code.\nWaiting for approval… (Ctrl-C to cancel)\n`),
+            });
+            stderr.write(`\nApproved in the browser. Sign-in saved for profile ${profile.name}.\n`);
+            if (login.cleanupPending)
+                stderr.write("A previous sign-in could not be revoked. Cleanup remains saved for the next login; the current sign-in is active. You can revoke the previous sign-in in Authorized apps.\n");
+            const session = await auth.session();
+            // Always list the approved workspaces, so a sign-in someone else
+            // approved shows up as workspaces or identities you don't recognize.
+            session.workspaces.forEach((workspace, index) => stderr.write(`${index + 1}. ${safeText(workspace.name)} (${workspace.workspace_id}), ${identity(session, workspace)}\n`));
+            const desired = options.workspace ?? env.ZO_WORKSPACE_ID ?? profile.workspaceId;
+            let chosen;
+            if (options.workspace !== undefined)
+                chosen = authorizedWorkspace(session, options.workspace).workspace_id;
+            else if (desired !== undefined) {
+                chosen = session.workspaces.find((workspace) => workspace.workspace_id === desired)?.workspace_id;
+                if (!chosen)
+                    stderr.write(env.ZO_WORKSPACE_ID !== undefined
+                        ? "ZO_WORKSPACE_ID is not authorized by the new sign-in. Choose a workspace, then update or unset ZO_WORKSPACE_ID (or use --workspace) before invoking.\n"
+                        : "The saved workspace is not authorized by the new sign-in. Choose a workspace explicitly; the previous selection is unchanged.\n");
+            }
+            else if (session.workspaces.length === 1)
+                chosen = session.workspaces[0]?.workspace_id;
+            if (!chosen &&
+                !runtime.stdin &&
+                process.stdin.isTTY &&
+                stderr.isTTY &&
+                session.workspaces.length > 0) {
+                const input = createInterface({
+                    input: process.stdin,
+                    output: process.stderr,
+                });
+                try {
+                    const answer = await input.question("Choose a workspace number: ", {
+                        signal,
+                    });
+                    if (/^[1-9][0-9]*$/.test(answer))
+                        chosen = session.workspaces[Number(answer) - 1]?.workspace_id;
+                }
+                finally {
+                    input.close();
+                }
+            }
+            if (!chosen) {
+                stderr.write("Select an authorized workspace with zo context use <workspace-id>.\n" +
+                    nextSteps);
+                writeLocalJson({
+                    profile: profile.name,
+                    signed_in: true,
+                    workspace_id: null,
+                    selection_required: true,
+                });
+                return;
+            }
+            await profiles.select(profile, chosen, signal);
+            stderr.write(nextSteps);
+            writeLocalJson({ profile: profile.name, workspace_id: chosen });
+            return;
+        }
+        const profile = await profiles.resolve(options.profile);
+        throwIfInterrupted(signal);
+        const auth = new AuthClient(profile, profiles.directory, {
+            env,
+            fetch: runtime.fetch,
+            signal,
+        });
+        if (args[0] === "logout") {
+            const parsed = commandOptions(args.slice(1), [], ["local-only"]);
+            const localOnly = parsed.flags.has("local-only");
+            await auth.logout(localOnly);
+            throwIfInterrupted(signal);
+            stderr.write(localOnly
+                ? "Local credentials removed. Server access was not revoked.\n"
+                : "Signed out; saved sign-ins revoked.\n");
+            return;
+        }
+        if (args[0] === "auth" && args[1] === "token") {
+            const parsed = commandOptions(args.slice(2), [], ["headers"]);
+            const token = await auth.accessToken();
+            throwIfInterrupted(signal);
+            if (parsed.flags.has("headers"))
+                writeLocalJson({ Authorization: `Bearer ${token}` });
+            else
+                stdout.write(`${token}\n`);
+            return;
+        }
+        if ((args[0] === "auth" && args[1] === "status") ||
+            (args[0] === "context" && args[1] === "show")) {
+            commandOptions(args.slice(2), []);
+            writeLocalJson(await contextStatus(profile, auth, options.workspace, env));
+            return;
+        }
+        if (args[0] === "context" && args[1] === "list") {
+            commandOptions(args.slice(2), []);
+            writeLocalJson((await auth.session()).workspaces);
+            return;
+        }
+        if (args[0] === "context" && args[1] === "use") {
+            if (args.length !== 3 || !args[2])
+                throw new CliError("Usage: zo context use <workspace-id>");
+            writeLocalJson(await useContext(profiles, profile, auth, args[2], signal));
+            return;
+        }
+        if (local)
+            throw new CliError("Unknown command. Run zo --help.");
+        const context = {
+            workspaceId: selectedWorkspace(profile, options.workspace, env),
+            apiOrigin: auth.binding.api,
+            accessToken: () => auth.accessToken(),
+            signal,
+            ...(runtime.fetch ? { fetch: runtime.fetch } : {}),
+        };
+        if (args[0] === "rpc") {
+            const action = args[1];
+            if (!action || action.startsWith("--"))
+                throw new CliError("Usage: zo rpc <action> [options]");
+            const parsed = commandOptions(args.slice(2), ["input", "input-file", "version", "query", "idempotency-key"], ["preview"]);
+            const { parseVersion } = await import("./catalog.js");
+            const version = parsed.values.get("version");
+            const result = await (await import("./rpc.js")).runRpc(context, {
+                action,
+                input: parsed.values.get("input"),
+                inputFile: parsed.values.get("input-file"),
+                query: parsed.values.get("query"),
+                version: version === undefined ? undefined : parseVersion(version),
+                idempotencyKey: parsed.values.get("idempotency-key"),
+                preview: parsed.flags.has("preview"),
+                stdin: runtime.stdin,
+            });
+            (await import("./output.js")).writeRpcResult(result, output);
+            return;
+        }
+        if (args[0] === "actions") {
+            const describe = args[1] === "describe";
+            if (args[1] !== "list" && !describe)
+                throw new CliError("Usage: zo actions list | describe <action>");
+            const action = describe ? args[2] : undefined;
+            if (describe && (!action || action.startsWith("--")))
+                throw new CliError("Usage: zo actions describe <action>");
+            if (options.envelope)
+                throw new CliError("--envelope is only supported for action invocation.");
+            const parsed = commandOptions(args.slice(describe ? 3 : 2), describe ? ["catalog", "version"] : ["catalog"]);
+            const mode = parsed.values.get("catalog") ?? "scoped";
+            if (mode !== "scoped" && mode !== "all")
+                throw new CliError("--catalog must be scoped or all.");
+            const { loadCatalog, listActions, describeAction, parseVersion } = await import("./catalog.js");
+            const version = parsed.values.get("version");
+            const parsedVersion = version === undefined ? undefined : parseVersion(version);
+            const { catalog } = await loadCatalog(context, { catalog: mode });
+            writeJson(action
+                ? describeAction(catalog, action, parsedVersion)
+                : listActions(catalog), output);
+            return;
+        }
+        const { matchBuiltinCommand, runBuiltin } = await import("./commands.js");
+        const command = matchBuiltinCommand(args);
+        if (!command)
+            throw new CliError("Unknown command. Run zo --help.");
+        const result = await runBuiltin(context, command.action, command.args, runtime.stdin);
+        (await import("./presentation.js")).writeBuiltinResult(command.action, result, { ...output, workspaceId: context.workspaceId });
+    }
+    finally {
+        process.removeListener("SIGINT", interrupt);
+    }
+}
+export async function execute(argv = process.argv.slice(2), runtime = {}) {
+    try {
+        await run(argv, runtime);
+        return 0;
+    }
+    catch (error) {
+        const { writeError } = await import("./output.js");
+        return writeError(error, {
+            ...runtime,
+            json: argv.some((arg) => arg === "--json"),
+        });
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zocomputer/cli",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "type": "module",
   "description": "Public Zo command line client",
   "bin": {
@@ -14,7 +14,7 @@
     "node": "^22.23.4 || ^24.22.1 || ^26.13.0"
   },
   "dependencies": {
-    "@zocomputer/system-api": "0.1.3"
+    "@zocomputer/system-api": "0.1.4"
   },
   "publishConfig": {
     "access": "public",