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

Select your application collection during onboarding. Use its ID in the target command below.

Install the bundled plugin with reflow init LocalBash. Bash and 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. Optional bashPath selects the Bash executable; otherwise the plugin uses bash on PATH. Commands run without interactive profile or rc files. Use explicit commands rather than relying on shell aliases. Keep the bindings file out of Git.

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

Write a flow

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

---
name: Capture command output
providers:
  worker: LocalBash
plugins:
  - name: LocalBash
    sourceCommit: 5852a91f8ba9f4c73585a5984a96117a159c068f
    descriptorDigest: c00f906e9113dc65cdcc314cfc0cc7464bbaad5780e6a69bcb1872517fb78d98
---

### 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:

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 your application’s worker or test command. The alias worker selects the private connection with the same name. See plugin setup for aliases and version pins.

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 file paths to retain after the command.

checkpoint is an RFL label for the invocation’s retained evidence. 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.txt" files="[\"report.txt\"]" checkpoint="order-report"

That example assumes your application supplies ./bin/check-orders. 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.

Evidence and failures

The snapshot retains stdout, stderr and exit code, plus requested files. A nonzero exit 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.

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.