Launcher and agent command help¶
This page is the --help text of every openadapt and openadapt agent
command, from openadapt 1.17.0, openadapt-flow 2.2.0, openadapt-agent 2.2.1. It's generated from each program's parser, and
CI fails when it differs from those versions. Commands explains
what each command is for, and All Flow commands lists
the openadapt flow commands. The launcher's research commands
(capture, eval, serve, and train) aren't listed.
openadapt agent ... runs openadapt-agent ...; the help text uses the
second name.
openadapt¶
openadapt¶
Usage: openadapt [OPTIONS] COMMAND [ARGS]...
OpenAdapt launcher for the openadapt-flow compiler.
Compile a demonstrated workflow into deterministic local replay. Healthy
runs make no model calls; configured checks can halt on ambiguity. Native
and remote substrates use platform-specific extras and permissions;
training/evaluation commands are research.
Quick Start (Python 3.10-3.12):
python -m pip install --upgrade openadapt
openadapt flow tutorial
Halt demo:
openadapt quickstart --break-it
Manual Demo Lifecycle:
openadapt flow demo-record --out rec
openadapt flow compile rec --out bundle --name demo
openadapt flow lint bundle
openadapt flow certify bundle --policy permissive
openadapt flow replay bundle
Lint lists the demo's coverage gaps. The demo has warnings, so `lint
--strict` exits 1 on it. The manual demo is runnable but not certified for
consequential work. Use `openadapt flow tutorial` for the effect-verified
first run.
Give an MCP client your compiled workflows:
openadapt agent serve --bundles DIR --allow-run
Options:
--version Show the version and exit.
--help Show this message and exit.
Commands:
flow Run the canonical demonstration compiler and governed runtime.
agent Serve compiled workflows to an MCP client (openadapt-agent).
capture Standalone local human GUI capture (optional [capture] extra).
connect Connect this computer to the signed-in OpenAdapt Cloud...
deploy Check this host and print the safe Flow/Desktop deployment...
doctor Check system requirements and dependencies.
eval Research: evaluate computer-use models on benchmarks.
quickstart Run a verified local tutorial against the bundled synthetic...
seal Check an OpenAdapt Seal offline: `openadapt seal verify...
serve Research: serve the training dashboard and viewer.
train Research: train ML models on captured demonstrations.
version Show version information for all packages.
openadapt agent¶
Usage: openadapt agent [OPTIONS]
Serve compiled workflows to an MCP client (openadapt-agent).
Every argument passes to openadapt-agent unchanged. Use this form where only
`openadapt` is on PATH, as after `uv tool install openadapt` or pipx, which
keep the `openadapt-agent` executable inside the tool's own environment.
Nothing is written to stdout before the bridge starts, so an MCP client can
launch this command directly.
Options:
--help Show this message and exit.
openadapt connect¶
Usage: openadapt connect [OPTIONS]
Connect this computer to the signed-in OpenAdapt Cloud workspace.
The browser creates a five-minute, one-use pairing. This command claims it
and saves the resulting workspace credential in the OS keychain. It cannot
execute arbitrary terminal commands or grant browser access to the shell.
Options:
--pairing TEXT Five-minute pairing code from Cloud settings
--uri TEXT Exact openadapt://connect desktop deep link
--host TEXT Cloud origin (default:
https://app.openadapt.ai)
--device-name TEXT Name shown for this computer
--destination-kind [openadapt-managed|customer-managed|local]
Trust class for the pairing destination
--trusted-host TEXT Exact allowed customer-managed origin
(repeatable)
--help Show this message and exit.
openadapt deploy¶
Usage: openadapt deploy [OPTIONS]
Check this host and print the safe Flow/Desktop deployment path.
This launcher command does not create another runtime or service manager. It
records no secret value, starts no connector, and does not treat an
incomplete preflight as a healthy deployment. It composes the installed Flow
connector, operator console, and repair lifecycle instead.
Options:
--backend [web|windows|macos|linux|rdp|citrix]
The execution surface that this customer
deployment will use. [default: web]
--secret-ref TEXT Secret reference only: env:NAME or
keychain:service/item. Never pass a secret
value.
--help Show this message and exit.
openadapt doctor¶
Usage: openadapt doctor [OPTIONS]
Check system requirements and dependencies.
Options:
--backend [web|windows|macos|linux|rdp|citrix]
Explain setup for one execution surface.
--help Show this message and exit.
openadapt flow¶
Usage: openadapt flow [OPTIONS]
Run the canonical demonstration compiler and governed runtime.
Every argument passes to openadapt-flow unchanged. This keeps the launcher
command list, help, options, validation, and exit codes identical to the
installed engine version.
Options:
--help Show this message and exit.
openadapt quickstart¶
Usage: openadapt quickstart [OPTIONS]
Run a verified local tutorial against the bundled synthetic app.
This is the shortest path to a real OpenAdapt run. It uses the bundled
synthetic tutorial, verifies the write through an independent read-only
system-of-record interface, keeps every artifact on this computer, and
enables no model or Cloud call. The output directory is never overwritten.
Other flags that the engine tutorial accepts (for example --guided or
--interactive-record) pass through to it unchanged.
Options:
--out PATH Directory for the recording, bundle, and run report. Default:
openadapt-quickstart, suffixed -2, -3, ... when taken.
--headed Show the browser while the tutorial runs.
--break-it After the verified run, rerun the same certified bundle against
a fault-injecting backend and watch the engine halt instead of
trusting the screen.
--help Show this message and exit.
openadapt seal¶
Usage: openadapt seal [OPTIONS]
Check an OpenAdapt Seal offline: `openadapt seal verify <file|url>`.
Also `openadapt seal keys pin` to pin Cloud's Seal keys after a person
confirms them. Every argument passes to `openadapt-agent seal` unchanged.
Options:
--help Show this message and exit.
openadapt version¶
Usage: openadapt version [OPTIONS]
Show version information for all packages.
Options:
--help Show this message and exit.
openadapt agent¶
openadapt-agent¶
usage: openadapt-agent [-h] [--version] {serve,repair,authoring,emit-skill,seal} ...
Your AI agent decides what to enter. OpenAdapt enters it in the app and checks that it saved.
'serve' with no flags starts a sandbox.
positional arguments:
{serve,repair,authoring,emit-skill,seal}
serve Serve workflows to your AI agent over MCP (stdio). With no flags, serve
the sandbox.
repair Control whether calling agents may help repair halted runs (local only).
authoring Hosted authoring mailbox client (ChatGPT.com / Claude.ai). Outbound HTTPS
only; not an HTTP listener.
emit-skill Write an Agent Skill for one workflow: what it does, its inputs, and how
to read the result. No recorded values, step text, or secrets.
seal Pin OpenAdapt Cloud's Seal keys and verify a Seal offline.
options:
-h, --help show this help message and exit
--version show program's version number and exit
openadapt-agent serve¶
usage: openadapt-agent serve [-h] [--mode {sandbox,attended,production}] [--bundles BUNDLES]
[--sandbox-engine {auto,flow,simulated}] [--authoring]
[--windows-agent-url URL] [--remote-window APP]
[--remote-window-title TITLE] [--citrix]
[--authoring-screens {off,scrubbed,unscrubbed}] [--tutorial]
[--allow-run] [--allow-protected-export]
[--allow-synthetic-recorded-defaults] [--allow-attended-actions]
[--url URL] [--config YAML] [--policy NAME-OR-PATH]
[--runs-dir RUNS_DIR] [--timeout SECONDS]
[--approval-mode {each_item,problems_only,not_gated}]
[--delegate-approvals AGENT_ID] [--allow-url-override]
[--flow-cli FLOW_CLI] [--headed] [--allow-model-grounding]
[--extra-run-arg ARG] [--repair-access FILE] [--repair-dir DIR]
[--hold-on-halt SECONDS]
options:
-h, --help show this help message and exit
--mode {sandbox,attended,production}
sandbox (default with no --bundles): one synthetic workflow that shows
every result. production: run the compiled workflows in --bundles.
attended: production plus decisions on paused runs by a person at this
computer. --bundles without --mode stays read-only.
--bundles BUNDLES Bundle directory: either one compiled bundle, or a directory whose
immediate subdirectories are bundles. Needed for --mode production and
--mode attended.
--sandbox-engine {auto,flow,simulated}
Advanced. flow drives the synthetic app in a hidden browser (needs the
tutorial extra); simulated returns the same results without opening it.
auto picks flow when it can.
--authoring Register first-demo authoring tools over local stdio: observe,
start_record, click, halt. Local Claude Code path is the first authoring
UI. Pass --url --headed to pin Playwright Chromium with empty cookies;
pause_for_input is how a person signs in there. --url is not the Chrome
window you already signed into. Omit --url to pin a unique frontmost
Chrome window after login (macOS; no DOM identity). Local stdio may also
type through the recorder; hosted MCP remains pause-only. Does not enable
run tools. This process stays stdio and must not be served over HTTP.
--windows-agent-url URL
With --authoring: drive a native Windows app through the Flow Windows
agent server running on the Windows computer (for example
http://localhost:5001, or an SSH-forwarded port from another computer).
The agent's input goes through the same synthetic-input path replay uses.
The token comes from OAFLOW_AGENT_TOKEN.
--remote-window APP With --authoring: drive the RDP or Citrix session shown in this local
client window (app name, for example 'Microsoft Remote Desktop'). Screen-
only: the agent clicks pixels and presses keys.
--remote-window-title TITLE
With --remote-window or --citrix: pick one window by its title.
--citrix With --authoring: drive the local Citrix Workspace window (--remote-window
overrides the app name). Screen-only.
--authoring-screens {off,scrubbed,unscrubbed}
With --authoring: let the agent see the pinned window through the screen
tool, so it can drive a native Windows app or a remote session from
pixels. scrubbed removes identifiers first and shares nothing if that
fails. Default off.
--tutorial Older name for --mode sandbox. Synthetic only. Cannot be combined with
--bundles, --url, or --config.
--allow-run Older name for --mode production (with --bundles) or --mode sandbox
(without). Without a mode or this flag, --bundles stays read-only.
--allow-protected-export
DANGER: export raw workflow labels, recorded values, intents, local paths,
reports, stdout, stderr, and exception detail to the MCP client. Off by
default; enable only for an explicitly trusted local client inside the
protected data boundary.
--allow-synthetic-recorded-defaults
DEMO ONLY: let omitted workflow parameters reuse recorded values. Use only
with synthetic demonstrations; production requires every declared
parameter so a run cannot silently target the recorded customer or record.
--allow-attended-actions
Part of --mode attended. Register governed Reject/Teach/Escalate tools for
signed durable pauses. With --config, also register Continue/Skip through
Flow's deployment-bound live verifier and deterministic resume path.
--url URL Target app URL passed to every `openadapt-flow run` (operator-fixed)
--config YAML Deployment config YAML forwarded to `openadapt-flow run --config`
--policy NAME-OR-PATH
Certifying policy forwarded to `openadapt-flow run --policy` and used by
get_workflow's certification check
--runs-dir RUNS_DIR Directory for run records and evidence (default:
$OPENADAPT_AGENT_RUNS_DIR, else ~/.openadapt/runs; the sandbox uses
~/.openadapt/agent-sandbox). Never relative to the folder the client
starts the server in.
--timeout SECONDS Per-call timeout for each governed run (default: 600)
--approval-mode {each_item,problems_only,not_gated}
Per-save approval passed to every `openadapt-flow run`. Unset (the
default): Flow decides, and under the Standard and Regulated profiles each
save waits for approval (each_item); a run waiting for that approval
reports needs_review. not_gated turns the pause off for every run this
server starts, and each run's result and Flow's report record that.
Callers can't change it.
--delegate-approvals AGENT_ID
Let the calling agent answer saves that wait for an approval, as the
opaque id AGENT_ID (for example agent:intake-bot). Adds the
list_approval_requests and answer_approval_request tools. Flow accepts the
agent's answer only under a person-signed approver grant (openadapt-flow
run --approver-policy) that names AGENT_ID and allows an agent for that
step; by default only a person may answer. Runs this server starts record
AGENT_ID as their initiator, so the agent can never approve its own runs.
Flow records the agent and the grant's digest as the approver.
--allow-url-override Permit MCP callers to pass a per-call `url` argument (default: the target
URL is fixed by --url/--config at server start)
--flow-cli FLOW_CLI Command used to invoke the flow CLI (default: this interpreter's `python
-m openadapt_flow`, so the flow installed alongside this server is always
the one that runs); may contain spaces, e.g. 'openadapt-flow'
--headed Keep a deployment-configured attended web session visible to the local
operator (required for web Continue/Skip).
--allow-model-grounding
Explicit CLI opt-in for configured off-box model grounding. A deployment
config may also opt in; otherwise verification remains local.
--extra-run-arg ARG Extra argument appended to every `openadapt-flow run` invocation
(repeatable; operator-fixed, e.g. --extra-run-arg=--allow-unencrypted for
a demo bundle)
--repair-access FILE Screen access setting for repairs, written by `openadapt-agent repair
access`. Without it, halted runs still return needs_repair but no screens,
and teach_repair is not offered.
--repair-dir DIR Where repair tokens, approvals, and candidates live (default
RUNS_DIR/.repair).
--hold-on-halt SECONDS
With --repair-access, keep a halted browser run's page open this long so
teach_repair acts on it (default 300; 0 turns it off).
openadapt-agent repair¶
usage: openadapt-agent repair [-h] {access,approve-screen} ...
positional arguments:
{access,approve-screen}
access Set screen access for repairs for one workflow or the whole organization.
approve-screen Look at the exact screen a calling agent would get for one repair, and
approve it.
options:
-h, --help show this help message and exit
openadapt-agent repair access¶
usage: openadapt-agent repair access [-h] (--workflow WORKFLOW | --org) --screens
{off,scrubbed_only,ask_each_time,allow_unscrubbed} --by BY
--file FILE
options:
-h, --help show this help message and exit
--workflow WORKFLOW Workflow name from list_workflows
--org Default for every workflow
--screens {off,scrubbed_only,ask_each_time,allow_unscrubbed}
--by BY Your name, recorded with the setting
--file FILE The --repair-access file
openadapt-agent repair approve-screen¶
usage: openadapt-agent repair approve-screen [-h] --by BY --repair-access FILE --repair-dir DIR
token_id
positional arguments:
token_id token_id from the needs_repair result
options:
-h, --help show this help message and exit
--by BY Your name, recorded with the approval
--repair-access FILE
--repair-dir DIR
openadapt-agent authoring¶
usage: openadapt-agent authoring [-h] {connect} ...
positional arguments:
{connect}
connect Claim an openadapt://runner link or pack URL, poll wait=0, and prompt Allow per chat
account
options:
-h, --help show this help message and exit
openadapt-agent authoring connect¶
usage: openadapt-agent authoring connect [-h] [--url URL] [--headed] target
Claim an openadapt://runner link or pack URL, poll wait=0, and prompt Allow per chat account.
Overlay chrome stays Desktop-only. Continue uses record_observed; it does not type secrets. This
process only makes outbound HTTPS.
positional arguments:
target openadapt://runner?pack=…&bind=oab_…&origin=https://openadapt.ai or
https://openadapt.ai/j/{id} (bind required to claim)
options:
-h, --help show this help message and exit
--url URL Launch Playwright Chromium with empty cookies at this URL. Not the browser you are
already signed into.
--headed Keep the Playwright window visible (required to sign in in the app).
openadapt-agent emit-skill¶
usage: openadapt-agent emit-skill [-h] --out OUT [--include-bundle] bundle
positional arguments:
bundle Workflow bundle directory
options:
-h, --help show this help message and exit
--out OUT Parent directory for the skill folder
--include-bundle Also copy the compiled bundle next to SKILL.md. The copy is protected workflow
data; install it only where that data may live.
openadapt-agent seal¶
usage: openadapt-agent seal [-h] {verify,keys} ...
positional arguments:
{verify,keys}
verify Check a Seal (receipt, run report, or webhook JSON).
keys Pin or show the Cloud Seal keys this computer trusts.
options:
-h, --help show this help message and exit
openadapt-agent seal verify¶
usage: openadapt-agent seal verify [-h] [--keys KEYS] [--json] target
positional arguments:
target Path, https:// URL, or - for stdin
options:
-h, --help show this help message and exit
--keys KEYS Pinned key file (default: your pinned keys)
--json Print the verdict as JSON
openadapt-agent seal keys¶
usage: openadapt-agent seal keys [-h] {pin,show} ...
positional arguments:
{pin,show}
pin Fetch /api/public/seal-keys and pin new keys after a person confirms each one.
show List pinned keys with fingerprints.
options:
-h, --help show this help message and exit
openadapt-agent seal keys pin¶
usage: openadapt-agent seal keys pin [-h] [--url URL] [--path PATH] [--confirm KEY_ID]
options:
-h, --help show this help message and exit
--url URL Key registry URL (default https://app.openadapt.ai/api/public/seal-keys)
--path PATH Pinned key file (default ~/.openadapt/seal-keys.json)
--confirm KEY_ID Trust this key id without a prompt, after checking its fingerprint out of
band. Repeatable.