From sign-in to a published flow

After installing the CLI, follow this guide from your local Fixtureframe workspace: the folder that will hold .fixtureframe/. The application's source code can live elsewhere, and is optional.

Terminal blocks run in PowerShell, Bash or your usual terminal. Agent prompt blocks go into Claude Code or another coding agent with the Fixtureframe skills installed. Slash commands such as /ff-context are agent instructions; commands such as ff survey are CLI operations. There is no terminal command named ff context.

The examples use an environment called staging, a target app at https://staging.example.com, and a flow called operator-tour. Substitute your own names and URL. Single-line terminal examples avoid differences between PowerShell and Bash line continuation.

flowchart TD
  studio["Studio sign-in and API key"] --> init["ff init: choose workspace and create environment"]
  init --> session["ff session init: sign in to the target app"]
  session --> skills["ff agent install"]
  skills --> survey["ff survey: initial map"]
  survey --> context["/ff-context: app knowledge and gaps"]
  context --> more{"Missing detail evidence?"}
  more -->|Yes| targeted["ff survey with verified seeds"]
  targeted --> plan["/ff-script: coverage, brief and script"]
  more -->|No| plan
  plan --> checks["ff brief and ff lint"]
  checks --> capture["ff script --session --local-only"]
  capture --> profile["ff profile create: if the flow needs values"]
  profile --> replay["ff validate, then ff run --session --local-only"]
  replay --> review["Review actual frames and declared outputs"]
  review --> publish["Publish the selected profile and flow"]
  publish --> rerun["ff run --flow: refresh later"]

1. Sign in to Studio and create a CLI API key

Open Fixtureframe Studio, or your organisation's Studio deployment. Make sure the organisation has a workspace. If it does not, an Owner creates one in Studio before you continue; an API key cannot create a workspace through ff init.

Open Settings → API keys, enter a purpose in Name for the new key, and choose Create key. Copy the key while it is shown. You will enter it in your terminal during initialization.

There are two separate sign-ins: this API key lets the CLI use Fixtureframe's control plane; the saved browser session in step 3 signs into the application being documented. They may be the same product when you document Studio itself, but they serve different purposes.

2. Initialize the workspace and select an environment

Run this yourself in an interactive terminal, from the folder where your flows should live.

Terminal

ff init --api-url https://app.fixtureframe.ai

Use the control-plane address that issued your key. A standalone installer may already supply that address, in which case ff init is sufficient. Enter the API key when prompted; do not paste it into the coding-agent conversation.

The interactive setup lets you:

1. Select the organisation and existing workspace available to your key.
2. Select an environment, or choose Create a new one.
3. For a new environment, enter its name and the target application's URL.
4. Optionally name the directory containing the product's source code; leave it blank for URL-only work.

A new environment uses this CLI as a self-hosted runner and initially allows the target URL's host. Review additional required hosts in Studio's environment settings. A flag naming an environment in non-interactive setup is not a substitute for creating its server record.

Setup writes .fixtureframe/config.json and local .env configuration. The final doctor report may show missing form-login credentials before you have a saved session; complete step 3 instead of supplying a password when you intend to use interactive sign-in.

3. Save a session for the target app

Terminal — run this yourself

ff session init --environment staging

A browser opens. Complete your app's normal sign-in, including SSO or MFA, and return to the app. Keep the browser open and press Enter in the terminal to save its state. This creates authentication state without creating a walkthrough.

ff session status
ff doctor

The session lives in .fixtureframe/auth/session.json and stays out of version control. A valid saved session means the doctor does not require otherwise-missing adapter login variables. Cookie expiry information is only a local check; the next browser operation establishes whether the app still accepts the session.

If the app rejects it, refresh the session interactively:

ff session init --environment staging --force

--force replaces an existing session that still looks valid. One workspace holds one saved session; use separate authoring folders when you need to keep different accounts' sessions separately. See Sessions for authentication and unattended-run options.

4. Install the agent skills

Terminal

ff agent install --host claude-code

Alternatively, ff agent install detects supported hosts and also updates AGENTS.md. Open a fresh agent session in this same folder. Repeat the installation after updating the CLI so the slash skills match the installed version.

Agent prompt

/ff-cli Check this workspace with ff doctor and ff session status.
Use the saved session for capture and replay. The target environment is staging.

5. Survey the app

Terminal, or ask the agent to run it

ff survey --environment staging --directory . --max-pages 60 --max-depth 3 --view-depth 2 --max-controls 25

The survey restores the saved session automatically. It records routes and reachable views, headings, controls and navigation paths, uploads the map, and writes a local cache for authoring. It follows navigation without completing the business tasks it finds. Review its report rather than treating a large screen count as complete feature coverage.

These are the survey switches you can use to tune discovery. The ceilings shown above are the current defaults; raising all of them is not a prerequisite for a good walkthrough.

An optional adapter name can follow survey when the environment needs one. Use the saved-session route above for ordinary interactive sign-in. Check ff help survey for your installed version.

6. Create reusable app context

Agent prompt

/ff-context Use the staging environment and its cached survey to create
.fixtureframe/APP_CONTEXT.md. The product source is C:/work/acme-app.
The audience is a new operator. Describe the user jobs, feature relationships,
representative detail views, and any missing evidence. Separate observed behavior
from source-supported assumptions. Propose demo-data needs before capture.

Omit the source sentence if you only have a URL. Review the generated context and correct important facts or priorities; you do not need to write a complete feature inventory yourself. The app-context guide includes a reusable template and more example prompts.

7. Resolve discovery gaps with a targeted survey

Run a second survey only when the context identifies missing evidence or the map is stale. For a detail route behind a row click, the agent should obtain the URL from an existing record before using it as a seed. Replace the placeholders below with those verified paths.

Terminal

ff survey --environment staging --seed "<first-verified-detail-path>" --seed "<second-verified-detail-path>" --max-pages 60 --max-depth 3 --view-depth 3 --max-controls 25

Append --never-click "<control-to-exclude>" for each app-specific control that should be excluded, and --headed if you want to watch. A seed is a starting URL, not generated sample data. The record must already exist. Do not guess an ID or turn a title into a slug unless the app supports that route.

Agent prompt

/ff-context Update APP_CONTEXT.md with the targeted survey evidence. Verify that
each seed reached the intended detail screen. Keep any remaining gaps explicit.

8. Choose a flow and agree what it should show

If you already know the walkthrough, go straight to /ff-script. If you need suggestions:

Agent prompt — optional

/ff-suggest Use APP_CONTEXT.md and the staging survey. Save candidate walkthroughs
in .fixtureframe/CATALOG.md. Prioritize the jobs a new operator needs first and
state the question, representative proof and scope of each candidate.

Then choose a candidate or supply your own goal.

Agent prompt

/ff-script Build operator-tour for a new operator using APP_CONTEXT.md and the
staging survey. Explain the main sections and the question each answers.
Propose chapters with representative proof, evidence gaps and explicit deferrals;
aim for about four minutes rather than one screenshot per menu item.
Identify variable inputs and displayed demo data before capture. Keep product
labels unchanged. Use the saved session, and report unsupported data substitution
instead of dropping a required chapter. Show the coverage and beats for agreement,
then write operator-tour.brief.yaml and operator-tour.mjs in .fixtureframe/flows.

For a task walkthrough, replace the orientation goal with the job, starting state and observable result. Broad stories may also produce <slug>.plan.md. A brief records confirmed beats; a context file or catalogue entry is not by itself confirmation of a new sequence.

9. Check the draft and capture locally

Terminal

ff brief .fixtureframe/flows/operator-tour.brief.yaml
ff lint .fixtureframe/flows/operator-tour.mjs --environment staging

Resolve errors and prepare any required displayed demo data before capturing. If the app or its scenario tooling cannot supply that data, resolve the gap before proceeding. Then authorize the proposed capture within the agreed environment and scope.

ff script .fixtureframe/flows/operator-tour.mjs --environment staging --session --local-only --output .fixtureframe/flows/operator-tour.flow.json --frames .fixtureframe/flows/assets/operator-tour --outputs screenshots,html_demo

This script signs in through the saved session, so it should not contain another login procedure. Add --parameter name=value for each input the script actually needs; for example, --parameter customer_name="Alex Morgan" supplies value("customer_name"). The recorder produces the flow JSON. --local-only keeps this capture from publishing it immediately.

10. Create a data profile when the flow needs one

Choose the parameter names and suitable values during authoring, before capture. The CLI's profile create --from command operates on the resulting flow file, so this command runs after the initial capture; it is not a pre-capture screen-data scanner.

Terminal

ff profile create operator-demo --from .fixtureframe/flows/operator-tour.flow.json --local-only
ff profile list

Review .fixtureframe/profiles/data/operator-demo.json if a profile was written. The command uses declared parameters, or proposes candidates from the flow, and reuses known parameter names. A navigation-only flow may have no audience values and produce no profile; omit profile flags in that case.

Creating a profile does not rewrite literal actions into parameter references. The agent must ensure the script and resulting flow actually use the selected names. It also does not replace a company logo, user name, email, phone number or record list already rendered on screen. Preparing that displayed data requires suitable app records or a supported scenario mechanism before capture. Keep authentication cookies and tokens separate from demo-data profiles.

11. Validate a fresh replay and review the artifacts

Terminal

ff validate .fixtureframe/flows/operator-tour.flow.json
ff run .fixtureframe/flows/operator-tour.flow.json --local-only --session --base-url https://staging.example.com --outputs html --dom --output .fixtureframe/runs/operator-tour-review

Append --data-profile operator-demo when step 10 produced a profile that covers the flow's inputs. Screenshots are captured by the run; --outputs html --dom also requests the declared HTML demo and its page markup. Choose a new output directory for a new review attempt so old artifacts remain distinct.

A fresh replay uses a new browser context initialized with the saved session. It does not require username/password variables or a signed-out browser. Inspect the replay's manifest and artifacts, not only the script's shot() images: script-specific waits and scrolling do not automatically become replay steps.

Agent prompt

/ff-script Review the operator-tour replay against its confirmed coverage plan.
For each chapter, cite the actual artifact and mark its question demonstrated,
partial or missing. Check loaded content, framing, narration, demo data and the
HTML output. Report execution success separately from story coverage. Do not
publish while required proof or data preparation remains unresolved.

12. Publish the selected profile and flow

Publishing a profile and publishing a flow are currently separate operations. If the local profile is needed on this runner only, create its server record with values kept on the runner:

Terminal — choose one profile storage mode, if needed

ff profile create operator-demo --from .fixtureframe/flows/operator-tour.flow.json

For demo values that should be stored and editable in Studio, use --inline instead:

ff profile create operator-demo --from .fixtureframe/flows/operator-tour.flow.json --inline

Run only the selected form. profile create reads the flow again and reuses matching local values; it is not a command to upload an arbitrary edited JSON file. Check the printed values and publication result. It creates a server record, not an update to an existing one: manage an existing profile in Studio rather than repeatedly creating the same name. --local-only creates no server record.

Then save the reviewed flow:

ff publish .fixtureframe/flows/operator-tour.flow.json --environment staging

Open the printed Studio URL and verify the workspace and flow. publish uploads referenced local assets, but does not automatically upload or associate a data profile. The current CLI resolves ff run --data-profile operator-demo from the local profile file, including for governed runs; uploading an inline profile alone does not make this runner resolve it from the server.

For subsequent versions, target the existing flow ID printed by publication:

ff publish .fixtureframe/flows/operator-tour.flow.json --flow "<published-flow-id>"

13. Rerun when the app changes

Terminal

ff session status
ff run --flow "<published-flow-id>" --session
ff status "<run-id>"

Add --data-profile operator-demo when required. A governed run uses the environment recorded on the server. A different runner needs access to the configured authentication and any runner-file data; publishing a flow does not transfer your browser session. Refresh expired sign-in interactively.

If the app changed enough to break the walk:

Agent prompt

/ff-diagnose Inspect run <run-id>. Explain the failed step and its evidence,
repair the source script where appropriate, and propose checks before recapture.

Other front doors

These are alternatives for the task at hand, not extra steps required for every flow.

See Skills and commands for every skill and How to ask for more ways to express goals and scope.