Headless Basics
Headless mode runs caliban non-interactively: prompt in, output to stdout, exit. It is the right entry point for scripts, CI pipelines, and any context where there is no TTY.
The -p / --print flag
Pass -p (or the long form --print) with your prompt to run headlessly:
caliban -p "List the files in this directory"
Without -p, caliban checks whether stdin is a TTY. If stdin is not a TTY (i.e. you are in a pipe) or stdout is piped, caliban enters headless mode automatically. Pass --no-auto-print to suppress the automatic fallback if you need to control this explicitly.
Output formats
The --output-format flag selects what caliban writes to stdout:
| Format | What you get |
|---|---|
text (default) | The assistant's final reply as plain text |
json | A single JSON object — the final result frame — suitable for jq |
stream-json | NDJSON: one event frame per line as the run progresses |
# Plain text
caliban -p "Explain tokio" --output-format text
# Single JSON result
caliban -p "Explain tokio" --output-format json | jq '.result'
# NDJSON stream (tool calls, partial messages, final result)
caliban -p "Explain tokio" --output-format stream-json
The stream-json format is the richest: it includes a system/init frame first (active model, tools, MCP servers, settings sources), per-call tool_use and tool_result frames during the run, and a final type: result frame with token counts and cost. For full details see The stream-json Protocol.
Reading the prompt from stdin
Pass - as the prompt to read from stdin instead of the command line:
echo "What does this error mean?" | caliban -p -
cat error.log | caliban -p -
This is useful when the prompt is too long for a shell argument or is generated by another command.
Exit codes
Caliban follows sysexits.h conventions plus two additional signals:
| Code | Meaning |
|---|---|
0 | Success |
1 | Generic runtime error |
2 | Tool or assistant error |
64 | Bad flags (EX_USAGE) or malformed stream-json input |
66 | Missing input (EX_NOINPUT) — e.g. --resume names a non-existent session |
75 | --max-turns exceeded (EX_TEMPFAIL) |
78 | Configuration error — stdin over 10 MB, settings parse failure |
124 | Cancelled — SIGTERM or Ctrl-C from the agent loop |
130 | SIGINT reached the harness (second Ctrl-C) |
137 | --max-budget-usd exceeded |
CI scripts can distinguish budget exhaustion (137) from a real failure (1/2) without parsing stdout.
When to use headless
Use -p when you know the task up front and want a single answer: one-shot summaries, code review scripts, CI checks, shell pipelines. Use the interactive TUI when you want a back-and-forth conversation, need to inspect tool calls as they run, or want to adjust the permission mode mid-session.
Permissions in headless mode
There is no modal in headless mode. Any rule that would normally show the Ask dialog instead becomes a hard deny. Read-only tools (Read, Glob, Grep) are allowed by default, but write and shell tools are not. To grant write access, pick one:
# Auto-allow file edits
caliban -p "Fix the typo in README.md" --permission-mode acceptEdits
# Narrow allow rule (repeatable)
caliban -p "Run tests" --allow 'Bash:cargo test*'
# Allow everything that would normally Ask (use sparingly)
caliban -p "..." --auto-allow
For depth on permission modes and rule syntax, see Print Mode.