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.

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

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.
MacOSApp	Drive an isolated copy of a native macOS app through Accessibility; retain assertions, accessibility trees and window captures. Not yet released; not bundled.

The public CLI includes all five plugins. After choosing an application, install them with reflow init --collection <collection-id>, or select names with reflow init Browser PostgreSQL --collection <collection-id>. 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.

MacOSApp is not part of the public CLI and is not yet released: it will be built from its private source repository with reflow init --plugin-source, --plugin-catalog-commit and --trust-plugin-source, and will need Go and the Xcode Command Line Tools. See its availability note; no install command is published yet.

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: 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"}
  }
}

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.

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. 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 the macOS/Linux arm64/x64 archives and record all four platforms in one lock. 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> --upgrade

Stop active application executions before upgrading; an upgrade applies immediately across the application’s devices and Git branches. Afterward, run init and commit the generated lock on other branches, or rebase them onto the lock commit. Reviewing the Git file does not delay the shared upgrade. To change plugin names, pass the complete desired set, for example reflow init Browser PostgreSQL --collection <collection-id> --upgrade.

For Git test storage, commit the generated .reflow/plugins.lock.json alongside your flows. For Reflow test storage, the application keeps the shared lock and init materializes a private device copy. The storage choice is retained when the lock is first created. Do not hand-edit either copy: the acknowledged shared selection is authoritative. Use --repo /path/to/checkout when initializing a Git application from another directory. One checkout has one shared plugin selection. If two teams use different selections for the same repository, use separate checkouts or worktrees. Exact-head PR checks use reflow init --lockfile-readonly: they install the acknowledged selection without updating shared state or the Git file. A missing platform must be initialized and committed before that check.

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.

Run and review

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. 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

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. 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, including short values. 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. Already shared evidence is not rewritten.