> ## 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.

# chat_once

> Single-shot JSON invocation, plus the background job queue via --submit and --status.

This page will document `python -m app.cli.chat_once`, the single-shot entry point
built for programmatic callers. It covers `--user`, `--thread`, `--message`,
`--agent`, `--flavour`, and the repeatable `--attach`, along with the JSON object
printed on stdout. It also covers the two background-queue flags: `--submit`
enqueues the message as a job and prints the job JSON, and `--status <job-id>`
polls one job while `--status all` lists every job for the user. Jobs are mirrored
into the store, so they survive a restart and can be recovered.

`chat_once` shares the slash-command registry with the interactive front ends, so
it recognizes commands and the `/agent`, `/model`, and `/thread` prefixes. It is
text-only (voice is not available) and it auto-denies any permission interrupt,
because there is no human in the loop.

<Note>
  This page is in progress. See [headless runs](/interfaces/headless) for the shared
  JSON contract and [background jobs](/guides/background-jobs) for the worker queue.
</Note>

<Columns cols={2}>
  <Card title="Headless runs" icon="cpu" href="/interfaces/headless">
    The same contract from `python -m app.main -p --json`.
  </Card>

  <Card title="Background jobs" icon="list-checks" href="/guides/background-jobs">
    `queue_policy.yaml` and the worker pool.
  </Card>
</Columns>