CLI reference

raw [options] [task]
raw dashboard [options]
raw vars list|get NAME
raw config init|list
raw package list|inspect|validate|pack|export|install|update|remove|link|fork
raw agent add NAME --from pkg/ALIAS/agents/EXPORT --model MODEL_ALIAS
raw sessions [--all] [--before CURSOR]
raw sessions show ID [--before CURSOR]
raw sessions panels ID [PANEL] [--all] [--json]
raw sessions delete ID
raw sessions stats
raw --acp --stdio
raw --acp --ws --host 127.0.0.1 --port 8765

Run raw --help for the summary. Run raw --version for the version.

Running a task

Form	Behavior
raw "task"	Runs one turn with the default agent, then exits.
raw	Opens the saved REPL on an interactive terminal.
raw --interactive	Opens the saved REPL.
raw -- "-task"	-- ends flag parsing, so the task can begin with -.
raw --continue ["task"]	Resumes the most recent unexpired session in the current directory.
raw --resume ID ["task"]	Resumes one session in the directory it was saved in. Prints that directory.

With a task, stdout contains only the answer. Status lines, tool activity, and the resume command go to stderr.

Options

Option	Default	Description
--agent NAME	default_agent, or RAW_AGENT	Selects a configured agent.
--config PATH	The global config file	Uses one alternate config file. An explicit file that does not exist is an error.
--system-prompt TEXT	None	Replaces the system prompt with this text.
--max-steps N	10000	Maximum number of model requests in one turn.
--max-output-bytes N	8192	Maximum size of a tool result sent to the model.
--request-timeout-ms N	120000	Deadline for one model or MCP request.
--display MODE	normal	Terminal detail: compact, normal, or verbose.
--reasoning MODE	summary	Reasoning text: hidden, summary, or full.
--color MODE	auto	auto, always, or never.
--icons MODE	auto	auto, unicode, or ascii.
--theme NAME	terminal	terminal, dark, or light.
--interactive	Off	Starts the REPL.
--continue	Off	Resumes the latest session in this directory.
--resume ID	None	Resumes one session by ID.
-y, --auto-approve	On	Compatibility alias. Tools already run automatically. It does not override an ask rule.
--help, --version		Shows help or the version.

Numeric flags override the matching RAW_* environment variable. Those override the agent’s values, and the agent’s values override the built-in defaults.

Session options

Option	Applies to	Description
--all	raw sessions, raw sessions panels	Lists sessions from every directory, or includes closed panels.
--before CURSOR	raw sessions, raw sessions show	Shows the next older page. Use the next: cursor printed by the previous page.
--json	raw sessions panels	Prints JSON instead of text.

Subcommands

raw dashboard

Starts the local browser app. The server runs in the foreground and binds to 127.0.0.1.

Option	Default	Description
--port PORT	8787	Port to listen on. 0 picks a free port.
--no-open	Off	Does not open a browser. The launch URL is still printed.
--config PATH	The global config file	Config the dashboard manages.
--agent NAME	default_agent	Agent preselected for new chats.

Ctrl-C stops the server and cancels its work.

raw vars

Command	Output
raw vars list	One JSON object with the selected variables’ metadata. No values, no provider runs.
raw vars get NAME	One JSON object: name, value, observed_at, cached.

Only --config and --agent apply. See Variables.

raw config

Command	Behavior
raw config init	Creates the config file with an agent named raw. Never overwrites an existing file.
raw config list	Prints one tab-separated line per agent, then exits.

raw config init writes the file with mode 0600. It selects the starter tools, the seven setup skills, and the now variable for the raw agent. The starter agent does not select hooks.

raw config list checks the config without resolving credentials, running providers, or starting MCP servers. It never prints API keys or prompt text. Each line has these fields, in order:

Field	Meaning
1	Agent name
2	Model alias
3	Upstream model_id
4	Provider
5	Method
6	Endpoint, with credentials removed
7	vision=
8	tools=
9	skills=
10	rules=
11	vars=
12	trigger= automatic compaction threshold, or manual
13	from= package reference, if bound
14	error= if a package binding is broken

raw package

Package commands print JSON and run without a model credential or a session database.

Command	Options	Description
list		Lists installed aliases.
inspect PATH		Reports the components, inputs, and requirements of a folder or .rawpkg.
validate PATH		Checks a folder or .rawpkg without running its code.
pack DIR --out FILE	--out	Writes a .rawpkg archive.
export	--agent NAME, --name @owner/name, --version X.Y.Z, --out DIR	Exports a configured agent as a package folder.
install PATH --as ALIAS	--as	Installs a folder or .rawpkg under an alias.
update ALIAS --from PATH	--from	Replaces an alias with a new archive or folder.
remove ALIAS		Removes an alias. Refused while an agent refers to it.
link DIR --as ALIAS	--as	Registers an editable folder under an alias.
fork ALIAS --out DIR	--out	Copies an installed package into an editable folder.

All package commands accept --config PATH to choose the config whose installation record they update.

raw agent add

raw agent add NAME --from pkg/ALIAS/agents/EXPORT --model MODEL_ALIAS [--inputs FILE]

Writes one agent to the selected config, bound to a package agent and your model alias. --inputs FILE reads the input values from a JSON object. See Packages.

raw sessions

Command	Description
raw sessions	Lists one page of sessions in the current directory. Prints next: when there are more.
raw sessions show ID	Shows the newest 20 visible items of a session. Needs no model credential.
raw sessions panels ID [PANEL]	Prints the latest state of a session’s tool panels.
raw sessions delete ID	Permanently deletes one inactive session.
raw sessions stats	Reports database, WAL, and payload storage, plus the largest sessions.

Listing and viewing do not renew a session’s expiry. See Configuration for sessions.retention_days.

raw --acp

Command	Description
raw --acp --stdio	Serves ACP over stdin and stdout. This is the default when you pass only --acp.
raw --acp --ws --host HOST --port PORT	Serves ACP over a WebSocket. Defaults are 127.0.0.1 and 8765. The host must be loopback: 127.0.0.1, ::1, or localhost.

See ACP and parent agents.

REPL commands

These five commands must be the whole line.

Command	Action
/compact	Summarizes older context with the selected model.
/clear	Closes the current session and starts a new one. The old history stays available.
/stats	Shows cumulative request, token, and cache usage. Makes no model request.
/panels [ID] [--all]	Prints the text of open tool panels. --all also lists closed panels.
/exit	Closes the session.

Any other line starting with / is sent to the model as ordinary text.

Ctrl-C cancels active work. In the REPL it returns to the prompt, and a second Ctrl-C while idle exits. Ctrl-D (end of input) cancels active work and exits.

Environment variables

Variable	Effect
RAW_AGENT	Agent name, used when --agent is absent.
RAW_SYSTEM_PROMPT	System prompt text. Overrides the agent’s prompt.
RAW_MAX_STEPS	Same as --max-steps.
RAW_MAX_OUTPUT_BYTES	Same as --max-output-bytes.
RAW_REQUEST_TIMEOUT_MS	Same as --request-timeout-ms.
RAW_BASH_PATH	Path to the Bash executable, if Bash is not on PATH.
XDG_CONFIG_HOME	Changes the config directory. Default ~/.config.
XDG_STATE_HOME	Changes the session store location. Default ~/.local/state.
XDG_DATA_HOME	Changes where installed package artifacts are stored. Default ~/.local/share.
NO_COLOR	Turns off colors in auto color mode.

The variables RAW_PROVIDER, RAW_MODEL, RAW_BASE_URL, and RAW_PROFILE were removed. If any of them is set, even to an empty value, Raw exits with an error. Select an agent instead.

Exit codes

Code	Meaning
0	The turn completed, or the informational command succeeded.
1	A runtime or provider error.
2	Invalid arguments or config.
3	The turn reached --max-steps.
130	The turn was cancelled by the user.

A tool error that the model handles does not change the exit code.

Note

Redirected stdout contains the answer only. Redirecting stderr separately keeps the status lines out of your output file.