Skip to content

Navigation Flows

Save repeatable Simulator navigation paths as compact flow files, replay them with one command, and review the latest run on an interactive flow page.

Navigation flows ship with RocketSim 17.0.0. They save repeatable navigation paths for an app in the Simulator so agents (and you) do not rediscover the same taps on every task or relaunch. Each flow is a small .rsflow text file on your Mac, scoped to the app’s bundle id.

Flows run with the same reliability as rocketsim do, including checkpoints that catch wrong turns early. After a successful run, RocketSim can open a flow review page with real screenshots, arrows from tapped elements, and tools for visual feedback.

Agent tasks often restart the app or bounce between branches. Without flows, every session repeats the same login, settings, or onboarding taps. With flows:

  • You save a path once from the steps the agent already performed.
  • You replay it with rocketsim flow <name> instead of many separate interact commands.
  • Leading flow <prerequisite> steps run only when needed, so shared setup stays DRY.

List the flows RocketSim knows for the app in the foreground (or pass --app <bundle-id> to scope another app):

Terminal window
rocketsim flow list

Each line is short: name, optional prerequisites, parameters, health markers such as (stale), and a one-line about summary. Use --match <text> to filter the list.

Run a flow by name:

Terminal window
rocketsim flow login
rocketsim flow open-settings --app com.example.app

rocketsim flow <name> accepts the same --udid and --app options as other Simulator commands, plus --from <step> to resume after an environmental interruption and --force when a flow is marked stale but you want to retry anyway.

After signing in once (manually or with rocketsim do), save the path:

Terminal window
rocketsim flow save --name login --about "Sign in with the test account" --last 3

Without --last, save uses the last five successful session steps. Use --from-step and --to-step to save a specific portion of the log instead.

RocketSim writes minimal selectors, inserts expect checkpoints between screen changes, and never stores secrets—only placeholders. A typical login flow looks like this:

name: login
about: Sign in with the test account
param: user = $TEST_USER
param: password secret = $TEST_PASSWORD
tap --identifier login.email
type '{user}'
tap --identifier login.password
type '{password}'
tap --label 'Sign In'
expect --label 'Home'

Run it with environment variables or explicit parameters:

Terminal window
export TEST_USER=alice
export TEST_PASSWORD=...
rocketsim flow login

For secrets, prefer shell expansion so values do not land in agent transcripts:

Terminal window
rocketsim flow login --param user=alice --param password=$TEST_PASSWORD

Flows can call other flows. Leading flow <name> lines before the first real step are prerequisites. At run time RocketSim skips a prerequisite when that flow’s final expect already holds (for example you are already on the home screen after sign-in). Any flow line after the first non-flow step always runs.

name: open-settings
about: Open the settings screen from home
flow login
tap --label 'Settings'
expect --identifier settings.title

Run rocketsim flow open-settings; the flow login block runs only when you are not already signed in and on the expected screen.

Declare parameters in the flow header:

DeclarationMeaning
param: userRequired
param: user = defaultLiteral default
param: user = $ENV_VARDefault from the environment
param: password secret = $TEST_PASSWORDSecret; value never persisted

Use {name} in step text. Values resolve in order: --param name=value (or inline flow login user=alice) → environment variable → literal default.

Passwords and other secrets are never written into .rsflow files, session logs, or failure output. When save detects secure fields, steps become type '{password}' with a secret parameter. Typed passwords in failure replies are redacted the same way.

When saving, bind literals to env names with --secret-env name=ENVVAR and replace typed secret text with --param name=literal.

A failed run stops at the first bad step and returns one compact reply (exit code 1) with the current screen in the same payload, so the agent can continue manually without restarting the app.

  • Drift (UI changed): the flow is marked stale. Navigate the corrected path, then run rocketsim flow fix <name> to merge your manual steps into the file. RocketSim may heal an unambiguous single-element rename automatically and persist the fix only if the rest of the run still passes.
  • Environmental blockers (alerts, wrong app in foreground, missing parameters): fix the blocker, then resume with rocketsim flow <name> --from <step>. Step numbers appear in the failure output and stay stable when prerequisites are skipped.

rocketsim flow verify replays one or all flows proactively to catch drift before a task starts.

Flows live in RocketSim’s sandbox on this Mac, under Application Support:

RocketSim/Flows/<bundle-id>/flows/<name>.rsflow

They are per app bundle id, not per Xcode project or git branch. The same app on the same Mac shares flows across worktrees. rocketsim flow list is the supported way to see what is available; agents should not read .rsflow bodies for routine navigation.

Sharing flows through a project repository is planned; today they stay local.

Every complete flow run records checkpoint screenshots and accessibility snapshots. Open the review UI from Terminal:

Terminal window
rocketsim flow open
rocketsim flow open login

flow open returns a token-protected localhost URL on the same browser preview server as rocketsim preview. The link stays valid for the RocketSim preview session (it outlives a single agent task but not an app restart). A newly saved flow shows its steps until the first successful run adds screens.

Stock Analyzer demo flow in Annotated mode with accessibility overlays and step arrows

The overview board shows each distinct screen once, with connectors from the tapped element to the next screen. Toggle Annotated (default) or Clean routes, show or hide the device bezel, and turn accessibility overlays on or off. Hover and select elements to inspect labels and identifiers; the Screens sidebar lists the element tree with search and keyboard navigation.

The same Stock Analyzer demo flow in Clean mode without overlays

Pan and zoom the canvas with the mouse, trackpad, or keyboard. Comment mode (C) lets you attach notes to elements; pins appear on the screenshot. The Comments sidebar groups notes by screen, includes a prompt preview, and Copy prompt builds an agent-ready message from your comments. Comments are stored in the browser’s localStorage for that flow run—they are not written into the flow store.

Comments sidebar with prompt preview on the Stock Analyzer demo flow

Overview of a recorded Stock Analyzer demo tour on the flow page

On the flow canvas (when focus is not in a text field):

KeyAction
CToggle comment mode
+ / =Zoom in
- / _Zoom out
0Actual size (100%)
F or 1Fit the board
Arrow keysPan (hold Shift for a larger step)
EscClear selection

Double-click the canvas to fit the board. In comment mode, Cmd/Ctrl+Enter submits a new comment.

Successful flow save and flow run replies may include flow_url the first time and again about every ten minutes—surface it once as Flow review: <url> for humans following along.

Flows need a booted Simulator session with your app reachable the same way as other rocketsim commands. flow open starts or reuses a browser preview tied to that Simulator; it cannot serve a flow page without a booted device.

Flow commands count toward the same agent-session allowance as other interaction and capture commands. When the allowance is exhausted, RocketSim returns quota_exceeded and agents should stop further flow runs for that task; read-only inspection still works. Open RocketSim → Settings → CLI & Agent to view the allowance or upgrade to Pro.

Keep individual flows to about 15 steps; split longer paths with a leading flow prerequisite. Prefer descriptive names and flow list over hand-editing files—use flow show or flow write only when you need to author a flow manually.