Where tests are saved

New teams start with Keep tests in Reflow. Your team can share and run tests without adding test files to the application repository. Each test is a Markdown flow with its own saved versions. Application knowledge pages describe how the app works; tests have their own entries under Flows and Knowledge.

Choose a location

During onboarding at app.reflow.io, choose your application and confirm Where new tests are saved. An application collection groups tests for one application, including tests kept in Reflow and tests kept in its repository.

Choose Keep tests in Reflow for a trial without test files in Git. Choose Keep tests in the repository when your team wants to review test source in Git. Owners and admins can change the default in Settings → Team → Test storage. Members use the team default. If you are using the local dashboard, follow its Team settings link to make the change in the hosted app.

Changing the default affects new tests. It never moves an existing test, resets a mailbox or replaces named variables. A collection can contain tests from both storage locations. Each test shows its source location.

Start without adding test files

You still need your application’s Git checkout, its running services and the runtimes declared by your flows. Ordinary plan/apply and dashboard Play use that checkout to detect application changes. Select the checkout as well as the target URL.

After signing in and choosing an application collection during onboarding:

reflow login
reflow init
reflow target http://localhost:3000 --group checkout --collection <collection-id>
reflow config get test-storage
reflow flows list

Select the collection once. Reflow remembers it privately for that target and checkout. To create a collection from the CLI, use reflow flows collection-create --name "My application", then select its returned ID. For GitHub, register its repository with reflow flows collection-bind --collection <id> --repository-id owner/name. A Git checkout without a remote can use the explicit local association. Use the collection ID when selecting an application; names alone may not be unique.

Ask your agent to read get_reflow_context, load flow-authoring and create a small test through manage_flows. It follows the current team default. For human authoring, keep a temporary draft outside the checkout and use:

reflow flows create --name checkout --file /tmp/checkout.md
reflow flows read checkout --json
reflow plan checkout
reflow apply checkout

Wait for Reflow to confirm the save, then read the saved version before running it. To edit a saved test, read it first and supply its version with reflow flows save checkout --file /tmp/checkout.md --base-version <version-id>. If someone else saves first, your draft stays available. Read their version and apply your edits to it before saving again.

Keep private bindings, inputs, plugin caches, captures and installed agent skills outside the application checkout, for example under ~/.reflow/. init installs plugins; it does not create test files or change the team’s preference. Check git status after your trial. Ordinary Reflow operations do not add files or edit .git in knowledge-base mode. An agent’s independent shell edits remain under your instructions and its own permissions.

Plan and run tests

plan and apply use all runnable tests in the selected collection, wherever they are saved. To run a subset, pass a test ID, slug or registered Markdown path. A plan can contain up to 20 flows, including dependencies. Select a smaller subset if your collection is larger.

needs can connect a repository test to a shared test in the same collection. Dependencies resolve to exact source versions before execution. Missing sources, ambiguous identities and conflicting copies stop the affected plan. Repository tests absent from the selected branch are reported as exclusions; a test that depends on one cannot run.

Repeat unchanged to reuse complete evidence. Edit application code or an earlier step to invalidate the affected work. Storage preference changes do not change execution inputs. Taint and reset keep their existing meanings; see Repair and rerun and Test data.

Edit repository tests on the device that has your checkout. flows read returns the file hash to pass as --base-hash when saving. The hosted dashboard can export a draft for you to save there. Reflow also keeps historical copies of the source used for execution; edit the repository file to change future runs.

Renaming a test in Reflow changes its display name and preserves its slug and named data. After renaming a repository file yourself, register its new path with reflow flows map-path <test-id> --path tests/new-name.md. Matching names or contents alone do not establish that two files are the same test.

Move existing tests

Moves are separate from changing the default. Start on the author device with the correct collection and checkout selected. A move keeps the canonical test ID and slug, exact source bytes, historical versions, evidence and approvals.

To move a shared test into Git:

reflow flows move preview checkout --to repository
reflow flows move stage --transfer <transfer-id>
# Review and commit the staged test using your normal Git workflow.
reflow flows move commit --transfer <transfer-id> --commit <full-commit-sha>

The preview lists the versions, dependencies and destination paths to review. Staging stops if a destination contains different text or the path is unsafe. Reflow starts using the repository copy after it verifies your commit and confirms the move. Until then, it uses the shared version. Teammates must update their checkouts to the commit containing the moved tests.

To move a repository test into Reflow:

reflow flows move preview checkout --to knowledge_base
reflow flows move commit --transfer <transfer-id>

The original file remains for explicit cleanup. Reflow recognizes an unchanged former copy without running a duplicate; a divergent former copy is a conflict. Moves leave Git commits, pushes, file cleanup and expectation approval to you. Dependencies can stay in the other storage location within the same collection. Use --keep-dependencies to confirm that choice when a preview lists dependencies you have not selected.

After interruption or an uncertain response, use reflow flows move inspect --transfer <transfer-id>. To abandon a prepared move, use move cancel; already staged files remain yours to inspect. A committed move requires a new reverse transfer. Do not create another transfer just to retry an uncertain response. Authoring responses also retain operation/session IDs for reflow flows operation --operation-id <id> --operation-session <session>.

Existing teams

Teams created before this option keep Repository as their initial default. A Reflow operator must review their existing application and repository associations before enabling collections. Conflicting duplicates need a decision about which source to use. Historical versions and approvals remain available, and activation does not move source files.

Use a CLI version that supports the team’s storage settings. After activation, older authoring and run entrypoints return an upgrade/context error instead of creating another writable head. Exact flow-ID/version runs remain available as explicit historical selections. For CI, follow the collection setup for GitHub Actions. Installed agent skills should read current context before authoring. Reflow does not rewrite your agent instructions when the team default changes.

For an advanced single-flow run without a checkout, manage_device_jobs start executes one exact saved version. It does not provide incremental plan/apply. Review exports must use evidence from the execution that produced them; do not rerun a controller test just to obtain an export.

Reviewed plans and interrupted file creation

A plan has a semantic fingerprint and a separate storage fingerprint. A preference change alone leaves both execution reuse and named test data intact. A changed source head or authority requires a new plan even when its bytes are identical. When pinning an inspected CLI plan, pass both --fingerprint and --storage-fingerprint; MCP apply takes fingerprint and storage_fingerprint. An ordinary reflow apply prepares and validates its current plan automatically.

MCP creates and move previews take policy_revision from get_reflow_context. This prevents a cached instruction from silently changing the destination. reflow flows create <name> --file - also accepts source on stdin.

Repository creates retain the original privately, reserve the test identity, write the file, and confirm the destination. A pending reservation cannot execute or be adopted as another test. Recovery checks the original test ID and source against the server, including after a restart loses the local confirmation. Recover the file with reflow flows recover-create --operation-id <id> --operation-session <session> --collection <id>. Reflow never resubmits an uncertain registry mutation automatically. Recovery preserves existing files and stops if their contents differ. Reflow uses a private lock outside the checkout to prevent two authoring operations from writing at once. After a crash, check that the recorded process has exited before removing its stale lock.

After a manual file rename removes the old path, map-path requires --base-hash from the old source read. It records the former bytes separately from the new destination. Test details link related historical records, including their versions, runs and approvals.