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.
Choose a plugin
Section titled “Choose a plugin”| Plugin | Use and evidence |
|---|---|
| Browser | Interact with pages and retain viewport or CSS-scoped screenshots. |
| LocalBash | Run host commands; retain output, exit code and files. |
| PostgreSQL | Check database rows or retain results of deliberate setup writes. |
| DockerUbuntu | Run commands in an existing Ubuntu container; retain output and files. |
| Mailbox | Keep a named inbox and capture new email codes or links. |
| OpenAPI | Call declared HTTP operations with typed requests; assert JSON responses and capture public scalar values. |
| MCP inspector | Check 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. |
| ClickHouse | Check ClickHouse rows such as telemetry and events, or retain results of deliberate setup statements. Optional: installed on demand. |
| Lean | Check 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. |
| Bombadil | Explore 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. |
| MacOSApp | Drive an isolated copy of a native macOS app through Accessibility; retain assertions, accessibility trees and window captures. Not yet released; not bundled. |
| SwiftVM: macOS VM | Disposable macOS 27 guests with staged jobs, native app journeys and artifact export. Optional, macOS on Apple Silicon only: installed on demand. |
| SwiftVM: Swift tests | Prototype 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. |
Pick the plugin for the check
Section titled “Pick the plugin for the check”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 check | Use | Not |
|---|---|---|
| A page or UI journey | Browser: role and label targets, expect, site.snapshot | Playwright or Puppeteer in a script; curl and grep on HTML |
| Properties that hold whatever a user does on a screen | Bombadil after Browser steps: explore.run browser="site" spec="app.spec.ts" time=60s | random clicking in site.script; the bombadil CLI in LocalBash |
| Database state | PostgreSQL: db.query … expect=json(…), db.value … -> id, db.execute for setup | psql or a driver in LocalBash |
| ClickHouse state (telemetry, events) | ClickHouse: ch.query … expect=json(…), ch.value … -> id, ch.execute for setup | clickhouse-client in bash, or docker exec … clickhouse-client |
| An MCP server | MCP: connect, tools, call … expect= | a Node or Python MCP client; curl JSON-RPC |
| An HTTP or RPC API | OpenAPI: http.call operationId=… expect=json(…), call_value | curl piped to jq; site.script with fetch |
| An email code or link | Mailbox: inbox.address, capture, extract | polling a mail API from a script |
| A state machine or protocol design | TLA+: tla.check, tla.trace | a hand-rolled model in a script |
| A proof or formal lemma | Lean: lean.check theorems=…, statements=json(…) | lean or lake in LocalBash; a proof checked by hand |
| Commands in a Linux container | DockerUbuntu | docker exec or docker run in LocalBash |
| A native macOS app | MacOSApp (not yet released) | osascript in LocalBash |
| A clean Mac in a disposable VM | SwiftVM: vm.guest_run (optional, macOS hosts only) | ssh or VM scripts in LocalBash |
| Shared setup | use <flow>, or needs | copied steps |
| Values between steps | capture, -> name, outputs | temporary files or environment variables |
| The product’s own CLI or build | LocalBash, 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.
Wait for a check, and branch on it
Section titled “Wait for a check, and branch on it”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=2sif 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.
Downloads
Section titled “Downloads”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.
Connect a plugin
Section titled “Connect a plugin”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: PostgreSQLHere 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"} }}chmod 600 /absolute/path/to/bindings.jsonreflow target http://localhost:3000 --group checkout --collection <collection-id> --bindings /absolute/path/to/bindings.jsonKeep 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.
One selection per application
Section titled “One selection per application”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:
reflow init --collection <collection-id> --upgradeStop 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 initthat 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-agentandgpg-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 runningreflow 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.
Run and review
Section titled “Run and review”reflow planreflow applyreflow dashboardPlanning 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.
Private values in shell evidence
Section titled “Private values in shell evidence”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
trueorfalseinput. - 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
1orokwould rewrite the evidence.reflow plannames 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.