# Commands
URL: /docs/cli/commands

All alineo commands and their options.



## SDK — OpenSandbox config and the local spec cache [#sdk--opensandbox-config-and-the-local-spec-cache]

<Cards>
  <Card href="/docs/cli/commands/init" title="init" description="Start a local OpenSandbox server via Docker." />

  <Card href="/docs/cli/commands/add" title="add" description="Fetch an agent spec from a URL or file and save it locally." />

  <Card href="/docs/cli/commands/list" title="list" description="List the agent specs saved in this project." />

  <Card href="/docs/cli/commands/remove" title="remove" description="Delete a saved agent spec file." />

  <Card href="/docs/cli/commands/telemetry" title="telemetry" description="Show, enable, or disable anonymous CLI usage telemetry." />
</Cards>

## Alineo — session lifecycle [#alineo--session-lifecycle]

These wrap `alineo`'s `Alineo.start()`/`Alineo.resume()`/`Alineo.attach()`/`Alineo.reattach()`/`Alineo.spawn()` directly. Sessions are usually addressed by **sandbox ID** — `prompt`, `steer`, and `stop` require it (see [alineo prompt](/docs/cli/commands/prompt#why-sandbox-id-not-name) for why). `spawn` and `logs` are addressed by session **name** instead — see their own pages for why. `start` begins a fresh session and takes a spec path, not an identifier.

<Cards>
  <Card href="/docs/cli/commands/start" title="start" description="Start a fresh, independent agent sandbox from a spec's own snapshot." />

  <Card href="/docs/cli/commands/prompt" title="prompt" description="Send one prompt to a running sandbox and print the reply." />

  <Card href="/docs/cli/commands/spawn" title="spawn" description="Spawn a child agent from a running session's own live sandbox." />

  <Card href="/docs/cli/commands/steer" title="steer" description="Redirect a running session at its next turn boundary, without restarting it." />

  <Card href="/docs/cli/commands/agents" title="agents" description="List running agent sessions, cross-checked against the live control plane." />

  <Card href="/docs/cli/commands/stop" title="stop" description="Stop a sandbox by ID." />

  <Card href="/docs/cli/commands/logs" title="logs" description="Print ledger events for a session." />
</Cards>

## Recursive spawning (`alineo spawn`) [#recursive-spawning-alineo-spawn]

A spec's `spawnDepth` is a nesting-depth budget — required for `alineo spawn` to be allowed from inside a session at all. Each spawn force-decrements it (`current - 1`) into the child's env; `0` means no budget left, `undefined` means spawning was never enabled for that spec.

`maxAgents` is a separate, optional ceiling on total descendants for one lineage, independent of nesting depth. Unset means uncapped. **Not** coordinated across sibling branches spawned in parallel — it's a per-lineage counter, not a global one.

```json
{
  "name": "orchestrator",
  "harness": "pi",
  "spawnDepth": 2,
  "maxAgents": 10
}
```

See [alineo spawn](/docs/cli/commands/spawn) for the full mechanics.

## Pi extension [#pi-extension]

`pi install npm:alineo-cli` installs the alineo extension into [Pi](https://pi.ai) at user scope. Once installed, any Pi session:

* Bootstraps `alineo` automatically on first use (installs it, runs `alineo init`) — no manual setup.
* Gets `alineo start`/`alineo spawn`/`alineo steer` CLI syntax injected into its own guidance, dynamically chosen based on whether the current session is itself running inside a alineo-managed sandbox.

The extension source lives at `pi-extension/alineo.ts` in the `alineo` npm package.