# Headless Mode [Docs](https://www.rightnowai.co/docs) / [RightNow Agent](https://www.rightnowai.co/docs/agent) / [Headless Mode](https://www.rightnowai.co/docs/headless) Updated 2026-10-17 > **Release status** > > RightNow Agent, the terminal coding agent, is paused. Its guides stay online as reference. Headless mode runs one prompt, writes the result to standard output, and exits. On this page - [Run a prompt](https://www.rightnowai.co/docs/headless#one-shot) - [Prompt input](https://www.rightnowai.co/docs/headless#input) - [Output formats](https://www.rightnowai.co/docs/headless#output-formats) - [Permissions](https://www.rightnowai.co/docs/headless#permissions) - [Exit codes](https://www.rightnowai.co/docs/headless#exit-codes) - [Options](https://www.rightnowai.co/docs/headless#options) - [Script against evidence](https://www.rightnowai.co/docs/headless#evidence) ## Build from source The reference below describes a build from the pinned agent source. ### Run a prompt Check the active provider, model, and credential with `rightnow auth status --json`. The shipped default provider is RunInfra ([Providers](https://www.rightnowai.co/docs/providers)). **Text** ```text rightnow -p "Review this workspace for broken imports" ``` `--print` is an alias of `-p`, and `--cwd` sets the working directory: **Text** ```text rightnow --print "Summarize the API" --cwd . ``` ### Prompt input Pass exactly one of `-p`, `--prompt-json`, or `--prompt-file`. Piped standard input is not read. Save content blocks as `prompt.json`: **JSON** ```json [ { "type": "text", "text": "Summarize this workspace" } ] ``` **Text** ```text rightnow --prompt-file ./prompt.json ``` Any file that does not end in `.json` is sent as plain text. ### Output formats **Text** ```text rightnow -p "List the changed modules" --output-format json ``` **plain** Final text (default). A run with verified effects ends with a `Headless completed with verified effects:` line. **json** One object with `text`, `stopReason`, `sessionId`, and `requestId`, plus `outcome` and `effects`, `thought`, usage fields, and `structuredOutput` (or `structuredOutputError`) when present. **streaming-json** One RightNow Agent event per line for text, thoughts, tool calls, usage, plans, completion, and errors. **streaming-messages-json** Messages API `stream-json` lines, from a `system` init record to a final `result` record. `--json-schema` takes a JSON object and returns the parsed reply in `structuredOutput`. #### Windows (PowerShell) **PowerShell** ```powershell rightnow --% -p "Return the package name" --json-schema "{\"type\":\"object\",\"properties\":{\"package\":{\"type\":\"string\"}},\"required\":[\"package\"]}" ``` #### macOS (zsh) **Text** ```text rightnow -p 'Return the package name' --json-schema '{ "type": "object", "properties": { "package": { "type": "string" } }, "required": ["package"] }' ``` #### Linux (bash) **Text** ```text rightnow -p 'Return the package name' --json-schema '{ "type": "object", "properties": { "package": { "type": "string" } }, "required": ["package"] }' ``` ### Permissions Headless mode never opens an approval prompt. A tool call that still needs a human decision fails closed with exit code `20`. Add a narrow `--allow` rule or use `--permission-mode auto`. > **Warning: Always-approve is not a sandbox** > > `--always-approve` and its aliases approve every offered tool call. Use them only in a trusted workspace and host; deny rules, hooks, and administrator locks still take precedence. ### Exit codes **0** Completed. An action request also needs at least one completed action tool call. **1** Startup, configuration, authentication (including failures during a prompt), output, or another unclassified failure. **2** CLI usage or argument error, or startup refused by managed requirements. **20** Refused, cancelled, or blocked by permission policy. **21** An action request produced no completed actionable tool, or human input was required. **22** An executable tool failed without recovery, execution stayed incomplete, or a turn, loop, model-call, spend, or time limit was reached. **23** The model backend or ACP initialization failed, or an established ACP connection closed before the turn completed. **101** The CLI thread could not be joined. **129** Unix shell status for SIGHUP (terminal hangup). **130** Unix shell status after SIGINT (Ctrl+C). **143** Unix shell status after SIGTERM. Retry notices go to standard error for `plain` and `json` output. Streaming formats emit structured retry events. Without an environment or model override, the generic retry budget allows at most 14 retries after the first attempt, with about 5.5 minutes of backoff. An interrupted run does not roll back file changes. ### Options #### Prompt **-p, --single, --print <PROMPT>** Send one prompt, print the result, and exit. **--prompt-json <JSON>** Provide a nonempty array of ACP content blocks, or an ACP wrapper object. **--prompt-file <PATH>** Read UTF-8 input from a file; `.json` files are parsed as ACP content blocks. **--verbatim** Send the prompt as written, without `` wrapping or large-prompt truncation. #### Model and instructions **-m, --model <MODEL>** Select a model-entry ID from the catalog, or use `provider/model`. **--reasoning-effort, --effort <EFFORT>** Set the reasoning effort for a reasoning model. **--rules, --append-system-prompt <TEXT>** Append extra rules to the system prompt. **--system-prompt-override, --system-prompt <PROMPT>** Replace the system prompt. #### Output **--output-format <FORMAT>** Choose `plain`, `json`, `streaming-json`, or `streaming-messages-json`. **--include-partial-messages** Add incremental `stream_event` records only with `streaming-messages-json`. **--json-schema <SCHEMA>** Constrain the response with a JSON Schema; `plain` output changes to `json`. #### Tools and agents **--agent <NAME>** Select an agent name or definition file. **--agents <JSON>** Supply inline subagent definitions as JSON. **--tools <TOOLS>** Limit the built-in tool set to a comma-separated list. **--disallowed-tools <TOOLS>** Remove built-in tools from a comma-separated list. **--disable-web-search** Disable both web search and web fetch tools. **--max-turns <N>** Limit agent turns to a positive integer. #### Permissions **--permission-mode <MODE>** Choose `default`, `acceptEdits`, `auto`, `dontAsk`, `bypassPermissions`, or `plan`. **--allow, --allowedTools <RULE>** Add comma-separated permission allow rules. **--deny, --disallowedTools <RULE>** Add comma-separated permission deny rules. **--always-approve, --yolo, --dangerously-skip-permissions** Approve offered tool permissions automatically. **--sandbox <PROFILE>** Select a filesystem and network sandbox profile; also configurable with `RIGHTNOW_SANDBOX`. #### Sessions **-r, --resume <ID\_OR\_TITLE>** Continue a stored session. Each run starts a new session otherwise. **-c, --continue** Continue the most recent session for the working directory. **-s, --session-id <UUID>** Start a new session with this unused UUID; with `-r` or `-c` it needs `--fork-session`. **--fork-session** With `-r` or `-c`, write the history to a new session ID. #### Directory and background work **--cwd <PATH>** Use PATH as the working directory. **--no-wait-for-background** Return after the first turn instead of waiting for background work. **--background-wait-timeout <SECS>** Wait for background work for at most this many seconds (default 600; minimum 1). Conflicts with `--no-wait-for-background`. #### Ignored by headless **--no-plan, --no-subagents** Interactive only; not passed to headless execution. **--experimental-memory, --no-memory** Not applied; memory follows `config.toml` and `RIGHTNOW_MEMORY`. **--no-alt-screen, --minimal, --fullscreen** Interactive display only; headless output is unchanged. **-w, --worktree \[NAME\]** Does not create a worktree; prepare the directory first. ### Script against evidence Treat the exit code and the structured output as the result, not a confident sentence from the model. For action prompts, json and streaming output list the observed effects. The diagnostic log lives at `/logs/unified.jsonl` inside the effective product home ([Configuration](https://www.rightnowai.co/docs/configuration)). Continue with [Troubleshooting](https://www.rightnowai.co/docs/troubleshooting), [Sessions](https://www.rightnowai.co/docs/sessions), [Permissions and Safety](https://www.rightnowai.co/docs/permissions), [Receipts](https://www.rightnowai.co/docs/receipts), or [Agent Mode](https://www.rightnowai.co/docs/agent-mode) for ACP clients. ## Next task [Verify the recorded file effects](https://www.rightnowai.co/docs/receipts) before relying on an automated run. ## Previous [Keyboard Shortcuts](https://www.rightnowai.co/docs/keyboard-shortcuts) ## Next [Sessions](https://www.rightnowai.co/docs/sessions)