How the AxiOwl CLI Works With Standard Input

How the AxiOwl CLI Works With Standard Input

Standard input matters in AxiOwl because agent messages are often not short, shell-friendly strings. They can include multiple paragraphs, quotes, JSON fragments, command output, Markdown, or code. The AxiOwl CLI supports a standard-input path so that operators can send the exact body they intend without fighting command-line quoting rules.

In the current Windows desktop CLI implementation, the public forms are:

axiowl send --to <agent> --body <message>
axiowl send --to <agent> --stdin
axiowl create --provider <provider> --name <agent> [--body <message> | --stdin]

The important detail is that --stdin is not a separate message type. It is another way to fill the same body field that --body fills. After the CLI collects the text, AxiOwl sends it through the normal message pipeline.

Sources read

Why AxiOwl Uses --stdin

Shell arguments are fine for one-line messages:

axiowl send --to "Target Agent" --body "Please check the latest build status."

That form becomes fragile when the message contains newlines, nested quotes, JSON, or copied terminal output. PowerShell can handle complex strings, but the quoting is still easy to damage during copy and paste. AxiOwl's standard-input form gives the shell one simple job: pass a stream of bytes into the CLI.

The project architecture note describes this as the safe path for multiline text, quotes, JSON, code, lists, and other content that must not be damaged by shell quoting:

@'
<full message>
'@ | axiowl send --to "Target Agent" --stdin

That command shape matches the current CLI usage text in apps/windows-desktop/src/cli.cpp. For send, --stdin is accepted alongside the same routing options as --body, including --to, --from, --from-node, --strict, --run-id, and --delivery-method.

What Happens Inside the CLI

The implementation is deliberately simple. In run_send, the CLI first reads normal options:

Then the stdin flag is checked. If --stdin is present, the CLI replaces the request body with the result of read_all_stdin().

The helper itself is direct C++ stream handling:

std::string read_all_stdin() {
    std::ostringstream out;
    out << std::cin.rdbuf();
    return out.str();
}

That means AxiOwl reads the entire standard-input stream until EOF and stores it as one string. It does not parse the content as JSON. It does not split the content into lines. It does not treat stdin as a special provider instruction. The stream becomes the original message body.

One practical consequence is precedence: if a caller supplies both --body and --stdin, the current implementation reads --body first and then replaces it with stdin content when the --stdin flag is present. Operators should use one or the other so the command is unambiguous.

The Body Still Goes Through the Normal Pipeline

After standard input is read, axiowl send constructs a MessageRequest and passes it into MessagePipeline::send.

The pipeline is where AxiOwl enforces the real send contract:

  1. A target is required.
  2. A non-empty message body is required after trimming.
  3. A sender identity must resolve, either from the registry or from explicit sender options.
  4. The target must resolve to a sendable registry row.
  5. AxiOwl builds the final visible provider body.
  6. The delivery worker starts the provider handoff.
  7. The CLI prints a receipt that does not pretend a provider replied.

This is why --stdin is safe to use for complex messages. It only changes how the original body enters AxiOwl. It does not bypass sender resolution, target resolution, registry checks, final visible body construction, activation checks, or delivery evidence logging.

If stdin is empty, or contains only whitespace, the send pipeline rejects it with the same rule used for --body: the message body is empty.

create --stdin Works the Same Way

The create command also supports standard input:

@'
Initial instructions for the new provider chat.
Include multiple lines, quoted text, and command output safely.
'@ | axiowl create --provider codex --name "New Agent" --from "Sender Agent" --stdin

In run_create, the CLI first reads --body into request.initial_message. If --stdin is present, it replaces that initial message with the complete standard-input stream.

After that, create-specific checks apply. --provider and --name are required. If an initial message is present, the current Windows desktop implementation treats most providers differently from antigravity_cli: for normal raw CLI create with an initial message, AxiOwl requires sender identity before it builds the final visible body. The error message tells the operator to use the MCP create tool from the provider host for an MCP test, or pass --from explicitly for a CLI-only test.

That matters because the initial message is not just dropped into a provider blindly. For most providers, AxiOwl wraps it using the same final-visible-body policy used by sends, including sender identity and reply instructions. For antigravity_cli, the implementation records a raw provider create prompt policy instead.

What Stdin Does Not Mean

Standard input is not an AxiOwl scripting language. It is not a batch format. It is not a JSON API. It does not imply that the target provider accepted the message or that the provider replied.

The Windows CLI receipt text is careful about this boundary. A handoff receipt can mean the MCP or CLI request was accepted by AxiOwl. Provider delivery, provider wake-up, and provider reply are not implied unless the selected path reports that provider status explicitly. The user docs say the same thing: accepted_by_axiowl means AxiOwl accepted the message and handed it to the delivery layer; it does not prove the target provider displayed or processed the message.

That boundary is part of the reason stdin support is useful. Operators can send rich input without changing the evidence model. The receipt still says what AxiOwl can prove, and the logs still record the body policy, target, provider, and delivery stage.

Scope Note: Standard axiowl CLI vs. Linux Provider Tools

The standard-input behavior described here is verified in the Windows desktop axiowl CLI source. The Linux provider-specific tool in apps/linux-desktop/axiowl-linux-x86_64/src/main_linux.cpp is a different command surface. Its current usage strings advertise provider-specific commands such as:

axiowl-linux codex-cli send --to <name-or-id> --body <text> [--sender <name>]
axiowl-linux opencode-cli send --to <name-or-id> --body <text> [--sender <name>]
axiowl-linux antigravity-cli send --to <name-or-id> --body <text> [--sender <name>]

Those Linux provider commands should not be assumed to accept --stdin based on the Windows CLI behavior. The command syntax should be taken from the specific binary being used.

Practical Operator Pattern

Use --body for short one-line messages:

axiowl send --to "Build Review Agent" --from "Operator Agent" --body "Please review the latest build output."

Use --stdin when the message has structure:

@'
Please review this failure summary:

- Step: package build
- Exit code: 1
- Relevant output:
  "missing payload/axiowl.exe hash"

Return only the likely cause and the next command to run.
'@ | axiowl send --to "Build Review Agent" --from "Operator Agent" --stdin

That pattern keeps the operator command readable and keeps the message body intact. AxiOwl then treats the collected stdin body exactly like any other original sender content: it resolves the sender and target, builds the final visible provider message once, and records a receipt that reflects the proven handoff state.

Closing

AxiOwl's standard-input support is small by design. The CLI reads the stream, uses it as the body, and hands the request to the same pipeline used by normal sends and creates. That makes --stdin useful without making it magical: it is the reliable way to move complex text through the CLI while preserving AxiOwl's normal registry, sender identity, delivery, and receipt rules.

Image prompt:

Create a polished graphic image related to: how the AxiOwl CLI works with standard input.

Subject: a clean terminal window shape receiving a flowing input stream from a pipe into structured message blocks, with subtle connector lines showing the stream becoming one preserved message payload; no readable characters.
Style: halfway between a clean symbolic icon and a realistic product/technical illustration; professional SaaS/technical marketing style; crisp edges; high detail; no text; no logos.
Background: solid #00ff00 chroma key green screen background covering the full canvas edge to edge.
Restrictions: no owl, no axolotl, no birds, no animals, no mascot, no text, no watermark.

Tagged