Skip to content

Plugins

Plugins connect a flow to the parts of your application it needs to exercise. Each plugin has its own connection settings, commands and retained evidence. Mix them in one flow or pass values between dependent flows.

list_plugins exposes each provider’s command argument schema. A flow invocation can also carry the host RFL modifier checkpoint="evidence-label"; the host removes that label before provider argument validation and dispatch. It is not a missing field in the provider descriptor. Use literal labels of 1-128 letters, digits, underscores or hyphens; other unknown arguments remain errors. within= and every= are host modifiers too: they wait for a call’s check to hold (see waiting and branching).

If this is your first flow, get started to install Reflow and sign in. App access requires an approved team.

PluginUse and evidence
BrowserInteract with pages and retain viewport or CSS-scoped screenshots.
LocalBashRun host commands; retain output, exit code and files.
PostgreSQLCheck database rows or retain results of deliberate setup writes.
DockerUbuntuRun commands in an existing Ubuntu container; retain output and files.
MailboxKeep a named inbox and capture new email codes or links.
OpenAPICall declared HTTP operations with typed requests; assert JSON responses and capture public scalar values.
MCP inspectorCheck what an MCP server exposes to one identity; retain tool, resource and prompt inventories and tool-call results.
TLA+Check a design written in TLA+ with the TLC model checker; retain counterexamples, and check recorded events against the design. Optional: installed on demand.
ClickHouseCheck ClickHouse rows such as telemetry and events, or retain results of deliberate setup statements. Optional: installed on demand.
LeanCheck Lean 4 proofs the flow carries: no sorry, standard axioms only, and the statements you wrote; retain Lean’s messages and each theorem’s axioms. Optional: installed on demand.
BombadilExplore the page your Browser steps opened and check properties that must hold whatever a user does; retain the actions, screenshots and trace of a violation. Optional: installed on demand.
MacOSAppDrive an isolated copy of a native macOS app through Accessibility; retain assertions, accessibility trees and window captures. Not yet released; not bundled.
SwiftVM: macOS VMDisposable macOS 27 guests with staged jobs, native app journeys and artifact export. Optional, macOS on Apple Silicon only: installed on demand.
SwiftVM: Swift testsPrototype that runs its own fixture’s Swift Testing suites in a macOS virtual machine, with coverage as a diagnostic; your packages are not supported yet. Uses the svm host tool, built from source.

Check each thing with the plugin built for it, so the assertion is a visible statement in the flow rather than a script’s exit code. LocalBash is for your product’s own CLI or build, one invocation per step.

You want to checkUseNot
A page or UI journeyBrowser: role and label targets, expect, site.snapshotPlaywright or Puppeteer in a script; curl and grep on HTML
Properties that hold whatever a user does on a screenBombadil after Browser steps: explore.run browser="site" spec="app.spec.ts" time=60srandom clicking in site.script; the bombadil CLI in LocalBash
Database statePostgreSQL: db.query … expect=json(…), db.value … -> id, db.execute for setuppsql or a driver in LocalBash
ClickHouse state (telemetry, events)ClickHouse: ch.query … expect=json(…), ch.value … -> id, ch.execute for setupclickhouse-client in bash, or docker exec … clickhouse-client
An MCP serverMCP: connect, tools, call … expect=a Node or Python MCP client; curl JSON-RPC
An HTTP or RPC APIOpenAPI: http.call operationId=… expect=json(…), call_valuecurl piped to jq; site.script with fetch
An email code or linkMailbox: inbox.address, capture, extractpolling a mail API from a script
A state machine or protocol designTLA+: tla.check, tla.tracea hand-rolled model in a script
A proof or formal lemmaLean: lean.check theorems=…, statements=json(…)lean or lake in LocalBash; a proof checked by hand
Commands in a Linux containerDockerUbuntudocker exec or docker run in LocalBash
A native macOS appMacOSApp (not yet released)osascript in LocalBash
A clean Mac in a disposable VMSwiftVM: vm.guest_run (optional, macOS hosts only)ssh or VM scripts in LocalBash
Shared setupuse <flow>, or needscopied steps
Values between stepscapture, -> name, outputstemporary files or environment variables
The product’s own CLI or buildLocalBash, one invocation per step

Saving a new flow refuses shell logic in a command, encoded blobs, home paths, scripts the flow does not carry and token-shaped literals; see LocalBash.

A command that states its check with expect= can wait for it and decide a branch, so a flow needs no polling loop or shell if:

db.query sql="SELECT state FROM jobs WHERE name = 'zz-e2e-export'" expect="{\"json\":[{\"pointer\":\"/0/state\",\"equals\":\"done\"}]}" within=2m every=2s
if db.query sql="SELECT id FROM agents WHERE name = 'zz-e2e-agent'" expect="{\"rows\":1}"
db.execute sql="DELETE FROM agents WHERE name = 'zz-e2e-agent'"

within= runs the call again while its check does not hold, every second unless every= says otherwise, and stops at once if the call breaks. within is the last time an attempt may start; when the step’s or flow’s time ends the wait first, the step fails as broke and a condition takes neither block. Only a command that observes can wait: PostgreSQL and ClickHouse query, MCP tools, resources, resource_templates, read_resource, prompts and get_prompt, and Browser expect and expect_url. Mutating commands (bash, db.execute, OpenAPI and MCP call) are refused: make the change once, then wait on a read of its result. An if or unless can take any of these commands, mutating ones included, run once; a call that broke fails the step instead of choosing a branch. Saving warns (wait-loop) when a carried script sleeps inside a loop. See wait for a check to hold and conditionals.

The bundled CLI selection includes seven plugins: Browser, LocalBash, PostgreSQL, DockerUbuntu, Mailbox, MCP and OpenAPI. After choosing an application, install them with reflow init --collection <collection-id>, or select names with reflow init Browser PostgreSQL --collection <collection-id>. An application that already has a selection keeps it; see one selection per application to change it. Ordinary initialization does not require Go or a private source checkout. Each plugin still needs its declared runtime, your application and any test data described on its page.

TLA is an optional plugin: it is not in the CLI download, and it is not part of the default selection. reflow init --upgrade TLA --collection <collection-id> adds it to an application and downloads it once for your platform; see install. ClickHouse is optional in the same way: reflow init --upgrade ClickHouse --collection <collection-id>; see install. SwiftVM is optional too, and runs only on macOS on Apple Silicon: reflow init --upgrade SwiftVM --collection <collection-id> on a Mac; on Linux, init refuses and says it needs a macOS host. See availability. Lean and Bombadil are optional like ClickHouse: reflow init --upgrade Lean --collection <collection-id> or reflow init --upgrade Bombadil --collection <collection-id>; see Lean install and Bombadil install.

An optional plugin can be several hundred MB, so a download has no overall deadline. It stops only when no data arrives for 60 seconds (120 seconds before the first byte, for proxies that hold a file back while they scan it), or when --download-timeout-ms <ms> passes if you give one. A download that keeps trickling never stops by itself, so set --download-timeout-ms in CI. While it runs, reflow init prints its progress on stderr: which plugin, which download of how many, MB done of the total, percent, rate and time left. On a terminal the line is redrawn about once a second; in a CI log or another program’s output it is a plain line at each further 10% and at least every 15 seconds, including while no data arrives. --json keeps stdout to one result object, and --log-level error prints no progress. For example:

Reflow: downloading Lean (2 of 3, 290.0 MB). It stops only if no data arrives for 60 s.
Reflow: downloading Lean (2 of 3): 29.0 of 290.0 MB (10%), 4.1 MB/s, about 1 min 4 s left.
Reflow: downloaded Lean (2 of 3, 290.0 MB) in 1 min 11 s; verifying it.

A download that stops says which plugin, how far it got and what to do. Its partial file is deleted and nothing is changed: run reflow init again to start it over. Every archive is checked against the size and digest its release manifest pins before anything is installed. Through MCP, init_plugins takes download_timeout_ms and sends the same lines as progress notifications when the request carries a progressToken.

MacOSApp’s desktop provider is not bundled or release-qualified; its source catalog selects the A2 build, and host acceptance of the A3 build is pending. Its separate guest executor runs native app journeys inside SwiftVM guests. See MacOSApp availability.

SwiftVM is a working prototype with vm.doctor, vm.template_verify and vm.guest_run, released as a prebuilt optional provider for macOS on Apple Silicon. It requires a prepared macOS guest template. See installation and limits.

Choose an application collection and test storage location during onboarding. Use that collection when selecting the target below.

A flow declares an alias and the plugin it uses. The alias also selects the private connection unless you give it a different binding name:

providers:
site: {use: Browser, binding: preview}
db: PostgreSQL

Here site uses the connection named preview; db uses the connection named db. Save those connections in a private JSON file:

{
"preview": {"provider": "Browser", "configuration": {"browser": "chromium", "targetUrl": "http://localhost:3000"}},
"db": {
"provider": "PostgreSQL",
"configuration": {"connectionString": "postgresql://test_user:replace-me@127.0.0.1:5432/test_db"}
}
}
Terminal window
chmod 600 /absolute/path/to/bindings.json
reflow target http://localhost:3000 --group checkout --collection <collection-id> --bindings /absolute/path/to/bindings.json

Keep credentials and machine-specific paths in the private file. Flow aliases and bindings are saved with the test, in Reflow or in Git. Each plugin page contains a complete flow example and explains its required configuration.

All flows and devices in an application collection use the same selected release of each plugin. Different applications can select different releases. Reuse the intended collection across scenarios, and skip init when list_plugins confirms the required locked providers are installed. A flow only declares aliases and bindings; do not add a plugins block or copy version hashes.

reflow init creates the application’s generated lock on first use. Later calls install or verify that same selection, including checksums for the current platform. They do not silently upgrade it when you update the CLI. Public releases retain an exact distribution and manifest hash. First initialization and explicit upgrades verify every platform archive the release declares and record those platforms in one lock: macOS on Apple silicon for current releases, all four macOS/Linux arm64/x64 targets for older ones. A fresh device can then retrieve its selected platform archive even with a newer CLI. Cached bytes are verified before reuse; no older CLI is executed.

Source builds use the locked commit’s build recipe and require its exact toolchain and runtime bytes. Supply the source checkout with --plugin-source. Source-built and public packages can have different runtime layouts; Reflow never substitutes one for the other or overwrites an existing platform checksum. A source-mode lock can add a platform only after initialization on that platform. Adding another platform’s checksums does not stale devices whose own selected bytes are unchanged.

Change the selection explicitly with:

Terminal window
reflow init --collection <collection-id> --upgrade

Stop active application executions before upgrading; an upgrade applies immediately across the application’s devices and Git branches. There is no lock file to commit or rebase: every branch uses the collection’s lock in Reflow, and each device runs reflow init once to install it.

With no plugin names, --upgrade moves every selected plugin to this CLI’s bundled release. With names, for example reflow init Browser --collection <collection-id> --upgrade, it moves only those plugins, adds any that are not selected yet, and keeps every other selected plugin exactly as locked. It never removes a plugin from the selection, and no command currently removes one. Init prints which plugins were upgraded, added and preserved, with their source commits.

A lock records one release for all of its plugins. If a plugin you did not name could not stay exactly as locked under this CLI’s release (it bundles another version, different package bytes, or not every locked platform), init refuses, changes nothing and lists those plugins. Name them as well, or pass no names to upgrade the whole selection.

Plugin versions are kept in Reflow with the application, whether its tests are in Git or in Reflow. Init writes a private device copy of the lock into the plugin cache and nothing into your checkout; a .reflow/plugins.lock.json in the checkout is not read, and init says that you can delete it. Delete it once every device and CI job runs a current CLI: older CLIs still read and check that file. Do not hand-edit the device copy: the acknowledged shared selection is authoritative. Use --repo /path/to/checkout when initializing a Git application from another directory. Exact-head PR checks use reflow init --lockfile-readonly: they install the collection’s lock and never change it. A missing platform must be initialized on that platform before that check.

When someone changes an application’s plugins, plan and apply on other devices stop with one line that names the application and the changed plugins, for example “The plugins for checkout-app changed (Browser, PostgreSQL). Run reflow init to install them.” Plan and apply never install plugins themselves.

The lock records source provenance, the command descriptor and package checksums so Reflow can verify the selected schema and installed binary/runtime. Missing, corrupt or stale local installations fail before execution and direct you to run init. Plan and apply never install plugins. Existing runs retain the exact selection they used; changing a provider invalidates reuse for affected flows. Use list_plugins or the application’s Plugins page to inspect its selection.

Where the disk supports file clones (APFS on macOS; Btrfs or XFS with reflink on Linux), applications on one device share the disk space of each plugin build that init installs: init keeps one copy under the device’s plugin cache and gives each application its own clone of it. Elsewhere each application keeps its own full copy. Do not link or bind-mount directories between applications inside the plugin cache (~/.reflow/plugins): that is unsupported, and init refuses the links it finds.

After it succeeds, reflow init removes old plugin versions from the device’s plugin cache and says what it removed and their logical size (pluginStorage in --json output and in the MCP init_plugins result); where copies share disk blocks as clones, less disk space may be freed. A version is removed only when all of these hold; otherwise it stays, and init says why:

  • No application on this device selects it in its current lock, however long ago that application was last used.
  • Its application’s plugin selection has not changed on this device for 30 days, so runs started or queued before an upgrade keep their plugins, whichever CLI version started them. A reflow init that leaves the selection as it was does not count as a change (an older CLI’s init does, which only keeps more).
  • No plan or run on this device has used it for 30 days. A version this CLI has not seen in use before (one an older CLI installed) starts its 30 days at the next init.
  • No running process uses it, and the CLI could inspect every process it needs to. On Linux, some programs (for example ssh-agent and gpg-agent) stop other programs of the same user from inspecting them. While one of them runs, init cannot be sure no process uses an old version, so it removes nothing and says why. On many Linux desktops this means old plugin versions stay until you stop such a program before running reflow init.
  • It is not a development or source build.
  • It can be downloaded again from the release it was installed from: that release still publishes exactly this build and has its archives at the release’s origin. Another release that carries the same build never counts. For a version an older CLI installed, which does not record its release, a release this device knows must publish exactly that build and still have its archives.
  • The plugin cache’s folders are plain folders, and the current plugins use only files inside their own installation. Where that is not so, init removes no old version anywhere on the device that time and says why.

Init never waits for this and never fails because of it: when another Reflow command is using the plugin cache, init skips removing old versions that time and says so; a later init removes them. Removing takes at most a minute; what is left then waits for a later init. The preview can list a version that init then keeps. Removing only removes: copies of one build in several applications are left as they are. reflow init --dry-run, and the preview reflow init --upgrade --dry-run (which, when the upgrade changes the application’s plugins, keeps that application’s versions as the upgrade would), only report what init would remove. Plan and apply never remove plugins.

An application’s lock can name a plugin this CLI cannot install by itself: an optional plugin another device added with a newer CLI, or a provider another device built from its own source repository (perhaps for another platform only). Init names that plugin and, when the lock’s release tells which, the way to install it (reflow upgrade, or reflow init --plugin-source <repository> --trust-plugin-source); otherwise, and in plan and apply, both are named. Until then, init installs the application’s other plugins without changing its selection, and flows that do not use that plugin run.

Terminal window
reflow plan
reflow apply
reflow dashboard

Planning reads declarations and retained evidence without executing plugin steps. Apply runs the required work. Every invocation produces a terminal outcome; the plugin decides which state and artifacts it retains. Browser snapshot deliberately captures a screen, while Bash commands and SQL queries retain their output directly. See snapshots and review.

Only commands with declared scalar return values can be used in capture, such as Mailbox’s address or code commands and OpenAPI’s call_value. Other plugin snapshots remain reviewable evidence; they are not automatically flow variables. See values and outputs.

To add application-specific commands, read Writing plugins. The RFL core and Go provider framework are licensed under Apache-2.0. Their repository remains private and a public SDK release is pending, so custom providers currently require source access and a matching Reflow build.

For LocalBash and DockerUbuntu, Reflow replaces known input values and private binding strings in captured text with placeholders such as ${inputs.gramDir} and ${bindings.shell.cwd} before storing team-visible evidence (shell is the configured binding name). Only bindings declared by the flow participate; numeric/boolean configuration switches and the public filesystem root cwd: "/" are not private strings. Neither are the exact selected target origin and granted navigation origins, such as a Browser targetUrl of http://localhost:3000; navigation refusals name them.

Some values are never replaced:

  • A matrix value (${matrix.side}): the flow states it and the variant’s name shows it.
  • An input declared private: false, such as a commit or a branch name: commit: {type: string, private: false}. Every other input is private.
  • A true or false input.
  • A private value of fewer than 4 characters, whether an input, a team variable or a binding string. It cannot be kept secret, and replacing every 1 or ok would rewrite the evidence. reflow plan names a text input whose value is that short.

A private value of 4 to 7 characters is replaced only where it stands alone, with no letter or digit directly before or after it; an escape or percent-encoding that ends just before it (\n, %3D) counts as a separator. A private head is replaced in side=head, /head/ and %3Dhead, while headers stays as written. A value of 8 characters or more is replaced wherever it appears, including inside a word, a URL or a percent-encoded query. This also covers command text, stdout/stderr in stored state, rendered reports, and extra rendered files. No per-command sed filter or opt-in flag is needed. Local source files and the values supplied to the command remain unchanged.

ANSI terminal formatting is removed before matching. Valid UTF-8 files without remaining binary control bytes are treated as text even when their media type is application/octet-stream. Binary files containing a known private value in UTF-8 or UTF-16 are withheld, with an evidence warning; unaffected binary files keep their exact bytes. The stored state identifies this as a derived review view and lists redacted, withheld and renamed files. Name collisions receive unique suffixes; retained file hashes describe the corresponding retained bytes. Canonical shell reports preserve the typed exit code and truncation flag. JSON string tokens, including JSON-lines and nested encoded JSON, are decoded for matching standard Unicode and HTML escapes. Complete raw private values take priority over shorter fields inside them. Replacements are applied together, so new placeholders are not filtered again. Crossing matches receive an explicit overlap marker; a report spelled identically to a complete private value becomes a placeholder. Unaffected numeric spelling and formatting are preserved. Deeply nested strings receive a withholding marker. The resulting review copy is not guaranteed to retain the original file format. Do not treat this review view as the original provider snapshot for a raw-state comparison.

Redaction preserves command success, failure and unknown completion; it does not retry a command. Matching covers complete known values and their JSON-escaped forms, by the length rules above. It does not detect arbitrary fragments, compressed or other encoded copies, reformatted JSON, line-ending conversions, or text visible inside images. Explicit flow captures, Browser screenshots and other providers have their own evidence contracts; this shell-evidence filter does not make those safe to publish secrets. Known private values are also filtered from step failure messages, by the same rules. Already shared evidence is not rewritten.