CLI reference

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.

`iii`

Process communication engine

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`	Launch the iii web console.
`project`	Manage iii projects (init, generate-docker)
`trigger`	Invoke a function on a running iii engine
`update`	Update iii and managed binaries to their latest versions
`worker`	Manage workers (add, remove, list, info).

`iii project`

Manage iii projects (init, generate-docker)

iii project <COMMAND>

`iii project generate-docker`

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

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

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

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]

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.

`iii update`

Update iii and managed binaries to their latest versions

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.

iii worker <COMMAND>

Subcommands:

Command	Description
`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`	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`	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`	Scaffold a NEW standalone worker repo from scratch. To install an EXISTING worker, use `iii worker add`
`list`	List all workers and their status
`logs`	Show logs from a managed worker container
`reinstall`	Re-download a worker (equivalent to `add --force`; pass `--reset-config` to also reset its config.yaml entry to registry defaults)
`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`	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`	Manage ephemeral sandboxes (create/exec/stop short-lived VMs)
`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`	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`	Stop a managed worker container. Stop is treated as a routine, reversible action; running `iii worker start <name>` brings the worker back up
`sync`	Install registry-managed workers exactly from iii.lock
`update`	Update workers in iii.lock to their latest allowed version
`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

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)

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

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

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

iii worker list

`iii worker logs`

Show logs from a managed worker container

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)

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

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)

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)

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.

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 -

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.

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.

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

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

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

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

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

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

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

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

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

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.

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]

​iii

​iii project

​iii project generate-docker

​iii project init

​iii trigger

​iii update

​iii worker

​iii worker add

​iii worker clear

​iii worker exec

​iii worker init

​iii worker list

​iii worker logs

​iii worker reinstall

​iii worker remove

​iii worker restart

​iii worker sandbox

​iii worker sandbox create

​iii worker sandbox download

​iii worker sandbox exec

​iii worker sandbox list

​iii worker sandbox run

​iii worker sandbox stop

​iii worker sandbox upload

​iii worker start

​iii worker status

​iii worker stop

​iii worker sync

​iii worker update

​iii worker verify

​iii console

`iii`

`iii project`

`iii project generate-docker`

`iii project init`

`iii trigger`

`iii update`

`iii worker`

`iii worker add`

`iii worker clear`

`iii worker exec`

`iii worker init`

`iii worker list`

`iii worker logs`

`iii worker reinstall`

`iii worker remove`

`iii worker restart`

`iii worker sandbox`

`iii worker sandbox create`

`iii worker sandbox download`

`iii worker sandbox exec`

`iii worker sandbox list`

`iii worker sandbox run`

`iii worker sandbox stop`

`iii worker sandbox upload`

`iii worker start`

`iii worker status`

`iii worker stop`

`iii worker sync`

`iii worker update`

`iii worker verify`

`iii console`