LocalBash plugin
Use LocalBash for an application command, worker or test script that runs on the same machine as your Reflow CLI. Each invocation keeps its output and exit status as evidence. Use DockerUbuntu for commands inside an existing Ubuntu container.
Connect
Section titled “Connect”Select your application collection during onboarding. Use its ID in the target command below.
Install the bundled plugin with reflow init --collection <collection-id>. The plugin
bundles GNU Bash 5.3; your command’s own dependencies must be available on the machine.
Save this private connection as bindings.json, replacing the directory with your
application’s absolute path:
{ "worker": { "provider": "LocalBash", "configuration": {"cwd": "/absolute/path/to/your/app"} }}cwd is required and must exist; it is the only configuration key. Commands run
on the bundled Bash without interactive profile or rc files. Use explicit commands; aliases from your interactive shell are not loaded.
Keep the bindings file out of Git.
chmod 600 /absolute/path/to/bindings.jsonreflow target --group worker-tests --collection <collection-id> --bindings /absolute/path/to/bindings.jsonPlan and apply check the application’s plugin lock and each declared binding.
The binding values stay on the device; shared shell evidence redacts known
private values. reflow init installs plugins; reflow target --bindings selects
their private configuration.
This also applies to explicit Browser aliases such as providers: {site: Browser}:
select a site entry with provider: "Browser" and configuration: {} to use
defaults. Implicit Browser statements without a provider declaration need no
private binding. Evidence reads and published reviews do not include the bindings
file.
Write a flow
Section titled “Write a flow”Copy this into /tmp/worker-output.md, outside your checkout.
This example needs only Bash:
---name: Capture command outputproviders: worker: LocalBash---
### Capture command output
```rflworker.bash command="printf 'worker ready\n'" checkpoint="worker-output"```Create the test in the team’s chosen location, then run it:
reflow flows create --name worker-output --file /tmp/worker-output.mdreflow plan worker-outputreflow apply worker-outputreflow dashboardReplace the printf command with the application executable under test, or with a
helper script the flow carries as a flow file.
Keep the logic in the script and let command only run it, passing paths and values
as arguments: no pipes, redirections or && chains in the command string.
A saved test must run on another machine: keep setup, assertions and cleanup in the
saved flow and its scripts. Undo what a step made in a
cleanup step, not with trap … EXIT
or || true in a script: it runs after the flow’s steps even when one failed, and
its own failure is reported. Temporary files go under REFLOW_STEP_FILES, which is
emptied after every step.
Commands may run the application’s executables and files committed to its repository,
never a script that exists only in your working directory, home directory or a private
binding. Credentials and endpoints stay in private bindings. Each command accepts at most
65536 UTF-8 bytes; split larger tests into bounded steps.
The alias worker selects the private connection with the same name. See
plugin setup for aliases and bindings.
Declare the tools the commands need
Section titled “Declare the tools the commands need”List the programs a flow’s commands run in its frontmatter, per alias, instead of
checking for them in a script (command -v uv || …, export PATH=…):
providers: worker: LocalBashrequires: worker: [go>=1.26, uv]When the first step that acts starts, LocalBash looks each tool up exactly as a
command of that alias would: the same cwd and environment, an executable file on
PATH. That PATH is the Reflow device service’s, not your terminal’s, and no binding
setting changes it: install tools there before the flow starts. An export PATH or
an install inside a step cannot satisfy the check, so leave a tool a step installs
for itself out of requires:. A tool without a floor is never run; with one,
Reflow runs go version (no toolchain download), java -version or
tool --version, for at most 5 s. A missing, older, pre-release or unreadable
version fails the flow before any authored command, naming every one:
go 1.22.3 is older than go>=1.26; uv is not on its PATH [tool_unavailable].
Reflow checks; it never installs a tool or changes PATH. See
the language guide.
Carry helper scripts in the flow
Section titled “Carry helper scripts in the flow”Declare a helper as a fenced block whose info string is file="relative/path",
optionally preceded by a language for highlighting. LocalBash receives every
declared file in a fresh private directory named by REFLOW_FLOW_FILES. Plugins
that read flow files, such as TLA, receive the same directory.
---name: Order totalsproviders: worker: LocalBash---
```python file="check_totals.py"import json, subprocessorders = json.loads(subprocess.check_output(["./bin/list-orders", "--json"]))assert sum(o["total"] for o in orders) == 4200, ordersprint("totals ok")```
### Check totals
```rflworker.bash command="python3 \"$REFLOW_FLOW_FILES/check_totals.py\"" checkpoint="totals"```- The file’s bytes are the block body exactly. The opening fence starts at the beginning of its line and the block is closed; a body line of three backticks, optionally surrounded by whitespace, would close it early.
- Paths use letters, digits,
.,_,-and/, with no.or..segment. Paths may not differ only in letter case, and a file cannot also be a directory. A flow declares at most 8 files, each at most 64 KiB and 192 KiB in total; the whole flow, files included, stays within its 256 KiB source limit. - The directory is not the working directory. Commands still run in the
binding’s
cwd; refer to files as"$REFLOW_FLOW_FILES/<path>". Write$REFLOW_FLOW_FILESwithout braces: RFL interpolates${…}in plugin arguments. - Files are read-only, written before the first LocalBash command and removed after
the run.
files=captures outputs belowcwdand cannot capture them. - Editing a file changes the saved flow, so plan/apply reruns its steps instead of reusing earlier results.
On the author device, saving refuses a test whose LocalBash commands run as a
program or interpreter script, source, read with < or copy a local file that
another machine would not have, and names the path and the fix:
- Tests kept in Reflow carry helpers as flow files. Application files they use must be committed to the application repository.
- Tests kept in the repository may instead commit helpers beside the test, for
example
.reflow/flows/order-totals/check_totals.py, staged with it. - Refused: files that are not committed (or staged, for repository tests), missing, outside the checkout (including your home directory), ignored by Git outside build and dependency directories, or reached through an absolute path into the checkout (write it relative to the working directory instead).
- Fine: installed runtimes and tools, paths the flow writes before it uses them
(such as heredoc output), and build or dependency output such as
dist/,target/,.venv/ornode_modules/.
Other arguments, such as jq . data.json, are not inspected. A hosted
connection has no checkout: it refuses invalid flow files and returns unverified
paths as portability_warnings.
Saving also checks the authoring rules on every connection. Creating a flow is
refused when a command uses shell logic (inline-shell: a pipe, &&, ;, a
redirection, a heredoc, $(…), a VAR=x prefix or -c/-e code), is over 300
characters (long-command), carries an encoded blob (encoded-blob), names a home
or .local/ path (local-path), runs a script from the working directory that the
flow does not carry (uncarried-script) or contains a token-shaped literal
(secret-literal). Calling psql, curl, docker exec or an MCP client from a
script is a warning that names the plugin to use instead, and so is starting a
server in the background (background-process). Saving an existing flow
and reflow plan only warn. Your agent’s flow-authoring skill lists every rule.
Keep files for the rest of a step
Section titled “Keep files for the rest of a step”Every step gets a fresh private directory named by REFLOW_STEP_FILES. It is
empty when the step starts and emptied when the step ends. A command writes
there, and a later statement of the same step reads it: another command, or a
plugin that reads step files, such as TLA:
worker.bash command="./bin/record-events \"$REFLOW_STEP_FILES/events.ndjson\""tla.trace spec="Orders.tla" trace="step:events.ndjson"That example assumes your application’s ./bin/record-events writes its events
to the path it is given. Pass the path to a carried script the same way.
- The next step starts with an empty directory: write and read within one step.
- The directory holds at most 64 MiB. A statement that leaves more there fails the step.
- Its files are not evidence and are not uploaded. Capture what reviewers need
with
files=belowcwd. - Write
$REFLOW_STEP_FILESwithout braces, like$REFLOW_FLOW_FILES.
Check results with expect
Section titled “Check results with expect”State what a command must do in the flow with expect, instead of an if … exit 1
or an assert inside a script. The script prints what it found; the flow says
what must hold. expect takes a JSON object, written most readably as a json(
block in a grouped call:
---name: Order reportproviders: worker: LocalBash---
```bash file="report.sh"# Prints the order report for the region in the first argument as one JSON object.set -euo pipefail./bin/orders report --region "$1" --json```
### Check the order report
```rflworker.bash ( command="bash \"$REFLOW_FLOW_FILES/report.sh\" eu" expect=json( {"exit": 0, "json": [{"pointer": "/status", "equals": "ok"}, {"pointer": "/elapsedMs", "lessThan": 1500}]} ) checkpoint="order-report")```| Key | What must hold |
|---|---|
exit | The exit status, or a list of accepted ones. It is 0 when omitted. A nonzero value states an expected failure: the step passes when the command fails that way. |
stdoutIncludes, stderrIncludes | The stream contains this exact text, or each text of a list. Texts match bytes exactly: \n does not match a \r\n line ending. |
stdoutExcludes, stderrExcludes | The stream does not contain the text. Truncated output of that stream cannot prove absence, so it fails. |
json | Assertions on stdout parsed as one JSON value. Each has a pointer (RFC 6901; "" is the whole output) and one operator: exists, equals, type, count, includes, lessThan, lessThanOrEqual, greaterThan or greaterThanOrEqual. Numbers compare exactly as decimals; operands must lie within ±9007199254740991, so compare larger numbers as strings. |
stepFiles | Files the command left in $REFLOW_STEP_FILES: a path with exists (true or false) or nonEmpty: true. A link out of the directory is not followed. |
The one-line form expect="{\"exit\":2}" is accepted too, but the json( block
is easier to read and to change. In either form ${…} is still RFL
interpolation: write $${ for a literal ${ in a text you expect.
Without expect, a nonzero exit status fails the step. With it, the step passes
only when every check holds, and the result records each check under expect
(met and checks). An unmet check is a judged result: the command completed
and what it produced did not hold. The step error lists every failed check with
what was expected and what was received (a value over 200 characters by its
length only):
Plugin LocalBash.bash failed: exit code 0; stderr is empty; expect.json[1] "/elapsedMs": expected lessThan 1500, received 2140 (value_differs)A command that could not run is not judged. When Bash does not start, or the
command exits 126 (found but not executable) or 127 (not found) and exit does
not name that status, the step fails with a fixed reason such as the command could not run: exit status 127 (command not found) and no expect record. An
invalid expect is refused before Bash starts, with a message that names the
mistake.
A negative test names the failure it expects:
worker.bash ( command="./bin/import --dry-run missing.csv" expect=json( {"exit": 2, "stderrIncludes": "missing.csv: no such file"} ))For json, stdout must be exactly one JSON value in valid UTF-8; print progress
and logs to stderr. A script that prints a bare number can be compared whole with
the pointer "", for a timing or a count:
worker.bash ( command="bash \"$REFLOW_FLOW_FILES/import-ms.sh\" orders.csv" expect=json( {"json": [{"pointer": "", "lessThanOrEqual": 1500}]} ))Branch on a command, and wait without a loop
Section titled “Branch on a command, and wait without a loop”A bash call with expect can decide an if or unless. It runs once: checks
that hold take the block, checks that do not take else, and a command that
could not run (or exited with a status expect does not name) fails the step.
Have the command finish its lookup and print the answer as JSON with exit status
0, exiting nonzero only when it cannot tell, and check the JSON without exit:
unless worker.bash command="\"$REFLOW_FLOW_FILES/has-package.sh\"" expect="{\"json\":[{\"pointer\":\"/exists\",\"equals\":true}]}" worker.bash command="make package"Here has-package.sh prints {"exists":true} or {"exists":false}, so only a
confirmed absence runs make package; a lookup that failed fails the step.
Do not use expect="{\"exit\":0}" for this: with an exit status named, every
other status, a command’s own error included, is a check that did not hold.
Because a bash condition may change something, and that change stays whichever
block runs, prefer a command that only reads.
bash cannot wait with within=: running it again could repeat what it changed,
so planning refuses it (within_not_repeatable). Do not poll in a script either
(saving warns: wait-loop). Run the change once, then wait on a read of its
result: observe or file below, a PostgreSQL query, an OpenAPI read, an
MCP read or a Browser expect with within=; see
wait for a check to hold.
Wait for a status with observe
Section titled “Wait for a status with observe”observe runs a command that only reads, such as a CLI’s status query (gh run view, kubectl get, your product’s status --json), and checks its output with
the same expect as bash. Because it only reads, it can wait with within=,
which replaces a script that loops with until and sleep:
worker.bash_value command="\"$REFLOW_FLOW_FILES/start-run.sh\"" select="/id" -> run_idworker.observe ( command="gh run view ${run_id} --json status" expect=json( {"json": [{"pointer": "/status", "equals": "completed"}]} ) within=20m every=20s timeout=30s)worker.observe command="gh run view ${run_id} --json conclusion" expect="{\"json\":[{\"pointer\":\"/conclusion\",\"equals\":\"success\"}]}" timeout=30sWait for the state to settle, then check the outcome once: a wait on the
conclusion being success would keep polling until within ends after a run
that failed.
- Read-only is your declaration. LocalBash runs
observeexactly as it runsbashand cannot tell a read from a write. Never observe a command that changes anything: Reflow may run it many times. commandruns one program or carried script with arguments, asbash’s does (saving checks it the same way);expectmust state at least one check, and should check the status itself:{"exit":0}alone holds while it is pending.observekeeps no files and returns no value: usebashandbash_valuefor those.- A pending answer does not hold, so a wait runs it again. An exit status that
expectdoes not name (the CLI’s own error, such as a network failure) or output that is not one JSON document forjsonfails the step at once, so leaveexitout when you check JSON. within=bounds when the last attempt may start, not how long one runs: give a remote read its owntimeout=.- A passing step is reused on a later plan like any other: read a status by a
specific id, and
reflow taintthe flow to look again.
Wait for a file with file
Section titled “Wait for a file with file”file checks one path below cwd without running anything: whether it exists,
is a nonempty file, contains a text, or holds JSON values. Because it only
looks, it can wait with within=, which replaces a script that sleeps until a
report, a log line or a ready marker appears:
worker.bash command="bash \"$REFLOW_FLOW_FILES/start-agent.sh\""worker.file path="agent-report.md" expect="{\"nonEmpty\":true}" within=10m every=2sexpect takes exists (true or false), nonEmpty: true, includes and
excludes (exact text, or a list) and json (the same pointer checks as
bash, on the file parsed as one JSON value). At most 512 KiB is read, and only
the failed checks’ expected and received values are retained.
The path is written in the flow, so a reader sees exactly which file the step
waits on: a normalized relative path below cwd, or $REFLOW_STEP_FILES/
followed by one for a file an earlier command of the same step wrote there.
Planning refuses ${…} from an input or a capture in it
(argument_not_literal: path must be written in the flow). A link that leads
out of its directory is never followed.
worker.bash command="bash \"$REFLOW_FLOW_FILES/export.sh\" \"$REFLOW_STEP_FILES/export.json\""worker.file path="$REFLOW_STEP_FILES/export.json" expect="{\"json\":[{\"pointer\":\"/rows\",\"greaterThan\":0}]}" within=1mA missing path, an empty file, a directory, text not yet in a complete file or a JSON value that differs does not hold, so a wait looks again. A path that cannot be read, a file over 512 KiB that would have to prove a text absent, and content that is not exactly one JSON value (such as half of one) fail the step at once. Publish JSON you wait for by atomic rename: write it to a temporary name in the same directory, then rename it into place, so a wait never reads half of it.
Run a server for the flow with service
Section titled “Run a server for the flow with service”A stub server, or the product under test, that must stay up across steps is a
service. Do not start it in a script with &, nohup or Popen, poll it and
kill it: LocalBash ends what a command left running when the command finishes,
and saving warns (background-process). service starts one program or carried
script, waits until it is ready, keeps it for the rest of the flow and returns
its port for -> name. stop ends it in a cleanup step and keeps its output:
---name: Client falls back after a timeoutproviders: worker: LocalBash---
```python file="stub.py"# Answers /ping at once and /slow after five seconds, on the port it is given.import http.server, sys, timeclass Stub(http.server.BaseHTTPRequestHandler): def do_GET(self): if self.path == "/slow": time.sleep(5) self.send_response(200) self.end_headers()http.server.HTTPServer(("127.0.0.1", int(sys.argv[1])), Stub).serve_forever()```
### Start the stub
```rflworker.service ( name="stub" command="python3 \"$REFLOW_FLOW_FILES/stub.py\" $REFLOW_SERVICE_PORT" port="auto" ready=json( {"http": "/ping"} ) timeout=30s) -> stub_port```
```rfl cleanup step="Stop the stub"worker.stop name="stub"```
### The client falls back within 1.5 seconds
```rflworker.bash ( command="./bin/client --url http://127.0.0.1:${stub_port}/slow --timeout 1s --json" expect=json( {"json": [{"pointer": "/fallback", "equals": true}, {"pointer": "/elapsedMs", "lessThan": 1500}]} ))```nameis written in the flow: 1 to 32 letters, digits,-or_, one running service per name.commandstays in the foreground (no&, no daemonizing) and runs incwdlikebash’s;$REFLOW_SERVICE_PORTis its port.port="auto"picks a free loopback port. A fixed port is written as text,port="8080", and is refused when something already listens on it. The port is returned as text.readyis{"tcp": true}(the default: something accepts connections on 127.0.0.1 at the port) or{"http": "/path"}(a GET answers 2xx, or thestatusyou name; redirects are not followed). It is checked every 100 ms until the statement’stimeout=(30 s by default). An answer counts only when the port’s listener is one of the service’s own processes, so another program that holds the port is never taken for the server.- If the server exits first, or is not ready in time, the step fails with its exit status or the last check’s answer and the server’s output, and it is stopped: a failed start leaves nothing running.
- It runs until
stopor the end of the run, whether the run passed, failed, timed out or was cancelled.stopsends TERM, waits 5 s, then kills what is left. It fails when the server had already exited, so a crash during the flow fails the run with its output. Stopping a service whose start failed passes. Without astopin a cleanup step the server is still stopped, but its output is not kept (saving warns:service-without-stop). - The
serviceandstopresults keep the last 256 KiB of stdout and stderr, starting on a whole line when earlier output was dropped. - A flow that starts a service, itself or in a flow it
uses, runs whole: a later run never reuses the step that started it, because the server ended with its run. A held run keeps the server up while you inspect it; the next apply ends the hold and replays the flow from its first step. A used flow that keeps a browsersession:cannot start a service.
service and stop cannot wait with within=. DockerUbuntu has no service
yet.
Return a value with bash_value
Section titled “Return a value with bash_value”bash_value runs a command like bash and returns one value from its JSON
stdout, so -> name can capture it for later steps. Pass the value on as an
argument of a carried script, never as part of shell logic:
worker.bash_value command="./bin/orders create --json" select="/id" -> order_idworker.bash ( command="bash \"$REFLOW_FLOW_FILES/show-order.sh\" ${order_id}" expect=json( {"json": [{"pointer": "/status", "equals": "open"}]} ))select is a JSON Pointer into stdout parsed as JSON. The step succeeds only when
the command succeeds (or meets its expect) and the pointer names a string,
number or boolean of at most 4 KiB; it returns that value as text. RFL pastes
${order_id} into the command as written, so the value must be a safe token:
letters, digits and . _ : / @ + -, not starting with -. Anything else fails
the step. raw="true" returns any printable text; use such a value only in an
argument another plugin treats as data, never in a command. The value is kept in
evidence and flows into later arguments, so never select a secret.
Commands
Section titled “Commands”worker.bash accepts:
| Argument | Type | Meaning |
|---|---|---|
command | string, required | Bash source to run in the configured directory. |
files | string, optional | A JSON array of relative output file paths to retain after the command. It never supplies inputs. |
expect | string, optional | A JSON object of expectations the completed command must meet. |
worker.bash_value accepts the same arguments, a required select, the JSON
Pointer of the value it returns, and an
optional raw="true".
worker.observe takes command and expect, both required. See
wait for a status.
worker.service takes name, command and port (required) and ready;
worker.stop takes name. See run a server.
checkpoint is a host RFL modifier for the invocation’s retained evidence, not a
LocalBash command argument. RFL removes it before provider argument validation and
dispatch, so it is absent from the bash descriptor returned by list_plugins.
Use a literal label of 1-128 letters, digits, underscores or hyphens. Other unknown
arguments are still rejected. It is not a separate shell command or a screenshot
of a terminal.
For a command that writes a report:
worker.bash command="./bin/check-orders --report report.txt" files="[\"report.txt\"]" checkpoint="order-report"That example assumes your application supplies ./bin/check-orders, which writes
its report to the path given with --report. Selected files
must exist inside cwd; absolute paths and paths that escape it are rejected.
Each captured file is limited to 4 MiB. Stdout and stderr are each limited to 1 MiB and indicate truncation when it
occurs. A truncated result cannot establish full equality during comparison.
Escape shell parameter expansion
Section titled “Escape shell parameter expansion”Most commands need no shell syntax of their own: put the logic in a carried script and pass values as arguments. A script’s bytes reach Bash exactly as written, so it needs no escaping. This section is for the rare command that must expand a shell parameter itself.
In a quoted plugin argument, write $${ for a literal ${. RFL consumes the
extra dollar once, then Bash receives the original shell parameter expansion.
This applies to both LocalBash and DockerUbuntu. Shell quotes alone do not stop
RFL interpolation.
worker.bash command="./bin/report --out \"$${PWD:-.}/report.txt\""Bash receives ./bin/report --out "${PWD:-.}/report.txt". An ordinary
${inputs.name} in the same command still resolves a declared Reflow input.
For nested shell expansions, escape each opening:
$${VAR:-$${OTHER:-default}}. Pipelines, ${PIPESTATUS[0]} and anything beyond
one command with arguments belong in a carried script.
Use double-quoted RFL strings and JSON escapes for quotes/backslashes. \${ is
not a supported RFL escape; $${ is the literal-opening syntax. This is separate
from shell quoting: to prevent Bash from expanding the resulting ${...}, quote
it appropriately in the shell command too. See the
language reference.
Keep generated reports outside the checkout
Section titled “Keep generated reports outside the checkout”cwd does not have to be your application checkout. For a knowledge-base PoC,
create a private work directory outside the repository and use its absolute path
as the LocalBash cwd. Stdout and stderr are retained automatically without
creating report files in the checkout. If you need a captured report file, carry
a script that runs the application command in its directory and writes the report
to a path below the private working directory:
```bash file="order-report.sh"# Runs the order check in the application directory (first argument) and writes# its output to the report path (second argument, below the working directory).set -euo pipefailreport="$PWD/$2"cd "$1"./bin/check-orders > "$report"```
```rflworker.bash command="bash \"$REFLOW_FLOW_FILES/order-report.sh\" /absolute/path/to/your/app report.txt" files="[\"report.txt\"]" checkpoint="order-report"```Replace the path and command with your application’s actual command. The script
changes only its own working directory; report.txt is written under the
configured private cwd. The command itself can still create application files,
so use its own output-directory option when appropriate. Capture does not follow
symlinks that escape cwd; an external symlink is not a supported workaround.
There is currently no separate evidenceDir configuration.
Evidence and failures
Section titled “Evidence and failures”The snapshot retains stdout, stderr and exit code, plus requested files. A nonzero
exit, unless expect names it, is a failed result whose output remains available
for diagnosis. No additional
snapshot command is needed. Comparing two results uses the retained outputs and
file hashes; a successful exit does not mean their contents are unchanged.
Shared shell evidence redacts known private values from text and withholds affected binary files. Local files remain unchanged.
Use snapshots and review to inspect changes, and repair and rerun when a command or its expected result changes.
Flows using this plugin can be saved in Reflow or in your repository. Read test storage for the team preference, private bindings and the shared plan/apply workflow.
Keep managed consent hooks in the flow
Section titled “Keep managed consent hooks in the flow”For MCP tests using managed consent identity, private bindings can select
setCommand: "@flow:set" and readCommand: "@flow:read" together. Put the complete
hook source in the saved flow’s consent_hooks frontmatter, keyed by the binding
name, with setCommand and readCommand strings. Each accepts at most 8192
characters. Hooks do not interpolate RFL inputs: read private fixture data from
the configured working directory and the requested identity from the private
REFLOW_PRIVATE_IDENTITY_FILE JSON file. Keep identities and credentials outside
shared source. Planning validates the declaration without executing it; execution
uses the admitted source with the existing identity lock, verification and restore
lifecycle. Missing or mixed declarations refuse rather than using another source.