| flag | does |
|---|---|
-p, --prompt QUERY | run one query headlessly and print the answer to stdout |
-q, --query QUESTION | one-shot query for pipes: only the final answer on stdout; progress and a recorded: replay receipt on stderr; the run auto-exports |
--json | with -p: a structured JSON result (answer, plan, tools, tokens, timing, gates) |
--export FILE | with -p or -q: write the run's export record to FILE after the turn |
--yolo | open the approval gate for the whole run — the same view as /policy open |
--replay FILE | render an exported run record offline, then exit |
--version | print the version |
The CLI is strict: an unknown flag exits 2 instead of silently launching the chat loop.
::-p vs -q
Both run the same headless turn — same engine loop, same deny-by-default gate, same trace recording. -p prints the answer (or, with --json, a machine-readable result whose gates record says which calls were prompted and denied). -q is the pipe-friendly rendering: stdout carries only the final synthesized answer, step-line progress goes to stderr, and the run auto-exports to logging/exports/ so the closing recorded: saturn --replay <file> line names a command that actually replays the run offline. A completed run exits 0; errors emit JSON with status: "error" under --json and exit 1.
saturn -p "what changed in local LLMs this week?"
git diff | saturn -p "review this change"
saturn -q "summarize notes.md" > summary.txt
saturn -p "..." --json --export run.json::the gate with no human present
Headless runs deny gated tools by default — there is nobody at the gate to say yes — and the answer discloses what was denied. --yolo opens the gate for the run, and that choice is on the record too. Piped stdin attaches to the turn and is scanned like an @file attachment.
note
The landing page's gate figure is a real headless run: the model planned write_file, the gate denied it, and nothing ran.