09_Headless Mode

Headless Mode

Headless mode runs Imza without the terminal UI. It uses the same core, tools, providers, and permission logic as the TUI, with no modal front-end attached. Use it for scripts, CI, and one-shot questions.

imza --ask "summarize the architecture of this repo"

# Restore a session and continue it non-interactively
imza --session my-session-id --exec "finish the TODOs in NOTES.md"

--ask runs one Plan-mode turn (read-only: no edits or writes, shell limited to read-only commands); --exec runs one Build-mode turn subject to permissions. Final assistant content goes to stdout, diagnostics to stderr, and update banners are suppressed.

When stdout is a terminal, the answer is printed as formatted Markdown that fits your terminal width, and --update shows a live progress display. When stdout is a pipe or a file, both fall back to plain text, so scripts and log capture see the answer unchanged.

Grant Only What the Task Needs

Because no one is present to approve requests, unresolved approvals are returned to the model as rejections. Pre-install the permissions the task requires:

imza --exec "build the project and summarize the changes" \
  --allow-dir ../shared-assets \
  --allow-cmd "git status" "cmake --build" \
  --allow-mcp github \
  --allow-skill deploy-helper

• --allow-dir <dir> grants read access beneath that directory for the session.
• --allow-cmd accepts a bare program name (grants the whole program, every subcommand) or a quoted pair like "git status" (grants only that pair). Anything else is rejected at startup.
• --allow-mcp <id> lets the agent connect and use that MCP server without asking. Unknown ids stop startup.
• --allow-skill <name> activates that skill without asking, and makes its folder readable. Unknown names stop startup.

Notes for scripts:

• A $skill mention whose policy would ask is refused outright; pre-approve it with --allow-skill or set its policy to allow in /skills (see Skills).
• The interactive question tool is unavailable.
• Headless runs never emit terminal notifications.

Exit Codes

Code	Meaning
0	Success
1	Provider failure
3	A required permission could not be presented (unattended)
4	Tool failure
130	Interrupted

imza --exec "update the changelog for this release" \
    --allow-cmd "git log" "git diff" || {
  code=$?
  [ "$code" -eq 3 ] && echo "missing permissions" \
    || echo "imza failed with $code"
  exit "$code"
}

Startup grants go into the same in-memory store as TUI approvals: they last for the session (or the one-shot run) and are cleared on directory change or exit. They never override disabled tools or mode restrictions.

See Permissions.