alineo steer

bunx alineo-cli steer <sandbox-id> <message> [--spec <path>]

Arguments

Argument	Description
`sandbox-id`	The target's sandbox ID, as printed by `alineo start`/`alineo spawn`. Required.
`message`	The steering instruction. Required.

Flags

Flag	Description
`--spec <path>`	The target's agent spec, if you have it locally. Optional — see Notes.

What it does

Connects to the target with Alineo.reattach() and calls agent.steer(message).

reattach() binds to the bridge already running in the target sandbox without restarting it — unlike alineo prompt, which uses Alineo.resume() and would abort a turn in progress. That's what makes steer safe to use on an agent that's busy.

When the message lands

The message is delivered after the tool calls in the target's current turn finish, and before its next model call. It does not interrupt a tool call that is already running. To stop an agent immediately regardless of what it's doing, use alineo stop.

Example

A parent session that forked a child can redirect it from its own bash tool, using the sandboxId from alineo spawn --json:

bunx alineo-cli spawn my-session ./agents/worker.json \
  --prompt "Audit src/ for security and performance issues" --json
# {"name":"fork-my-session-a1b2c3","sandboxId":"6a69afcb-7a00-437a-9819-e032022cc736","reply":null}

bunx alineo-cli steer 6a69afcb-7a00-437a-9819-e032022cc736 \
  "Security only — drop the performance review."

[alineo] steered fork-my-session-a1b2c3 (6a69afcb-7a00-437a-9819-e032022cc736)

Steering children well

When a parent is redirected, it's usually better for the parent to decide what each child should now do than to send every child the same instruction. A child working on one slice of the task needs a message about its slice — and some children may be better stopped with alineo stop, or replaced with a fresh alineo spawn.

The Pi extension includes this guidance in the system prompt of sessions running inside a sandbox.

Notes

No spec is required. The target's name is looked up from the sandbox list for the log line; pass --spec only if the target's real spec is on hand.
Sandboxes are addressed by ID, not name, for the same reasons as alineo prompt.
For steering agents managed by the alineod daemon, use its POST /agents/:id/steer route instead.