Command line

npx ronsel start [--context ] [--no-install]

ronsel [--context <folder>]
ronsel --file <flow.md> --env <environment>
ronsel --view <view> --env <environment> [--folder <folder>]
ronsel --import-env <env.yaml> [--view <view> --env <environment>] [--dry-run]
ronsel --capabilities
ronsel --agent --agent-id <name> [--broker <url> --username <user> --password <secret>]
ronsel --remote <agent> --file <flow.md> --env <environment>

start is the first command: it makes the folder a project of its own and starts the UI. Told nothing to run, ronsel starts the web UI on http://localhost:3001 — that second form is the whole of it. Every other form runs something and comes back with an exit code.

The tool does not have to be installed globally: npx ronsel start writes a package.json that depends on it, so every command below can be typed as npm run ronsel -- <flags> in that folder. npm install -g ronsel puts ronsel itself on the PATH, and both spellings do the same thing.

Flag	What it does
--no-install	With start, write the files and skip the npm install.
--context	The context folder. Without it, the directory the command was run from is used, after asking. Every other path is resolved against it.
--file	Run one flow. The path is relative to the context: flows/checkout/refund.md.
--view	Run every flow a saved view matches, as one test run. The name or the slug of a view of views.yaml.
--folder	With --view, scope the view to a folder of the flows tree. Default: every flow.
--env	The environment to run against. Required with --file and --view.
--import-env	Write a YAML export of environment variables into the context's env files before anything runs.
--dry-run	With --import-env, print what it would write, write nothing and run nothing.
--capabilities	List every application of the context with its methods.
--agent, --agent-id, --broker, --username, --password	Run this machine as a remote agent. See Remote agents.
--remote <agent>	Run --file or --view on that agent instead of here.
--debug	Print the environment variables and Node.js paths, for when nothing else explains a failure.
--version, -v	Print the installed version.
--help	Show the help.

Writing flows with AI is a web UI feature: the provider and keys are configured there, and the CLI has no flag for it.

Starting a project

mkdir e2e && cd e2e
npx ronsel start

start does four things, in order, and then starts the UI:

1. Furnishes the folder as a context — flows/, applications/, the tsconfig.json that gives your editor the types, and, the first time, the example applications and flows.

2. Writes a package.json that depends on the exact version it is, and carries the command as a script:

    {
      "private": true,
      "scripts": { "ronsel": "ronsel --context ." },
      "devDependencies": { "ronsel": "^1.11.0" }
    }
   

3. Writes a .gitignore with node_modules/ and test-runs/, if those lines are not there already.

4. Runs npm install.

From then on the whole thing is npm run ronsel, in that folder, for you and for whoever clones the repository:

npm install
npm run ronsel

That is the point of the command. The version is pinned in the repository rather than in whatever happens to be installed on the machine, so a colleague and a CI job run the same tool as you, with nothing installed globally.

Everything start writes is additive. A package.json that is already there keeps its formatting and every key it had; a ronsel script somebody else wrote is reported and left alone; the examples are seeded once and never restored, so a folder you have since pruned is not refilled. Running it again in a folder that is already a project adds whatever is missing and nothing else.

--context <path> starts the project somewhere else, and unlike every other command it creates the folder if it is not there:

npx ronsel start --context ~/projects/shop/e2e

--no-install writes the files and leaves the npm install to somebody else — a Dockerfile, a lockfile-aware CI step, or you.

The context, and being asked about it

cd ~/projects/shop/e2e
ronsel

Use /home/you/projects/shop/e2e as the context? [Y/n]

Without --context the directory you are standing in is the candidate, and the tool asks before settling on it — a folder it may be about to write into is not something to assume. An empty directory is furnished with the example applications and flows on that first yes; a directory with anything already in it is served exactly as it is, and nothing of the tool's is written into it.

The question is only ever asked of a terminal. A run nobody is watching — a pipeline, a piped command — answers yes and prints the directory it settled on, so a job never hangs on a prompt:

Context directory: /home/ci/work/e2e

In a pipeline, name the folder anyway: --context e2e says what the job means, wherever it happens to be run from.

Running one flow

ronsel --context ~/projects/shop/e2e --file flows/checkout/refund.md --env uat

The steps are printed as they run, with their request, response and assertions, and the run is recorded under test-runs/ exactly as one from the UI. The command exits with 0 when the flow passed and 1 otherwise.

Running a view

ronsel --context ~/projects/shop/e2e --view smoke --env uat

--view runs every flow a saved view matches, one after the other, as a single test run. The CLI button of a folder view writes the exact command for what is on screen, --folder included when the view is scoped to a folder.

The view is evaluated when the command runs, not when it was written down: a flow added later that its filters keep is picked up without touching the pipeline. Every flow runs even when one fails, the summary lists the failed ones, and the exit code is 1 if any did. Why a view rather than a list of files is the right thing to hand a pipeline is explained in Organizing flows.

Bringing the environment variables with you

Env files hold secrets, so they are not in the repository a pipeline clones. --import-env takes the YAML document the Environment variables screen exports and writes its values into the context's env files before any flow runs:

ronsel --context . --import-env env.yaml --view smoke --env uat

The path is resolved against the working directory first and the context second. Missing files are created, existing ones keep everything the document does not name, and an application the document names that the context does not have is reported and skipped. Every file touched and every entry left out is printed:

Environment variables — imported /home/ci/env.yaml:
  updated applications/payments/env/uat.env — 1 added, 1 overwritten
  created applications/checkout/env/uat.env — 1 added
  skipped billing — no such application in this context
  1 created, 1 updated; 2 added, 1 overwritten, 0 already the same, 1 skipped

A document that cannot be read stops the command before anything runs. The document carries real values: keep it out of git and out of the job's log.

In a pipeline

A job needs Node.js 24, the package, the context and the environment document. A context made with ronsel start carries its own package.json, so the job installs the version the repository pins rather than whatever is latest. With GitHub Actions, the context being the e2e folder of the repository and the export stored as the secret FLOWS_ENV_UAT:

jobs:
  smoke:
    runs-on: ubuntu-latest
    defaults:
      run:
        working-directory: e2e
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 24
      - run: npm ci
      - run: printf '%s' "$FLOWS_ENV" > env.yaml
        env:
          FLOWS_ENV: ${{ secrets.FLOWS_ENV_UAT }}
      - run: npm run ronsel -- --import-env env.yaml --view smoke --env uat
      - uses: actions/upload-artifact@v4
        if: always()
        with:
          name: flows-report
          path: e2e/test-runs/**/report.html

The -- matters: it is what hands the flags to the tool rather than to npm. Without a package.json in the context, npm install -g ronsel and ronsel --context e2e --import-env env.yaml --view smoke --env uat are the same job with the version left to chance.

The job fails when a flow fails, and the HTML report of the run is kept as an artifact either way. Flows that drive a browser need npx playwright install --with-deps chromium before the run. Any other CI system is the same four steps: install, write the document, run the view, keep the report.

Remote

ronsel --remote agent-ourense --view smoke --env uat

runs the view on a machine that can reach the systems under test, and prints and records the run here as if it had run locally. See Remote agents.