The openadapt flow CLI¶
Record a workflow once, compile it into a deterministic vision-anchored script,
replay it locally, and resolve, repair, or halt under drift. Every command below
is a subcommand of openadapt flow.
Command form
The primary form is openadapt flow <verb>. If you installed the standalone
engine package, the same verbs are available as openadapt-flow <verb>
(drop the space). The flags are identical.
Verbs at a glance¶
| Verb | What it does | Exit code |
|---|---|---|
record |
Record your own app (--url) in a headed browser |
0 |
demo-record |
Serve the sample app and record the canonical demo | 0 |
compile |
Compile a recording into a workflow bundle | 0 |
induce |
Induce a parameterized program from multiple recordings | 0 if certified, 2 if underdetermined |
replay |
Replay a bundle, locally and deterministically | 0 on success, 1 on failure |
run |
Execute a bundle through the fail-closed deployment gate | 0 success, 1 execution halt, 2 refusal |
resume |
Resume a durably-paused run from its last checkpoint | 0 on success, 1/3 otherwise |
approve |
Mark a durably-paused run's escalation approved | 0 on success, 1 if none |
teach |
Resolve a halted run from a fix demonstration, governed | 0 if promoted, 1 if refused, 2 on bad inputs |
lint |
Report a bundle's coverage gaps | nonzero by severity |
certify |
Enforce a safety policy, refuse the bundle if it fails | 2 on failure |
disambiguate |
Surface and resolve compile-time ambiguities | 2 if a consequential ambiguity is unresolved |
login |
Validate a hosted ingest token and remember the host | 0/1 |
push |
Explicitly upload a recording or bundle to a control plane | 0/1 |
validate-hosted |
Bind local validation evidence to a one-time hosted challenge | 0/1 |
report-break |
Send a scrubbed, schema-minimized halt descriptor | 0/1 |
bench |
Replay a bundle N times against the sample app and aggregate | 0 if all pass |
benchmark |
Compare compiled replay vs a computer-use agent | 0 |
emit-skill |
Emit an Agent Skills folder for a bundle | 0 |
emit-mcp |
Emit a standalone MCP server.py for a bundle |
0 |
One config wires a real deployment
record, compile, certify, replay, run, and resume all accept
--config deployment.yaml, which wires the backend, effect verification, API
actuation, durable runtime, and policy in one place. See the
deployment configuration reference. Direct flags
below override individual fields.
record¶
Open a headed browser on your own app and record what you do.
| Flag | Description |
|---|---|
--url (required) |
URL of the app to record against |
--out (required) |
Recording output directory |
--secret FIELD |
Mark a typed field (by name or id) as a secret: its value is never persisted and is injected at replay from OPENADAPT_FLOW_SECRET_<FIELD>. input[type=password] is always secret. Repeatable. |
--param FIELD |
Record a typed field as a parameter: its demonstrated value becomes the default, overridable at replay with --param. Repeatable. |
--headless |
Run the browser headless (scripted or CI recording) |
demo-record¶
Serve the bundled sample app locally and record the canonical triage demo. Good for the five-minute tour.
| Flag | Description |
|---|---|
--out (required) |
Recording output directory |
--note-text |
Note text typed during the demo (recorded as a parameter) |
--param-name |
Parameter name for the note (default note) |
--drift |
Comma-separated drift modes to record against |
--headed |
Run the browser headed |
--record-video DIR |
Opt-in: capture a WebM of the recording session (default off) |
compile¶
Compile a recording directory into a workflow bundle.
| Argument / flag | Description |
|---|---|
recording (positional) |
Recording directory produced by record |
--out (required) |
Output bundle directory |
--name (required) |
Workflow name |
induce¶
Induce a parameterized program bundle from two or more recordings (or already-compiled bundles) of the same task: infer the shared parameters, loops, and branches. It refuses — writes no bundle, exits nonzero — when intent is underdetermined, rather than guessing a branch. See Induce a program from multiple traces.
| Argument / flag | Description |
|---|---|
recording ... (positional, 2+) |
Recording or bundle directories of the same task |
--out (required) |
Output program-bundle directory (written only when certified) |
--name |
Name for the induced workflow (default induced-program) |
--held-out |
Also run leave-one-out held-out validation and print per-fold reproduction scores (needs 2+ traces) |
Exits 0 when the program is certified (bundle written) and 2 when it is
not certified (no bundle written; the uncertainties are printed).
replay¶
Replay a bundle. With no --url, it serves the bundled sample app.
| Flag | Description |
|---|---|
bundle (positional) |
Workflow bundle directory |
--url |
Target app URL (default: serve the bundled sample app) |
--drift |
Comma-separated drift modes (theme,move,rename,modal) to demonstrate self-healing; only valid without --url |
--run-dir |
Run output directory (default: runs/replay-<UTC timestamp>) |
--param K=V |
Parameter substitution. Repeatable. |
--save-healed-to DIR |
Write the healed bundle to this directory |
--headed |
Run the browser headed |
--record-video DIR |
Opt-in: capture a WebM of the replay session (default off) |
--worklist [RELATION=]FILE |
CSV/JSON worklist of parameter rows driving a program bundle's loop over a relation (repeatable). RELATION=FILE binds a named relation; a bare FILE binds the program's sole loop relation. Refused on a linear bundle. |
Deployment-wiring flags (shared with run / resume;
default off, so an unconfigured replay behaves exactly as before):
| Flag | Description |
|---|---|
--config YAML |
Deployment config wiring backend / actuation / effects / runtime / policy. Flags below override individual fields. |
--effects-kind |
System-of-record verifier: none, rest, fhir, document-hash. Verifies consequential writes against the real record, not the screen. |
--effects-base-url |
Base URL for the rest / fhir verifier |
--effects-root |
Document-store root for the document-hash verifier |
--api-actuator |
Perform a step carrying an ApiBinding via the API ($0, no GUI), confirmed by the effect verifier |
--api-base-url |
Base URL for the API actuator (implies --api-actuator) |
--durable |
Enable the Tier-3 durable runtime: checkpoint each verified step, durably pause on halt, resumable via resume |
--allow-model-grounding |
Model-egress opt-in (PHI audit REM-3): permit wiring an off-box model grounder / identity-VLM / state-verifier; screenshots may leave the box. Off by default: replay makes no model-service calls; target and effect-verifier traffic remains deployment-defined. |
Exits 0 on success and 1 on a halt. With no model component wired, replay makes
no model-service calls; target and effect-verifier traffic still follows the
deployment configuration. The on-prem VLM appliance is engaged only when
--allow-model-grounding is passed and
OPENADAPT_FLOW_VLM_URL is set.
run¶
The same executor as replay, behind a fail-closed admission gate:
the bundle must pass policy, identity coverage, effect coverage, approval,
encryption, and manifest-integrity checks before any action executes. Backend,
effect verification, API actuation, durable runtime, and policy are wired from
--config. The demo-only --drift teaching aid is not offered. See
Run a deployment.
| Flag | Description |
|---|---|
bundle (positional) |
Workflow bundle directory |
--url |
Target app URL (default: backend.url from --config) |
--run-dir |
Run output directory (default runs/replay-<UTC timestamp>) |
--param K=V |
Parameter substitution. Repeatable. |
--save-healed-to DIR |
Write the healed bundle to this directory |
--headed |
Run the browser headed |
--policy NAME-OR-PATH |
Certifying policy (default: config policy, then clinical-write). |
--approve-unverified-writes |
Explicitly approve writes whose declared effects cannot be independently verified in this deployment. |
--strict-templates |
Refuse rather than warn when template/screenshot assets are unsealed. |
--allow-unencrypted |
Development escape hatch that disables the default encryption-at-rest refusal. |
--pin-digest SHA256 |
Refuse unless the sealed content digest matches. |
--pin-version VERSION |
Refuse unless the compiler version matches. |
--dry-run, --explain |
Print the gate report and exit without executing. |
Accepts every deployment-wiring flag above (--config,
--effects-*, --api-*, --durable, --worklist, --allow-model-grounding).
Exits 2 on admission refusal, 0 after successful execution, and 1 if an
admitted execution later halts.
resume¶
Resume a durably-paused run from its last verified checkpoint, never re-running an already-confirmed write. Rebuilds a live backend, re-binds the run's parameters, and continues from the checkpoint. See Durable runtime.
| Flag | Description |
|---|---|
run_dir (positional) |
The paused run directory (holds the checkpoints) |
--url |
Target app URL to rebuild a live backend (default: backend.url from --config) |
--headed |
Run the browser headed |
--require-approval |
Refuse to resume unless the pending escalation is approved (see approve) |
Also accepts the deployment-wiring flags (--config, --effects-*, --api-*,
--durable). Exits 1 when there is no pending escalation to resume, 3 when
--require-approval is set and the escalation is not approved, and 0/1 on
the resumed run's success/halt.
approve¶
Mark a durably-paused run's pending escalation approved, so
resume --require-approval will continue it.
| Flag | Description |
|---|---|
run_dir (positional) |
The paused run directory (holds the escalation) |
Exits 0 on success (or if already approved) and 1 when there is no pending
escalation.
Approval scope today
Approval is recorded as auditable metadata on the escalation, and
resume --require-approval gates on it. A full approval store (who, when,
signature) is on the durable roadmap. See
Durable runtime.
teach¶
Resolve a halted run: demonstrate the fix once, and teach compiles it back
into the workflow through the governed induction path so that state never halts
again. It induces the correction as a guarded exception branch, gates it against
a regression check and a held-out canary, and writes an updated bundle only
if it passes. See The halt-learn loop.
openadapt flow teach runs/replay-20260712-140233 \
--fix recordings/dismiss-the-dialog \
--bundle bundles/patient-intake \
--out bundles/patient-intake-v2
| Flag | Description |
|---|---|
run_dir (positional) |
The HALTED run directory (holds report.json with a halt) |
--fix (required) |
The fix demonstration: a recording directory of just the corrective actions (e.g. dismiss the dialog), or a .json correction spec (resolution_steps, optional tail_intents / facts / params) |
--bundle (required) |
The base bundle that halted (seeds the skill's active version) |
--out (required) |
Output directory for the UPDATED bundle, written only when the correction is promoted |
--skill-id |
Skill id in the versioned library (default: the run's workflow name) |
--library |
Directory for the versioned skill library that keeps the promotion lineage (default: <out>.skills) |
Deterministic and $0 on the shipped path: the resolution is induced by the
model-free reference inducer. Exits 0 when a verified revision is promoted (the
updated bundle is at --out), 1 on a governed refusal (the correction was
underdetermined or would weaken a safety invariant, so nothing is written and the
base bundle stays halting), and 2 when the inputs are unusable (no halt in the
report, no base bundle, or a malformed fix).
lint¶
Report a bundle's coverage gaps (unarmed clicks, vacuous postconditions, under-classified risk), each with a severity.
| Flag | Description |
|---|---|
bundle (positional) |
Workflow bundle directory |
--strict |
Exit nonzero on warnings too (default: only on errors) |
Exits nonzero once a finding reaches error (an unarmed or vacuous
irreversible step).
certify¶
Enforce a policy on a bundle and refuse it (nonzero exit) if it fails. This is what makes "runnable" distinct from "certified safe."
openadapt flow certify bundle --policy clinical-write
# or read the policy from a deployment config:
openadapt flow certify bundle --config deployment.yaml
| Flag | Description |
|---|---|
bundle (positional) |
Workflow bundle directory |
--policy |
Policy YAML path, or a built-in name (permissive, clinical-write). Defaults to policy.policy from --config. |
--config YAML |
Deployment config to read the policy from when --policy is omitted, so one file both certifies and runs the bundle |
Provide --policy or a --config that sets policy.policy; certify errors if
neither supplies a policy. Exits 2 when the bundle fails certification.
disambiguate¶
Surface the compile-time multiple-choice questions an ambiguous demonstration raises, and apply the answers as guards or parameters. Ask, do not guess.
| Flag | Description |
|---|---|
bundle (positional) |
Workflow bundle directory |
--interactive |
Prompt for each question on the terminal |
--answers FILE |
JSON file mapping question id to chosen option key |
--write |
Save the resolved workflow back into the bundle |
Exits 2 if a consequential (must-answer) ambiguity is left unresolved.
login¶
Validate a hosted ingest token. The CLI stores the token in the OS keychain when available and stores only the non-secret host in its config. Plaintext token storage requires an explicit fallback flag. This is a connectivity command, not a hosted-runner entitlement.
| Flag | Description |
|---|---|
--token |
Ingest token. Falls back to OPENADAPT_INGEST_TOKEN, the OS keychain, then an existing config migration token. |
--host |
Control-plane base URL. Defaults to the configured host, then https://app.openadapt.ai. |
--no-save |
Validate without writing the host/token to the config file. |
validate-hosted¶
Acquire an expiring, one-time Cloud challenge and create a signed operator attestation over strict lint, policy certification, and a successful local replay. Both inputs must be reviewed and approved sanitized derivatives. The bundle must have been compiled from the exact approved recording, and bundle sanitation must preserve execution-bearing bytes.
openadapt flow validate-hosted \
--recording recording.sanitized \
--bundle bundle.sanitized \
--run-dir runs/triage-validation \
--policy clinical-write \
--risk-class consequential \
--environment validation/mock-emr-v1 \
--target-url https://validation.example/login \
--allowed-host cdn.validation.example \
--out triage.runtime-validation.json
| Flag | Description |
|---|---|
--recording |
Approved sanitized recording derivative used to compile the bundle. |
--bundle |
Approved sanitized bundle derivative whose exact archive will upload. |
--run-dir |
Successful, non-halted local replay directory containing report.json. |
--policy |
Named or file-backed policy that must pass again during validation. |
--risk-class |
low or consequential; must match the risk derived from the compiled steps and be allowed by Cloud. |
--environment |
Non-PHI validation-environment identifier; only its SHA-256 is included. |
--target-url |
Exact non-PHI HTTPS entry URL. The report must bind the same requested URL and its actual browser origin; credentials, query strings, and fragments are refused. |
--allowed-host |
Additional exact hostname allowed during hosted execution. Repeatable; the target hostname is included automatically. |
--compiler-config |
Optional JSON object; its digest must match compiler provenance already sealed into the bundle. |
--out |
Attestation JSON path. |
--destination-kind, --trusted-host |
Destination policy for managed or exact-allowlisted customer endpoints. |
--host, --token |
Override the configured control plane and token used for the challenge and HMAC. |
The attestation binds the exact recording and bundle archive hashes, compiler identity/configuration, parameter schema, target/host execution boundary, lint/certification evidence, replay report, validation environment, policy, risk class, and challenge. The client also verifies the run report's workflow, bundle digest, source-recording provenance, parameter schema, and actual browser origin. Cloud verifies its configured exact policy, risk-class, and deployed compiler-version allowlists and consumes the organization/token-bound challenge once when the bundle is accepted.
This is operator self-attestation, not an independent test or certification.
The ingest-token HMAC proves possession and detects mutation; it does not prove
that Cloud or an auditor observed the local replay. certify only evaluates the
selected policy. Use independent evidence custody and a separately controlled
signer when independent certification is required.
push¶
Create or verify a sanitized derivative, enforce its review/approval and
destination policy, and upload its immutable approved archive to /api/ingest.
Uploading does not itself run the workflow.
Sanitation does not establish runnability. Recording push registers the exact
approved source and returns the next validation state; it does not create a
runnable workflow. Compile that derivative locally, run strict lint,
certification, and successful replay, then sanitize/review/approve the bundle,
run validate-hosted, and push the exact bundle with its one-time attestation.
openadapt flow sanitize recording --kind recording --out recording.sanitized
openadapt flow review-sanitized recording.sanitized --original recording
openadapt flow approve-sanitized recording.sanitized \
--original recording --reviewer alice@example.com
openadapt flow push recording.sanitized --kind recording --name "Triage"
Calling push with a raw path performs the first sanitation step and normally
returns pending_review plus the local viewer command. After approval, call
push on the derivative directory.
| Flag | Description |
|---|---|
path |
Recording or bundle directory. Defaults to the most recent recording in the current directory. |
--kind |
recording (default) or bundle. |
--name |
Workflow name. |
--workflow-id |
Existing hosted workflow UUID to receive a validated replacement bundle. Valid only with --kind bundle. |
--resolves-run-id |
Exact halted-run UUID repaired by this replacement. Requires --kind bundle and --workflow-id; the halt is resolved only after atomic activation. |
--deployment-kind |
Execution lane: cloud, byoc, or regulated. This is independent of destination trust; every lane requires a verified derivative. |
--destination-kind |
openadapt-managed, customer-managed, or local. The OpenAdapt origin is recognized automatically. |
--trusted-host |
Exact HTTPS origin allowed for a customer-managed endpoint; repeatable. |
--sanitized-out |
Destination for the derivative created from a raw path. |
--auto-approve |
Administrator policy approval for a stable derivative with complete type coverage. Human review is the default. |
--validation-attestation |
Required challenge-bound validate-hosted JSON when --kind bundle; it must match the exact approved bundle archive. |
--attest-non-phi |
Deprecated and refused. A declaration cannot bypass sanitation, review, or exact-hash approval. |
--host, --token |
Override the configured control plane and token. |
Remote artifact upload requires an approved sanitized derivative. The pipeline inventories and transforms a copy, rescans it, records unresolved findings and tool versions in a manifest, and binds operator approval to the derivative hash. Unknown, symlinked, unsupported, or unresolved content aborts the upload instead of being copied unchanged. The destination is evaluated separately: a verified customer endpoint may accept data its policy permits, while an unknown endpoint is refused. Compilation alone is never a de-identification claim.
sanitize, review-sanitized, approve-sanitized¶
sanitize creates a separate derivative and openadapt.sanitization/v1
manifest without modifying the source. review-sanitized serves a loopback-only
original-versus-derivative viewer with no remote assets. approve-sanitized
records the reviewer and freezes an immutable archive; later modification makes
the approval invalid.
openadapt flow sanitize PATH --kind recording --out DERIVATIVE
openadapt flow review-sanitized DERIVATIVE --original PATH
openadapt flow approve-sanitized DERIVATIVE --original PATH --reviewer IDENTITY
| Command/flag | Description |
|---|---|
sanitize --kind |
Required artifact type: recording or bundle. |
sanitize --redactions FILE |
Additional local JSON text/image redactions. |
sanitize --overwrite |
Replace an existing derivative; never modifies the source. |
review-sanitized --original |
Sensitive source shown only by the loopback viewer. |
review-sanitized --no-open |
Print the local URL rather than opening a browser. |
approve-sanitized --original |
Required sensitive source used to verify derivative provenance. |
approve-sanitized --reviewer |
Required identity written into the approval record. |
A bundle whose sanitation changed load-bearing identity evidence is not accepted as executable. Parameterize the sensitive value before compilation or execute the original inside its trusted runtime boundary.
report-break¶
Read a halted run's report.json and emit a scrubbed, schema-minimized halt descriptor.
The recording stays local. A PHI-boundary rejection retries with a harder scrub
and can fall back to local-only.
| Flag | Description |
|---|---|
run_dir |
Halted run directory containing report.json. |
--workflow-id |
Required hosted workflow id returned by push or the dashboard. |
--deployment-kind |
cloud (default) or byoc; routes the teaching target. |
--org-id |
Optional organization id. |
--host, --token |
Override the configured control plane and token. |
See Hosted browser execution for the launch candidate, sanitation protocol, and destination-aware boundary.
bench¶
Replay a bundle N times against the sample app and aggregate the results.
| Flag | Description |
|---|---|
bundle (positional) |
Workflow bundle directory |
--n |
Number of iterations (default 3) |
--drift |
Comma-separated drift modes forwarded to the sample-app URL |
--run-root (required) |
Directory for per-iteration runs |
--param K=V |
Parameter substitution. Repeatable. |
--headed |
Run the browser headed |
benchmark¶
Compare compiled replay against a computer-use agent on the sample triage task.
The agent arm costs real money
The agent arm calls a hosted model and incurs API cost. The compiled arm is $0. Run the agent arm only with cost caps in place.
| Flag | Description |
|---|---|
--n-compiled |
Compiled-replay iterations (default 100) |
--n-agent |
Agent iterations (default 20) |
--out |
Output directory for results and chart |
--note-text |
Note text both arms enter |
--headed |
Run the browsers headed |
emit-skill / emit-mcp¶
Emit a compiled bundle as an Agent Skills folder, or as a standalone MCP server, so other agents can invoke the workflow as a tool.
| Flag | Description |
|---|---|
bundle (positional) |
Workflow bundle directory |
--out (required) |
Output folder (skill) or file path (MCP server.py) |