One-shot & Scripting

One-shot mode runs a single prompt, prints the result to stdout and exits. It needs no terminal, so it works under cron, CI, systemd and any other place a script runs.

Running a prompt

oasis-agent -p "read src/main.rs and summarise the risky parts"

--base-url is required on every run

It has no default. Either configure it once with oasis-agent setup, export OASIS_BASE_URL, or pass --base-url explicitly. The examples below assume it is configured. See Configuration.

Omit the value to read the prompt from stdin:

echo "list every TODO comment" | oasis-agent -p
cat prompt.txt | oasis-agent -p

Not saving the conversation

oasis-agent --no-session -p "list all TODO comments in the codebase"

Nothing is written to ~/.oasis/sessions and the conversation cannot be resumed later. Use this for anything running on a schedule, or the session store fills with runs nobody will read.

Choosing how much autonomy

A one-shot run has nobody to answer a prompt. Decide up front what it may do.

Flag	Effect
--mode manual (default)	Stops at the first mutating tool. Safe, but a script that stops has not finished
--mode auto	Nothing routine is asked, inside the working directory
--plan	Read-only. Useful for analysis runs that must not change anything
--skip-permissions	Approves every waivable request, including Bash and paths outside the working directory

Hard-stop tools ask in every mode, so an unattended one-shot run will stall if the model reaches for one. Do not build a pipeline that depends on a PLC write happening without a human. See Permission Model.

Scoping the sandbox

oasis-agent --cwd /srv/plc-project --mode auto -p "run the tests and fix any failures"

--cwd sets the sandbox root for every file tool. In auto and accept edits, paths outside it still prompt, which is what makes --mode auto usable in a script.

Analysis without a model

Two subcommands run with no endpoint and no network at all:

oasis-agent check --module preempt-rt
oasis-agent audit --profile preempt-rt > evidence.txt

Exit code 0 means nothing failed, 2 means something did. See Conformance Checks and Audit Reports.

Example: a nightly conformance job

#!/bin/sh
set -eu

DATE=$(date +%F)

# Assessment first: no model, no network, deterministic output
oasis-agent audit --profile preempt-rt > "/var/log/oasis/rt-$DATE.txt"

# Then let the agent read the report and open a ticket if anything regressed
oasis-agent --no-session --mode auto -p "
Read /var/log/oasis/rt-$DATE.txt and compare it to yesterday's report in the
same directory. If anything regressed, write a summary to /var/log/oasis/regression-$DATE.md.
"

Exit codes

Code	Meaning
0	The turn completed
1	The run failed: configuration error, endpoint unreachable, or an unrecoverable turn error
2	For check and audit: something failed the assessment
130	The turn was cancelled (Ctrl+C, or SIGINT)

A background agent that stopped because it needs approval exits with a distinct code. See Background Agents & Jobs.

Machine-readable output

For structured events rather than prose, use the control protocol:

oasis-agent serve --stdio

It speaks JSON-RPC 2.0 over NDJSON and gives you every tool call, result and permission request as a typed event. See Control Protocol.

For a listing you can parse without a protocol, several subcommands take --json:

oasis-agent agents --json