Command Reference

Every subcommand, flag and environment variable. oasis-agent --help prints the same list with defaults resolved for your machine.

Subcommands

Command	Needs an endpoint	Purpose
(none)	Yes	Run a turn: interactive REPL, one-shot, or background agent
serve	Yes	Speak the control protocol
connect <path>	No	Relay stdin/stdout to a socket the agent is serving
check	No	Run conformance checks
audit	No	Produce an audit report
sessions	No	List saved conversations
agents	No	List background agents
version	No	Print the version
install [target]	No	Install a version and point the launcher at it
update	No	Update to the newest published version
uninstall	No	Remove the installation, after listing what will go
doctor	No	Report on the installation
setup	No	Ask for the model endpoint and save it

Commands marked "needs an endpoint: No" work on a binary that has never been pointed at a server. That is deliberate: choosing a conversation to resume, or assessing a machine, must not require a model.

serve

Flag	Purpose
--stdio	Speak the protocol on stdin/stdout
--unix <path>	Listen on a unix socket instead, created 0600. Conflicts with --stdio
--allow-host-mutations	Answer the four host-reshaping methods: config.set, checks.run, audit.run, update.apply

check

Flag	Default	Purpose
--module <id>	all	Only checks in this module, e.g. preempt-rt
--check <id>	all	One check by id, e.g. l3.rt.preempt-rt-active
--subject <s>	device	One of repo, artefact, device, endpoint
--target <t>	this machine / cwd	A hostname, a path, an address
--catalogue <dir>	—	Descriptor TOML layered over the built-in catalogue
--format <f>	json	Output format. JSON is the only one
--list-modules	—	List the check modules this build has, then exit

audit

Flag	Default	Purpose
--profile <p>	all	all, or one module name
--subject <s>	device	One of repo, artefact, device, endpoint
--target <t>	this machine / cwd	A hostname, a path, an address
--catalogue <dir>	—	Descriptor TOML layered over the built-in catalogue
--list-profiles	—	List the profiles this build can run, then exit

sessions

Flag	Default	Purpose
--here	off	Only conversations from this directory
--limit <n>	20	How many to print

agents

Flag	Purpose
--all	Include finished and failed agents
--cwd <dir>	Only agents dispatched under this directory
--stop <id>	Stop one by id
--json	Print as a JSON array and exit

version

Flag	Purpose
-v, --verbose	Also print the commit and build date

Line 1 of the output is the bare version string. That is the contract scripts parse.

install

oasis-agent install latest      # newest published version
oasis-agent install 0.4.2       # a specific version

stable is not accepted. There is no promotion tier and no channel to choose.

uninstall

Lists what it will remove and asks first. A launcher you wrote yourself is never touched.

Flag	Purpose
-y, --yes	Skip the confirmation. Required when stdin is not a terminal
--dry-run	Print what would be removed, then stop
--keep-audit	Keep ~/.oasis/audit.jsonl. On a customer device the record of every write the agent made may need to outlive the install

Mode selection

Flag	Mode
(none, stdin is a terminal)	Interactive REPL
--repl	Interactive REPL, forced
-p, --print [prompt]	One-shot. Omit the value to read from stdin
--bg, --background	Dispatch as a detached background agent
-r, --resume [id]	Resume a saved conversation
--log-file + --response-fifo	Harness mode: driven by an embedding program

serve is the sixth mode; it is a subcommand rather than a flag.

Endpoint and model

Flag	Environment	Default
--base-url <url>	OASIS_BASE_URL	required
--model <name>	OASIS_MODEL	qwen
--api-key <key>	OASIS_API_KEY	none
--thinking-profile <p>	OASIS_THINKING_PROFILE	off. One of off, creative, coding
--no-probe	—	Skip the startup /props probe

Sandbox and permissions

Flag	Environment	Default
--cwd <dir>	OASIS_CWD	current directory
--mode <mode>	OASIS_MODE	manual. One of plan, manual, accept-edits, auto, dangerous
--plan	—	Shorthand for --mode plan
--skip-permissions	—	Approve every waivable request. Does not waive hard-stop tools
--actor <string>	OASIS_ACTOR	none. Stamped on every write in the audit trail

Context and compaction

Flag	Environment	Default
--context-window <n>	OASIS_CONTEXT_WINDOW	probed from /props, else 120 000
--max-prompt-tokens <n>	—	context-window − response-reserve
--response-reserve <n>	—	8 192

Tools and extensions

Flag	Environment	Purpose
--mcp-config <path>	OASIS_MCP_CONFIG	Load MCP servers at startup
--mcp-login	—	Run the interactive OAuth login for every configured HTTP server, then exit. Requires --mcp-config
--no-memory	—	No Memory tool and no memory briefing
--vision-capable	—	Required for ViewImage to do anything
--no-delegation-nudge	—	Suppress the hint to hand bulk reading to a subagent
--ethercat-acquire-bus <if>	—	Restrict EtherCAT acquisition to these interfaces. Repeatable

Harness mode

For embedding the agent in another program. See Harness Mode.

Flag	Purpose
--log-file <path>	Write the run's event stream to <path> as newline-delimited JSON. Requires --response-fifo
--response-fifo <path>	Named pipe the agent reads permission verdicts from. Requires --log-file
--persistent	Serve every turn from one process instead of one per turn. Requires both flags above
--history-file <path>	Conversation history to resume from, as an OpenAI-format JSON array

Session persistence

Flag	Purpose
--no-session	Do not save this conversation
-r, --resume [id]	Resume a saved conversation. A unique prefix of the id is enough

Terminal

Flag	Environment	Purpose
--no-color	NO_COLOR	Disable ANSI colour
--no-history	OASIS_AGENT_NO_HISTORY=1	Disable persistent input history
--no-diffs	—	Show file edits as plain results
--no-collapse	—	Show every tool result in full

Configuration and diagnostics

Flag	Purpose
--config <path>	Explicit config file path
--show-config	Print the resolved configuration and which layer supplied each value, then exit
--cwd-hint	Name the working directory in the system prompt

Environment variables

Variable	Equivalent flag
OASIS_BASE_URL	--base-url
OASIS_MODEL	--model
OASIS_API_KEY	--api-key
OASIS_CWD	--cwd
OASIS_MODE	--mode
OASIS_ACTOR	--actor
OASIS_CONTEXT_WINDOW	--context-window
OASIS_THINKING_PROFILE	--thinking-profile
OASIS_MCP_CONFIG	--mcp-config
NO_COLOR	--no-color
OASIS_AGENT_NO_HISTORY	--no-history

Update and capability variables

These have no flag. They override the matching config-file key, for CI and containers where writing a config file is awkward. See Configuration.

Variable	Effect
OASIS_DISABLE_AUTOUPDATER	Set to any value to turn off the background auto-update and the startup check. Same effect as auto_update: false
OASIS_RELEASE_HOST	Release store to resolve versions from. Overrides release_host
OASIS_NO_CAPABILITIES	Do not grant the EtherCAT capabilities during an install. Same effect as grant_capabilities: false
OASIS_DEBUG	Set to any value to print the server probe result to stderr at startup

Path variables

Variable	Overrides
OASIS_ROOT	The installation root, ~/.oasis
OASIS_INSTALL_DIR	The launcher directory, ~/.local/bin
OASIS_AUDIT_FILE	The audit log, ~/.oasis/audit.jsonl
OASIS_MEMORY_DIR	The memory store
OASIS_MCP_TOKEN_STORE	The MCP token cache

Exit codes

Code	Meaning
0	Success. For check and audit, nothing failed, including checks that could not be measured
1	The run failed: configuration error, unreachable endpoint, unrecoverable turn error
2	For check and audit: something failed the assessment
130	Cancelled (Ctrl+C or SIGINT)

A background agent that stopped because it needs approval exits with a distinct code and is listed as blocked by oasis-agent agents.

Slash commands

Available inside the interactive REPL. See Interactive REPL.

/help, /expand, /cost, /plan, /jobs, /background, /agents, /status, /config, /restart, /update, /exit