> ## Documentation Index
> Fetch the complete documentation index at: https://iii.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI reference

> Every flag, argument, and subcommand of the iii CLI, including iii worker and iii console, generated from the CLI definitions in source.

Reference for the `iii` binary and the `iii worker` and `iii console` runtimes it dispatches to. Running `iii` with no subcommand starts the engine. The same information is available from the binaries themselves via `iii --help` and `iii <subcommand> --help`. For a guided overview, see [CLI](../using-iii/cli).

## `iii`

Process communication engine

```text theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
iii [OPTIONS] [COMMAND]
```

| Option                  | Description                                                                             |
| ----------------------- | --------------------------------------------------------------------------------------- |
| `-c, --config <CONFIG>` | Path to the config file \[default: config.yaml]                                         |
| `-v, --version`         | Print version and exit                                                                  |
| `--use-default-config`  | Run with built-in defaults instead of a config file. Cannot be combined with `--config` |
| `--no-update-check`     | Disable background update and security advisory checks                                  |

**Subcommands:**

| Command                   | Description                                                                                                                                                                           |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `cloud`                   | Manage iii Cloud deployments. Dispatches to the external `iii-cloud` binary, which is temporarily maintained outside this repository; run `iii cloud --help` for its current surface. |
| [`console`](#iii-console) | Launch the iii web console.                                                                                                                                                           |
| [`project`](#iii-project) | Manage iii projects (init, generate-docker)                                                                                                                                           |
| [`trigger`](#iii-trigger) | Invoke a function on a running iii engine                                                                                                                                             |
| [`update`](#iii-update)   | Update iii and managed binaries to their latest versions                                                                                                                              |
| [`worker`](#iii-worker)   | Manage workers (add, remove, list, info).                                                                                                                                             |

### `iii project`

Manage iii projects (init, generate-docker)

```text theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
iii project <COMMAND>
```

#### `iii project generate-docker`

Generate Docker assets (Dockerfile, docker-compose.yml, .env) for an existing iii project

```text theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
iii project generate-docker [OPTIONS]
```

| Option                          | Description                                                                                               |
| ------------------------------- | --------------------------------------------------------------------------------------------------------- |
| `-d, --directory <DIRECTORY>`   | Target directory (defaults to current directory)                                                          |
| `--template-dir <TEMPLATE_DIR>` | Local directory to use for templates instead of fetching from remote (for template development and tests) |

#### `iii project init`

Initialize a new iii project in the current directory

```text theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
iii project init [OPTIONS] [NAME]
```

| Argument | Description                                                                                                                               |
| -------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `[NAME]` | Target directory for the new project (positional). Ignored when `--directory` is given. The project name is the resolved directory's name |

| Option                          | Description                                                                                                                                                                                                                                                      |
| ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `-d, --directory <DIRECTORY>`   | Target directory. Takes precedence over NAME. If neither NAME nor `--directory` is provided, the directory defaults to the current directory                                                                                                                     |
| `--docker`                      | Also generate Docker assets (Dockerfile, docker-compose.yml, .env). Equivalent to running `iii project generate-docker` separately                                                                                                                               |
| `-t, --template <TEMPLATE>`     | Scaffold from a named template (e.g. "quickstart"). Triggers the interactive scaffolder TUI                                                                                                                                                                      |
| `--template-dir <TEMPLATE_DIR>` | Local directory to use for templates instead of fetching from remote (for template development and tests)                                                                                                                                                        |
| `--skip-iii`                    | Skip the iii-engine version compatibility check                                                                                                                                                                                                                  |
| `--allow-non-empty`             | Allow initialization into a non-empty directory. Without this flag, init errors out if the target dir contains anything other than hidden dotfiles (e.g. `.git/`). Re-running init in a directory with `.iii/project.ini` is always allowed (idempotent re-init) |

### `iii trigger`

Invoke a function on a running iii engine

```text theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
iii trigger [OPTIONS] [FUNCTION_PATH] [KV]...
```

| Argument          | Description                                                                                                                       |
| ----------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `[FUNCTION_PATH]` | Function path (e.g. `my::fn`, `sandbox::create`). Positional                                                                      |
| `[KV]...`         | Key=value payload tokens (`a=10 b="hello world"`). Combinable with `--json`: kv pairs override individual keys of the json object |

| Option                      | Description                                                                                                                           |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `--json <JSON>`             | JSON payload (`--json '{"a":1}'`). When combined with kv pairs the json must be an object; kv pairs override its keys (shallow merge) |
| `--address <ADDRESS>`       | Engine host address \[default: localhost]                                                                                             |
| `--port <PORT>`             | Engine WebSocket port \[default: 49134]                                                                                               |
| `--timeout-ms <TIMEOUT_MS>` | Max time to wait for the invocation result (milliseconds) \[default: 30000]                                                           |

<Note>
  `iii trigger <function> --help` additionally queries a running engine for the function's description and request schema. That output depends on which workers are registered and is not part of this page; see [Creating Workers / Functions](../creating-workers/functions#attach-request-and-response-schemas).
</Note>

### `iii update`

Update iii and managed binaries to their latest versions

```text theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
iii update [OPTIONS] [COMMAND]
```

| Argument    | Description                                                                                                                                                |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `[COMMAND]` | Specific command or binary to update (e.g., "console", "self"). Use "self" or "iii" to update only iii. If omitted, updates iii and all installed binaries |

| Option           | Description                                                      |
| ---------------- | ---------------------------------------------------------------- |
| `--list-targets` | List the targets you can pass to `iii update [COMMAND]` and exit |

## `iii worker`

iii managed worker runtime

The `iii` binary dispatches `iii worker ...` to the separately installed `iii-worker` runtime; this section documents that runtime's full tree.

```text theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
iii worker <COMMAND>
```

**Subcommands:**

| Command                              | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`add`](#iii-worker-add)             | Install a worker from the iii registry, a path to a local worker directory (ex. `./myWorker` with a `iii.worker.yaml` file within it) or by OCI image reference. To create a NEW worker from scratch, use `iii worker init`. By default `add` waits up to 120s for the worker to report ready. After which the worker will continue to boot but the command will return to the shell. See `iii worker status` to continue observing a booting worker and `iii worker logs` for logs |
| [`clear`](#iii-worker-clear)         | Clear downloaded worker artifacts from \~/.iii/ (local-only, no engine connection needed). Does not affect a worker's own build artifacts or dependencies (e.g. node\_modules, Cargo.lock)                                                                                                                                                                                                                                                                                          |
| [`exec`](#iii-worker-exec)           | Run a command inside a running worker's VM. Pipes stdin/stdout/ stderr through and returns the child's exit code. Pass `-t` for an interactive PTY                                                                                                                                                                                                                                                                                                                                  |
| [`init`](#iii-worker-init)           | Scaffold a NEW standalone worker repo from scratch. To install an EXISTING worker, use `iii worker add`                                                                                                                                                                                                                                                                                                                                                                             |
| [`list`](#iii-worker-list)           | List all workers and their status                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| [`logs`](#iii-worker-logs)           | Show logs from a managed worker container                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| [`reinstall`](#iii-worker-reinstall) | Re-download a worker (equivalent to `add --force`; pass `--reset-config` to also reset its config.yaml entry to registry defaults)                                                                                                                                                                                                                                                                                                                                                  |
| [`remove`](#iii-worker-remove)       | Remove one or more workers from config.yaml. The engine's file watcher tears down any running sandbox. Artifacts under \~/.iii/managed/\{name}/ remain; use `iii worker clear {name}` to delete them                                                                                                                                                                                                                                                                                |
| [`restart`](#iii-worker-restart)     | Restart a managed worker: stop if running, then start. By default waits up to 120s for the worker to report ready (same as start)                                                                                                                                                                                                                                                                                                                                                   |
| [`sandbox`](#iii-worker-sandbox)     | Manage ephemeral sandboxes (create/exec/stop short-lived VMs)                                                                                                                                                                                                                                                                                                                                                                                                                       |
| [`start`](#iii-worker-start)         | Start a previously stopped managed worker container. By default waits up to 120s for the worker to report ready before returning. Workers will continue to start after 120s, see `iii worker status` and `iii worker logs` for tracking workers                                                                                                                                                                                                                                     |
| [`status`](#iii-worker-status)       | Show detailed status of one worker (config, sandbox, process, logs). By default refreshes live in place until the worker reaches a success or failure state                                                                                                                                                                                                                                                                                                                         |
| [`stop`](#iii-worker-stop)           | Stop a managed worker container. Stop is treated as a routine, reversible action; running `iii worker start <name>` brings the worker back up                                                                                                                                                                                                                                                                                                                                       |
| [`sync`](#iii-worker-sync)           | Install registry-managed workers exactly from iii.lock                                                                                                                                                                                                                                                                                                                                                                                                                              |
| [`update`](#iii-worker-update)       | Update workers in iii.lock to their latest allowed version                                                                                                                                                                                                                                                                                                                                                                                                                          |
| [`verify`](#iii-worker-verify)       | Verify the worker's manifest (iii.worker.yaml) is valid                                                                                                                                                                                                                                                                                                                                                                                                                             |

### `iii worker add`

Install a worker from the iii registry, a path to a local worker directory (ex. `./myWorker` with a `iii.worker.yaml` file within it) or by OCI image reference. To create a NEW worker from scratch, use `iii worker init`. By default `add` waits up to 120s for the worker to report ready. After which the worker will continue to boot but the command will return to the shell. See `iii worker status` to continue observing a booting worker and `iii worker logs` for logs

```text theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
iii worker add [OPTIONS] <WORKER[@VERSION]|PATH>...
```

| Argument                      | Description                                                                                                                                                                                                     |
| ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `<WORKER[@VERSION]\|PATH>...` | iii registry worker names (ex. `database` or `pdfkit@1.0.0`), local worker paths (ex. `./my_worker`, a directory containing `iii.worker.yaml`), or Docker / OCI image references (ex. `ghcr.io/org/worker:tag`) |

| Option           | Description                                                                                                                                                                         |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--reset-config` | Discard the worker's config.yaml entry and recreate it from registry defaults. Plain `add --force` would otherwise keep the entry. Only takes effect together with `--force` on add |
| `-f, --force`    | Force re-download: delete existing artifacts before adding                                                                                                                          |
| `--no-wait`      | Don't block waiting for the engine to finish booting the worker                                                                                                                     |

### `iii worker clear`

Clear downloaded worker artifacts from \~/.iii/ (local-only, no engine connection needed). Does not affect a worker's own build artifacts or dependencies (e.g. node\_modules, Cargo.lock)

```text theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
iii worker clear [OPTIONS] [WORKER]
```

| Argument   | Description                              |
| ---------- | ---------------------------------------- |
| `[WORKER]` | Worker name to clear (omit to clear all) |

| Option      | Description              |
| ----------- | ------------------------ |
| `-y, --yes` | Skip confirmation prompt |

### `iii worker exec`

Run a command inside a running worker's VM. Pipes stdin/stdout/ stderr through and returns the child's exit code. Pass `-t` for an interactive PTY

```text theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
iii worker exec [OPTIONS] <WORKER> [-- <COMMAND>...]
```

| Argument       | Description                                                                                                                                         |
| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `<WORKER>`     | Worker name whose VM to run the command in                                                                                                          |
| `[COMMAND]...` | Program and arguments. Comes after `--`: `iii worker exec pdfkit -- /bin/ls -la /workspace`. First element is the executable; the rest are its argv |

| Option                    | Description                                                                                                                                                                                                                                                                                              |
| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `-e, --env <ENV>`         | Set an environment variable inside the spawned process (repeatable). `KEY=VALUE` form; anything without `=` is silently skipped                                                                                                                                                                          |
| `-w, --workdir <WORKDIR>` | Working directory inside the guest. Defaults to the dispatcher's cwd (typically `/workspace`)                                                                                                                                                                                                            |
| `-t, --tty`               | Allocate a pseudo-terminal. Required for interactive shells and TUI programs; merges stdout/stderr through the PTY master and puts the host terminal in raw mode for the session. Automatically enabled when both stdin and stdout are TTYs (ssh-style); pass `--no-tty` to force pipe mode in that case |
| `--no-tty`                | Disable TTY auto-detection and force pipe mode. Use when you want byte-exact output in a terminal session (e.g. capturing structured output from an otherwise-interactive tool)                                                                                                                          |
| `--timeout <TIMEOUT>`     | Kill the process after this long (e.g. `30s`, `5m`, `500ms`). Parsed by the standard `humantime` syntax. On expiry the client sends SIGKILL to the guest session and exits with code 124 (matches coreutils `timeout(1)`), so shell scripts can distinguish a timeout from an ordinary nonzero exit      |

### `iii worker init`

Scaffold a NEW standalone worker repo from scratch. To install an EXISTING worker, use `iii worker add`

```text theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
iii worker init [OPTIONS] [NAME]
```

| Argument | Description                                                                                                                             |
| -------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `[NAME]` | Target directory for the new worker (positional). Ignored when `--directory` is given. The worker name is the resolved directory's name |

| Option                          | Description                                                                                                                                                                    |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `-d, --directory <DIRECTORY>`   | Target directory. Takes precedence over NAME. If neither NAME nor `--directory` is provided, the directory defaults to the current directory                                   |
| `--template-dir <TEMPLATE_DIR>` | Local directory to use for templates instead of fetching from remote (for template development and tests)                                                                      |
| `--allow-non-empty`             | Allow initialization into a non-empty directory. Re-running init in a directory with `.iii/worker.ini` is always allowed (idempotent re-init)                                  |
| `-l, --language <LANG>`         | Worker language (`typescript` \| `javascript` \| `python` \| `rust`). Accepts short aliases (`ts`, `js`, `py`, `rust`, `rs`). When omitted, the user is prompted interactively |
| `--skip-iii`                    | Skip the iii-engine version compatibility check enforced by the scaffolder. Mirrors the flag on `iii project init`                                                             |

### `iii worker list`

List all workers and their status

```text theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
iii worker list
```

### `iii worker logs`

Show logs from a managed worker container

```text theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
iii worker logs [OPTIONS] <WORKER>
```

| Argument   | Description |
| ---------- | ----------- |
| `<WORKER>` | Worker name |

| Option                | Description                               |
| --------------------- | ----------------------------------------- |
| `-f, --follow`        | Follow log output                         |
| `--address <ADDRESS>` | Engine host address \[default: localhost] |
| `--port <PORT>`       | Engine WebSocket port \[default: 49134]   |

### `iii worker reinstall`

Re-download a worker (equivalent to `add --force`; pass `--reset-config` to also reset its config.yaml entry to registry defaults)

```text theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
iii worker reinstall [OPTIONS] <WORKER[@VERSION]|PATH>...
```

| Argument                      | Description                                                                                                                                                                                                     |
| ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `<WORKER[@VERSION]\|PATH>...` | iii registry worker names (ex. `database` or `pdfkit@1.0.0`), local worker paths (ex. `./my_worker`, a directory containing `iii.worker.yaml`), or Docker / OCI image references (ex. `ghcr.io/org/worker:tag`) |

| Option           | Description                                                                                                                                                                         |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--reset-config` | Discard the worker's config.yaml entry and recreate it from registry defaults. Plain `add --force` would otherwise keep the entry. Only takes effect together with `--force` on add |

### `iii worker remove`

Remove one or more workers from config.yaml. The engine's file watcher tears down any running sandbox. Artifacts under \~/.iii/managed/\{name}/ remain; use `iii worker clear {name}` to delete them

```text theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
iii worker remove [OPTIONS] <WORKER>...
```

| Argument      | Description                             |
| ------------- | --------------------------------------- |
| `<WORKER>...` | Worker names to remove (e.g., "pdfkit") |

| Option      | Description                                                     |
| ----------- | --------------------------------------------------------------- |
| `-y, --yes` | Skip the confirmation prompt when a worker is currently running |

### `iii worker restart`

Restart a managed worker: stop if running, then start. By default waits up to 120s for the worker to report ready (same as start)

```text theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
iii worker restart [OPTIONS] <WORKER>
```

| Argument   | Description            |
| ---------- | ---------------------- |
| `<WORKER>` | Worker name to restart |

| Option            | Description                                                                                                   |
| ----------------- | ------------------------------------------------------------------------------------------------------------- |
| `--no-wait`       | Return immediately. Don't block waiting for the worker to report ready                                        |
| `--port <PORT>`   | Engine WebSocket port the spawned worker connects back to. Same semantics as `start --port` \[default: 49134] |
| `--config <PATH>` | Same as `start --config`                                                                                      |

### `iii worker sandbox`

Manage ephemeral sandboxes (create/exec/stop short-lived VMs)

```text theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
iii worker sandbox <COMMAND>
```

#### `iii worker sandbox create`

Create a long-lived sandbox and print its id to stdout. Pair with `iii worker sandbox exec <id>` and `iii worker sandbox stop <id>`.

Pipe-friendly: the sandbox id is the only thing on stdout, so you can do `SB=$(iii worker sandbox create python)` in a shell.

```text theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
iii worker sandbox create [OPTIONS] <IMAGE>
```

| Argument  | Description                                                     |
| --------- | --------------------------------------------------------------- |
| `<IMAGE>` | OCI image reference (must match the engine's sandbox allowlist) |

| Option                  | Description                                                                                                          |
| ----------------------- | -------------------------------------------------------------------------------------------------------------------- |
| `--cpus <CPUS>`         | vCPUs allocated to the sandbox VM \[default: 1]                                                                      |
| `--memory <MEMORY>`     | Memory in MiB allocated to the sandbox VM \[default: 512]                                                            |
| `--idle-timeout <SECS>` | Auto-stop the sandbox after this many seconds of exec inactivity. Omit to use the engine's default                   |
| `--name <NAME>`         | Human-readable label for the sandbox (shown in `list`)                                                               |
| `--network`             | Enable guest network access. Default follows the engine's sandbox policy (typically disabled)                        |
| `-e, --env <KEY=VALUE>` | Set an environment variable inside the guest. Repeatable, `KEY=VALUE` form; entries without `=` are silently skipped |
| `--port <PORT>`         | Engine WebSocket port \[default: 49134]                                                                              |

#### `iii worker sandbox download`

Copy a file out of a running sandbox to a local path.

Streams bytes through an iii data channel. Writes to `LOCAL_PATH` on disk (or stdout when `LOCAL_PATH` is `-`).

Examples: iii worker sandbox download \<SB> /workspace/output.json ./output.json iii worker sandbox download \<SB> /workspace/build.tar - | tar -tf -

```text theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
iii worker sandbox download [OPTIONS] <SANDBOX_ID> <REMOTE_PATH> <LOCAL_PATH>
```

| Argument        | Description                                                             |
| --------------- | ----------------------------------------------------------------------- |
| `<SANDBOX_ID>`  | Sandbox id from `iii worker sandbox create` / `iii worker sandbox list` |
| `<REMOTE_PATH>` | Source path inside the sandbox                                          |
| `<LOCAL_PATH>`  | Destination path on the host. Use `-` to write to stdout                |

| Option          | Description                             |
| --------------- | --------------------------------------- |
| `--port <PORT>` | Engine WebSocket port \[default: 49134] |

#### `iii worker sandbox exec`

Run a command inside an already-running sandbox.

Pipe-mode only. Pair with `iii worker sandbox create` for the sandbox id. For interactive TTY sessions, use `iii worker exec` against a managed worker instead.

```text theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
iii worker sandbox exec [OPTIONS] <SANDBOX_ID> [COMMAND]...
```

| Argument       | Description                                                                                                                   |
| -------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `<SANDBOX_ID>` | Sandbox id from `iii worker sandbox create` / `iii worker sandbox list`                                                       |
| `[COMMAND]...` | Program and arguments to exec inside the sandbox. Comes after `--`: `iii worker sandbox exec <id> -- python3 -c 'print(2+2)'` |

| Option                  | Description                                                                                                                    |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `--timeout <TIMEOUT>`   | Kill the child after this long (e.g. `30s`, `5m`, `500ms`). Parsed by the standard `humantime` syntax                          |
| `-e, --env <KEY=VALUE>` | Set an environment variable inside the spawned process. Repeatable, `KEY=VALUE` form; entries without `=` are silently skipped |
| `--port <PORT>`         | Engine WebSocket port \[default: 49134]                                                                                        |

#### `iii worker sandbox list`

List every sandbox the daemon knows about.

The daemon's list RPC is owner-scoped for multi-tenant SDK callers, but `iii worker sandbox` is a local admin tool with no authenticated identity, so the CLI always requests the unscoped view. The `--all` flag is a silent no-op, kept so scripts that pass it from earlier releases keep working.

```text theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
iii worker sandbox list [OPTIONS]
```

| Option          | Description                             |
| --------------- | --------------------------------------- |
| `--port <PORT>` | Engine WebSocket port \[default: 49134] |

#### `iii worker sandbox run`

Create a one-shot sandbox, run a command inside it, and stop it. For multi-step workflows (agent loops, REPLs) use `create` + `exec` + `stop` instead

```text theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
iii worker sandbox run [OPTIONS] <IMAGE> [COMMAND]...
```

| Argument       | Description                                                     |
| -------------- | --------------------------------------------------------------- |
| `<IMAGE>`      | OCI image reference (must match the engine's sandbox allowlist) |
| `[COMMAND]...` | Program and arguments to exec inside the sandbox                |

| Option              | Description                                               |
| ------------------- | --------------------------------------------------------- |
| `--cpus <CPUS>`     | vCPUs allocated to the sandbox VM \[default: 1]           |
| `--memory <MEMORY>` | Memory in MiB allocated to the sandbox VM \[default: 512] |
| `--port <PORT>`     | Engine WebSocket port \[default: 49134]                   |

#### `iii worker sandbox stop`

Stop a sandbox by id, waiting for the reaper to finish

```text theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
iii worker sandbox stop [OPTIONS] <SANDBOX_ID>
```

| Argument       | Description                                              |
| -------------- | -------------------------------------------------------- |
| `<SANDBOX_ID>` | Sandbox id returned by `sandbox create` / `sandbox list` |

| Option          | Description                             |
| --------------- | --------------------------------------- |
| `--port <PORT>` | Engine WebSocket port \[default: 49134] |

#### `iii worker sandbox upload`

Copy a local file into a running sandbox.

Streams bytes through an iii data channel; no JSON-envelope size cap. Reads `LOCAL_PATH` from disk (or stdin when `LOCAL_PATH` is `-`) and writes atomically (temp file + fsync + rename) to `REMOTE_PATH` inside the sandbox.

Examples: iii worker sandbox upload \<SB> ./script.js /workspace/script.js tar -cf - ./srcdir | iii worker sandbox upload \<SB> - /workspace/src.tar

```text theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
iii worker sandbox upload [OPTIONS] <SANDBOX_ID> <LOCAL_PATH> <REMOTE_PATH>
```

| Argument        | Description                                                             |
| --------------- | ----------------------------------------------------------------------- |
| `<SANDBOX_ID>`  | Sandbox id from `iii worker sandbox create` / `iii worker sandbox list` |
| `<LOCAL_PATH>`  | Source path on the host. Use `-` to read from stdin                     |
| `<REMOTE_PATH>` | Destination path inside the sandbox                                     |

| Option          | Description                                                                    |
| --------------- | ------------------------------------------------------------------------------ |
| `--mode <MODE>` | File mode (octal) applied to the destination after the rename \[default: 0644] |
| `--parents`     | Create parent directories of `REMOTE_PATH` if they're missing                  |
| `--port <PORT>` | Engine WebSocket port \[default: 49134]                                        |

### `iii worker start`

Start a previously stopped managed worker container. By default waits up to 120s for the worker to report ready before returning. Workers will continue to start after 120s, see `iii worker status` and `iii worker logs` for tracking workers

```text theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
iii worker start [OPTIONS] <WORKER>
```

| Argument   | Description          |
| ---------- | -------------------- |
| `<WORKER>` | Worker name to start |

| Option            | Description                                                                                                                                                                                                                                                         |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--no-wait`       | Return immediately. Don't block waiting for the worker to report ready                                                                                                                                                                                              |
| `--port <PORT>`   | Engine WebSocket port the spawned worker connects back to. Defaults to DEFAULT\_PORT; the engine passes its configured iii-worker-manager port when auto-spawning external workers so non-default manager ports don't silently break connectivity \[default: 49134] |
| `--config <PATH>` | YAML config forwarded to the spawned worker binary as `--config <path>`. Binary workers only; OCI workers warn and ignore                                                                                                                                           |

### `iii worker status`

Show detailed status of one worker (config, sandbox, process, logs). By default refreshes live in place until the worker reaches a success or failure state

```text theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
iii worker status [OPTIONS] <WORKER>
```

| Argument   | Description |
| ---------- | ----------- |
| `<WORKER>` | Worker name |

| Option       | Description                                         |
| ------------ | --------------------------------------------------- |
| `--no-watch` | Print status and exit immediately (no live refresh) |

### `iii worker stop`

Stop a managed worker container. Stop is treated as a routine, reversible action; running `iii worker start <name>` brings the worker back up

```text theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
iii worker stop [OPTIONS] <WORKER>
```

| Argument   | Description         |
| ---------- | ------------------- |
| `<WORKER>` | Worker name to stop |

| Option      | Description                                                                                                |
| ----------- | ---------------------------------------------------------------------------------------------------------- |
| `-y, --yes` | Backward-compat no-op. Stop never prompts; the flag is kept so scripts that already pass `-y` keep working |

### `iii worker sync`

Install registry-managed workers exactly from iii.lock

```text theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
iii worker sync [OPTIONS]
```

| Option     | Description                                                                              |
| ---------- | ---------------------------------------------------------------------------------------- |
| `--frozen` | Verify lockfile dependencies without mutating local files. Useful for validation in CICD |

### `iii worker update`

Update workers in iii.lock to their latest allowed version

```text theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
iii worker update [WORKER]
```

| Argument   | Description                                                                  |
| ---------- | ---------------------------------------------------------------------------- |
| `[WORKER]` | Optional worker name to update. If omitted, updates every worker in iii.lock |

### `iii worker verify`

Verify the worker's manifest (iii.worker.yaml) is valid

```text theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
iii worker verify [OPTIONS]
```

| Option     | Description                                                |
| ---------- | ---------------------------------------------------------- |
| `--strict` | Also check dependency declarations against locked versions |

## `iii console`

Developer console for the iii engine

The `iii` binary dispatches `iii console ...` to the separately installed `iii-console` binary (downloaded on first use); the same binary can also be invoked directly as `iii-console`.

```text theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
iii console [OPTIONS]
```

| Option                                    | Description                                                                                           |
| ----------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| `-p, --port <PORT>`                       | Port to run the console server on \[default: 3113]                                                    |
| `--host <HOST>`                           | Host to bind the console server to \[default: 127.0.0.1]                                              |
| `--engine-host <ENGINE_HOST>`             | Host where the iii engine is running \[default: 127.0.0.1]                                            |
| `--engine-port <ENGINE_PORT>`             | Port for the iii engine REST API \[default: 3111]                                                     |
| `--ws-port <WS_PORT>`                     | Port for the iii engine WebSocket \[default: 3112]                                                    |
| `--bridge-port <BRIDGE_PORT>`             | Engine WebSocket port the console registers its worker functions on \[default: 49134]                 |
| `--no-otel`                               | Disable OpenTelemetry tracing, metrics, and logs export \[env: OTEL\_DISABLED]                        |
| `--otel-service-name <OTEL_SERVICE_NAME>` | OpenTelemetry service name (default: iii-console) \[default: iii-console] \[env: OTEL\_SERVICE\_NAME] |
| `--enable-flow`                           | Enable the experimental flow visualization page \[env: III\_ENABLE\_FLOW]                             |