Skip to content

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.

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.

Terminal window
chmod 600 /absolute/path/to/bindings.json
reflow target --group worker-tests --collection <collection-id> --bindings /absolute/path/to/bindings.json

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

Copy this into /tmp/worker-output.md, outside your checkout. This example needs only Bash:

---
name: Capture command output
providers:
worker: LocalBash
---
### Capture command output
```rfl
worker.bash command="printf 'worker ready\n'" checkpoint="worker-output"
```

Create the test in the team’s chosen location, then run it:

Terminal window
reflow flows create --name worker-output --file /tmp/worker-output.md
reflow plan worker-output
reflow apply worker-output
reflow dashboard

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

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: LocalBash
requires:
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.

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 totals
providers:
worker: LocalBash
---
```python file="check_totals.py"
import json, subprocess
orders = json.loads(subprocess.check_output(["./bin/list-orders", "--json"]))
assert sum(o["total"] for o in orders) == 4200, orders
print("totals ok")
```
### Check totals
```rfl
worker.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_FILES without braces: RFL interpolates ${…} in plugin arguments.
  • Files are read-only, written before the first LocalBash command and removed after the run. files= captures outputs below cwd and 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/ or node_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.

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= below cwd.
  • Write $REFLOW_STEP_FILES without braces, like $REFLOW_FLOW_FILES.

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 report
providers:
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
```rfl
worker.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"
)
```
KeyWhat must hold
exitThe 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, stderrIncludesThe 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, stderrExcludesThe stream does not contain the text. Truncated output of that stream cannot prove absence, so it fails.
jsonAssertions 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.
stepFilesFiles 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.

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_id
worker.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=30s

Wait 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 observe exactly as it runs bash and cannot tell a read from a write. Never observe a command that changes anything: Reflow may run it many times.
  • command runs one program or carried script with arguments, as bash’s does (saving checks it the same way); expect must state at least one check, and should check the status itself: {"exit":0} alone holds while it is pending. observe keeps no files and returns no value: use bash and bash_value for those.
  • A pending answer does not hold, so a wait runs it again. An exit status that expect does not name (the CLI’s own error, such as a network failure) or output that is not one JSON document for json fails the step at once, so leave exit out when you check JSON.
  • within= bounds when the last attempt may start, not how long one runs: give a remote read its own timeout=.
  • A passing step is reused on a later plan like any other: read a status by a specific id, and reflow taint the flow to look again.

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=2s

expect 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=1m

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

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 timeout
providers:
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, time
class 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
```rfl
worker.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
```rfl
worker.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}]}
)
)
```
  • name is written in the flow: 1 to 32 letters, digits, - or _, one running service per name.
  • command stays in the foreground (no &, no daemonizing) and runs in cwd like bash’s; $REFLOW_SERVICE_PORT is 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.
  • ready is {"tcp": true} (the default: something accepts connections on 127.0.0.1 at the port) or {"http": "/path"} (a GET answers 2xx, or the status you name; redirects are not followed). It is checked every 100 ms until the statement’s timeout= (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 stop or the end of the run, whether the run passed, failed, timed out or was cancelled. stop sends 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 a stop in a cleanup step the server is still stopped, but its output is not kept (saving warns: service-without-stop).
  • The service and stop results 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 browser session: cannot start a service.

service and stop cannot wait with within=. DockerUbuntu has no service yet.

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

worker.bash accepts:

ArgumentTypeMeaning
commandstring, requiredBash source to run in the configured directory.
filesstring, optionalA JSON array of relative output file paths to retain after the command. It never supplies inputs.
expectstring, optionalA 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.

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 pipefail
report="$PWD/$2"
cd "$1"
./bin/check-orders > "$report"
```
```rfl
worker.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.

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.

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.