Headless Mode

Run a prompt

Check the active provider, model, and credential with rightnow auth status --json. The shipped default provider is RunInfra (Providers).

rightnow -p "Review this workspace for broken imports"

--print is an alias of -p, and --cwd sets the working directory:

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:

[
  { "type": "text", "text": "Summarize this workspace" }
]

rightnow --prompt-file ./prompt.json

Any file that does not end in .json is sent as plain text.

Output formats

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)

rightnow --% -p "Return the package name" --json-schema "{\"type\":\"object\",\"properties\":{\"package\":{\"type\":\"string\"}},\"required\":[\"package\"]}"

macOS (zsh)

rightnow -p 'Return the package name' --json-schema '{ "type": "object", "properties": { "package": { "type": "string" } }, "required": ["package"] }'

Linux (bash)

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.

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