Command reference¶

pip install openadapt installs the openadapt command. It has a few commands of its own and passes two groups through to the engine:

openadapt flow ... runs openadapt-flow, the compiler and runtime.
openadapt agent ... runs openadapt-agent, the MCP server.

Every command takes --help, which is the authority for its options. This page lists the commands in openadapt 1.17.0 and openadapt-flow 2.1.0.

Launcher commands¶

Command	What it does
`openadapt quickstart [--break-it] [--headed] [--out DIR]`	Runs the bundled tutorial: records, compiles, certifies, and runs a save against a test app, then confirms it through the app's API. `--break-it` adds a second run against a backend that fakes success. See Quickstart.
`openadapt doctor [--backend SURFACE]`	Checks this computer's requirements, for one surface if given.
`openadapt deploy [--backend SURFACE] [--secret-ref REF]`	Checks this host and prints the deployment path for a surface. Takes secret references only (`env:NAME` or `keychain:service/item`).
`openadapt connect --pairing CODE`	Pairs this computer with an OpenAdapt Cloud workspace.
`openadapt seal verify TARGET [--keys KEYS] [--json]`	Checks a Seal offline. `openadapt seal keys pin` and `show` manage the trusted keys.
`openadapt version`	Prints installed package versions.

Verbs at a glance¶

openadapt flow VERB and openadapt-flow VERB are the same command.

Verb	What it does
`demo`	Shows a checked run and a run where the app fakes success, side by side, on test data.
`tutorial`	The engine side of `openadapt quickstart`.
`demo-record`	Serves the MockMed test app and records the standard triage demonstration.
`record`	Records a demonstration in a browser, on the desktop, or in an RDP or Citrix client window.
`compile`	Compiles one recording into a bundle.
`induce`	Learns one program from two or more recordings, or refuses and lists the recordings it needs.
`for-each`	Wraps a bundle in a loop over a worklist.
`compose`	Chains bundles from different surfaces, passing confirmed values.
`process`	Builds a process from separately admitted parts, each with its own admission.
`disambiguate`	Asks the open questions in an induced program as multiple choice.
`intake`	Fills a workflow's inputs from a referral PDF, fax image, or email.
`visualize`	Draws a bundle as HTML, Mermaid, or JSON.
`lint`	Lists what the program doesn't cover yet.
`scaffold-verifier`	Drafts record checks from a recording or bundle, for a person to complete.
`bind-record-checks`	Attaches reviewed record checks to a compiled bundle, in a new bundle.
`certify`	Checks a bundle against a policy.
`qualify`	Manages and runs a bundle's qualification against normal and fault cases.
`propose-qualification`	Same as `qualify propose`.
`seal`	Writes an encrypted copy of a bundle using `OPENADAPT_BUNDLE_KEY`.
`admit`	Reads the public release-admission list. It never signs anything.
`replay`	Performs every step of a bundle against a real app. Never checks the record.
`run`	Runs a bundle under a profile, with every gate.
`resume`	Continues a paused durable run from its last confirmed step.
`approve`	Records a decision that lets a paused run resume.
`item-approval`	Lists, approves, or declines the saves a run is waiting on.
`explain`	Explains a finished run in plain words, with the next command.
`attach-seal`	Adds Cloud's signed receipt to a `VERIFIED` run report.
`bench`	Replays a bundle many times against MockMed and summarizes.
`benchmark`	Compares compiled replay with a computer-use agent on MockMed. The agent side needs an Anthropic API key and costs money.
`teach`	Turns a fix demonstration for a halted run into a guarded branch.
`teach-branch`	Learns a guarded branch from two or more halts fixed the same way.
`repair`	Moves a repaired bundle through review, campaigns, approval, staging, canary, and rollback.
`emit-skill`	Writes an Agent Skill for a bundle.
`emit-mcp`	Writes a standalone MCP `server.py` for a bundle.
`connect`	Claims a pairing and stores the workspace credential in the keychain.
`login`	Checks an ingest token and stores it in the keychain.
`sanitize`	Writes a redacted copy of a recording or bundle. Never changes the original.
`review-sanitized`	Shows the original and the redacted copy side by side in a local viewer.
`approve-sanitized`	Freezes the reviewed copy as an approved archive.
`materialize-approved`	Rebuilds an approved copy from its archive and approval record.
`validate-hosted`	Binds lint, certification, and a local run to a one-time Cloud challenge.
`push`	Uploads an approved archive to Cloud.
`report-break`	Sends a halted run's diagnostic, with no patient data, to Cloud.
`report-run`	Sends a finished run's summary, with no patient data, to Cloud.
`connector`	Enrolls this computer with Cloud and runs Cloud jobs locally.
`console`	Serves a local operator page over bundles, runs, and halts. Read-only unless `--allow-actions`.
`business-decisions`	Relays typed business decisions on a customer runner. It never resumes or acts.
`serve-execute`	Serves the Execute API locally. Its receipts are signed with a local key and aren't Seals.
`serve-reward`	Scores training episodes by reading the system of record. Its receipts aren't Seals.

certify, replay, run, and resume all accept --config deploy.yaml. record and compile don't.

Try it¶

openadapt flow demo
openadapt flow tutorial --break-it
openadapt flow demo-record --out rec

Record¶

openadapt flow record --url URL --out rec                 # browser
openadapt flow record --out rec                           # this computer's desktop
openadapt flow record --backend citrix --out rec          # Citrix client window

With no --url and no --backend, record captures on this OS. Main options: --param, --secret, --identifier, --task, --window, --window-title, --browser-cdp-endpoint, --until-cmd, and the surface options. See Record a demonstration.

Build¶

openadapt flow compile rec --out bundle --name NAME [--accept-params A,B | --params-from FILE | --no-confirm-params]
openadapt flow induce rec1 rec2 [...] --out program [--name NAME] [--held-out]
openadapt flow for-each bundle --records FILE --out program [--map COLUMN=PARAM] [--max-iterations N]
openadapt flow compose --child NAME=PATH --child NAME=PATH [--handoff A.x=B.y] [--after NAME=PRED] --out DIR
openadapt flow disambiguate program [--interactive | --answers FILE] [--write]

See Build a program from several demonstrations.

Inspect¶

openadapt flow visualize bundle [--format html|mermaid|json] [-o FILE] [--profile remote-safe]
openadapt flow explain RUN_DIR

visualize --profile other than operator-local removes recorded text, values, selectors, and URLs from the view.

Check¶

openadapt flow lint bundle [--strict]
openadapt flow scaffold-verifier rec [-o DIR]
openadapt flow bind-record-checks bundle --binding FILE (--check | -o OUT)
openadapt flow certify bundle [--policy clinical-write|permissive|FILE] [--config deploy.yaml]
openadapt flow seal bundle -o bundle-sealed

qualify subcommands in 2.1.0: schema, label, init, propose, accept, admit-local, from-demo, inspect, explain, report, set-identity, set-risk, trust-runner, set-effect, business-decision, judgment-cases, add-case, run, run-case, drills, add-requalification, and certify. See Certify and qualify a workflow.

Run¶

openadapt flow replay bundle [--url URL] [--run-dir DIR] [--param K=V]
openadapt flow run bundle --profile standard --config deploy.yaml [--qualification-authority-file FILE]
openadapt flow resume RUN_DIR [--require-approval]
openadapt flow approve RUN_DIR [--approver ID] [--resolution OPTION] [--authorize-uncertain-retry]
openadapt flow item-approval show RUN_DIR
openadapt flow attach-seal RUN_DIR --execution-id ID

Main run options: --profile, --config, --param, --params-file, --worklist, --policy, --durable, --dry-run, --approval-mode, --approval-wait, --effects-kind, --effects-base-url, --allow-model-grounding, --hold-on-halt, --browser-cdp-endpoint, --cloud-execution-id, and the surface options. See Run a workflow.

Repair¶

openadapt flow teach RUN_DIR --fix FIX --bundle bundle --out bundle-v2
openadapt flow teach-branch --example RUN_DIR FIX --example RUN_DIR FIX --bundle bundle --out bundle-v2
openadapt flow repair {register,list,show,review,campaign,approve,stage,canary,canary-record,rollback,status}

See Handle a halt.

Agents¶

openadapt flow emit-skill bundle --out DIR
openadapt flow emit-mcp bundle --out server.py
openadapt agent serve [--mode sandbox|attended|production] [--bundles DIR] [--runs-dir DIR] [--config YAML]
openadapt agent emit-skill bundle --out DIR [--include-bundle]

See Connect an agent.

Cloud¶

openadapt flow sanitize PATH --kind recording|bundle --out DIR
openadapt flow review-sanitized DIR --original PATH
openadapt flow approve-sanitized DIR --original PATH --reviewer ID
openadapt flow push DIR --kind recording|bundle [--validation-attestation FILE]

See Deploy.

Operate¶

console needs the console extra, serve-execute the execute extra, and serve-reward the reward extra of openadapt-flow.

Surface options¶

record, replay, run, resume, and qualify run-case share these:

Option	Surface
`--backend web\\|windows\\|macos\\|linux\\|rdp\\|citrix`	Which surface to drive
`--url`, `--browser-cdp-endpoint`, `--browser-page-url`	Browser
`--agent-url`	Windows, through the Windows agent server (replay and run only)
`--macos-app`, `--macos-window-title`	macOS
`--linux-app`, `--linux-window-title`, `--linux-allow-physical-input`	Linux (replay and run only)
`--rdp-host`	RDP over the network (replay and run only)
`--rdp-window`, `--rdp-window-title`, `--rdp-readiness-text`	RDP or Citrix client window
`--allow-surface-override`	Run on a different surface than recorded; the report records it