# Worker commands Captured help for supplied worker processes and managed worker control. Shell, AWL and agent commands run worker processes. The managed-fleet commands contact the server that owns those processes. Connected workers and managed workers are separate readings. ## worker Run worker processes supplied by the Aion distribution ```text aion worker [OPTIONS] ``` ## worker shell Serve strict manifest-wired shell commands on an Aion task queue ```text aion worker shell [OPTIONS] --manifest --awl ``` - `--manifest `: Strict TOML shell-worker manifest generated from checked AWL - `--awl `: Required AWL document used to derive the input and output schemas for the manifest’s actions. - `--deployment `: Managed worker deployment name - `--instance-id `: Unique id for this launch of the managed worker deployment ## worker awl Serve the queue a WORKER DOCUMENT declares — a `.awl` file whose opening declaration is `worker ` rather than `workflow `. ```text aion worker awl [OPTIONS] ``` - ``: The `.awl` WORKER document to serve: a file whose opening declaration is `worker `. A workflow document is refused by name - `--identity `: Registration identity. Defaults to the document queue name followed by -awl-worker. - `--node `: Node label advertised by this worker. `AION_WORKER_NODE` supplies it when `--node` is absent; with neither, the SDK uses the host name - `--deployment `: Managed worker deployment name - `--instance-id `: Unique id for this launch of the managed worker deployment - `--concurrency `: Maximum activities served at once - `--reconnect-initial-backoff `: Seconds before the first reconnect attempt - `--reconnect-max-backoff `: Reconnect backoff cap, in seconds - `--reconnect-max-attempts `: Cumulative session-drop budget - `--auth-token-file `: File containing the bearer used to authenticate this worker. Required when the server enforces worker authentication. - `--check`: Print the exact action surface this worker would advertise, with the command each action runs, then exit without connecting. Those descriptors are the whole admission decision on a queue carrying a deployed contract, so reading them before dialling turns a remote contract-mismatch refusal into something checkable at the desk. ## worker agent Serve an agent harness compiled into this binary on the queue an `.awl` document declares — an agent worker without writing a crate. ```text aion worker agent [OPTIONS] [AWL] ``` - `[AWL]`: AWL document declaring the queue, actions and agent harness. Supply a document when running the worker. - `--liminal-address `: Liminal listen address to dial, for example `127.0.0.1:50061`. Repeat it to supply ordered redial candidates: when the connected server dies, the worker migrates to the next candidate and re-registers there. Env: `AION_WORKER_LIMINAL_ADDRESSES` (comma-separated, same order). Not the global `--endpoint`: that is a gRPC target, and the agent-harness seam exists only on the liminal worker transport. - `--task-queue `: Serve this queue instead of deriving it from the document. A document declaring exactly one `worker` block leaves nothing to choose, so the queue is derived from it. This selects among several. Env: `AION_TASK_QUEUE`. - `--identity `: Stable worker-build identity, used to correlate compatibility decisions. Env: `AION_WORKER_IDENTITY` - `--deployment `: Managed worker deployment name - `--instance-id `: Unique id for this launch of the managed worker deployment - `--node `: Locality affinity advertised at registration. Defaults to this machine's hostname, the worker SDK's own documented default - `--liminal-token-file `: File holding the liminal listener's CONNECTION token, for a server commissioned with a connection gate. This verb dials the liminal transport, which is exactly the leg the gate sits on: without this, a worker against a commissioned listener is refused at the handshake. The token authenticates the CONNECTION, not the caller -- it carries no claims, so this worker's attribution stays the `--identity` it registers under. A FILE, never the token itself: a value passed as a flag or exported as a variable is readable by every process on the host and has no mode to restrict. Env: `AION_WORKER_LIMINAL_TOKEN_FILE`. - `--check`: Print the typed action surface this worker would advertise, then exit without connecting to anything. Those descriptors are the whole admission decision on a contract-bearing queue, so seeing them before dialling turns a remote contract-mismatch refusal into something readable at the desk. ## worker status Report the managed worker fleet the SERVER supervises. ```text aion worker status [OPTIONS] ``` ## worker connected List workers connected to the registry the server dispatches against ```text aion worker connected [OPTIONS] ``` - `--all-namespaces`: Include every namespace instead of filtering to the global `--namespace` - `--task-queue `: Optional task queue filter - `--activity-type `: Optional activity type filter - Requires a newer main build; the public 18 September 2026 crate lacks this command. ## worker start Start a managed worker: record the intent durably, then supervise it. ```text aion worker start [OPTIONS] ``` - ``: Worker deployment name (the primary key used at `/worker-deployments`) ## worker stop Stop a managed worker and keep it stopped until explicitly started. ```text aion worker stop [OPTIONS] ``` - ``: Worker deployment name ## worker restart Restart a managed worker, leaving its desired state at running ```text aion worker restart [OPTIONS] ``` - ``: Worker deployment name Read [workers and SDKs](/aion/concepts/workers-and-sdks/) and [worker operations](/aion/operations/workers/). Agent check mode resolves and prints a surface without connecting.