> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ziro-agent.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Headless runs

> Single-turn output with -p and --json, and the fail-closed rule for approval interrupts.

This page will cover running Ziro without an interactive session: `-p "message"`
for one turn of plain-text output, a bare `-p` reading the message from stdin, and
`--json` for the machine-readable line. The JSON contract is the same one
`python -m app.cli.chat_once` emits, so a script can move between the two without
changing its parser. Headless runs never open the setup wizard or the session
pickers: the user resolves from `--user` or the last-used user, and a missing
user or missing API key fails fast to stderr with a pointer at `ziro setup`.

The important behavioural rule is fail-closed: a headless run has no human to ask,
so any permission interrupt that would raise an approval prompt is **auto-denied**
rather than blocking. Plugin trust behaves the same way: dangerous grants stay
inert in a headless run regardless of what is recorded.

<Note>
  This page is in progress. See the [chat-once reference](/reference/chat-once) for
  the flag list and [CLI reference](/reference/cli) for the dispatch rule.
</Note>

<Columns cols={2}>
  <Card title="chat_once" icon="book-open" href="/reference/chat-once">
    Flags, JSON fields, and the background job queue.
  </Card>

  <Card title="Background jobs" icon="list-checks" href="/guides/background-jobs">
    Submitting and polling work that outlives one turn.
  </Card>
</Columns>