Headless Mode

Run a prompt

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 .

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

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.

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.

Output formats

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

rightnow -p "List the changed modules" --output-format json

--json-schema takes a JSON object and returns the parsed reply in structuredOutput. In PowerShell, --% keeps the escaped quotes intact.

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, output, or another unclassified failure, including authentication before the prompt.

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 connection failed before the turn completed, including an authentication error returned during the prompt.

130

Unix shell status after SIGINT (Ctrl+C).

143

Unix shell status after SIGTERM.

Provider retries are silent: a retryable provider error can take up to 15 attempts, about 5.5 minutes, before the run exits 23. An interrupted run does not roll back file changes.