Install the CLI

One command. The archive carries its own Node runtime, so there is nothing to install first.

The CLI is distributed as a standalone archive with its own Node runtime bundled in. You do not need Node, npm, or a toolchain on the machine that runs it.

curl -fsSL https://fixtureframe.qa.tera.cloud/install.sh | sh

The installer is served by the control plane it belongs to, and the copy you download is bound to that host. Installing from a different environment's URL gives you a CLI pointed at that environment — which is the intended behaviour, not a mistake to work around.

Two names, one command

The installer puts both on your PATH, pointing at the same binary:

fixtureframe --help
ff --help

The rest of these docs use ff. These are commands you type many times a day, and the short form is the one that survives that; anywhere you see ff, spelling it fixtureframe does exactly the same thing.

A shell alias always beats a command on the PATH. If you already alias ff to something of your own — ffmpeg and fuzzy-finders are the usual ones — yours wins and ff here will not reach this CLI. Use fixtureframe in that case, or alias it to something free.

Create a workspace

For the full sequence of commands and agent prompts, follow From sign-in to a published flow.

First sign in to your Fixtureframe Studio deployment. Open Settings → API keys, name a new key, choose Create key, and copy it while it is shown. An organisation Owner must create a Studio workspace if one does not already exist.

A workspace is a directory holding a .fixtureframe folder: the flows, the environment configuration, and the credentials the runner needs.

ff init

init prompts for a control-plane key when a terminal is attached, and takes --api-key when one is not — which is the form CI wants. Run interactive setup yourself so the key stays out of the agent conversation. Use --api-url <control-plane-url> when you need to override the installed default.

Select your organisation and existing workspace, then select an environment or choose Create a new one. Supply the environment name and target app URL. A source-code directory is optional. The API key connects to Fixtureframe; the environment URL identifies the app you will capture.

Save the app session

ff session init --environment staging
ff session status

Replace staging with your environment name. Complete sign-in in the browser, keep it open, and press Enter in the terminal. Survey restores this session automatically; use --session with ff script and ff run. A valid saved session removes the need for adapter username/password variables. See Sessions for renewal and replay.

Optional adapter credentials

ff init also writes .env.example, and that file is the answer to "what am I supposed to put in .env?" It is generated from the adapters this workspace has enabled — each one declares its own credentials, with a description and whether it is required — so it lists the variables that actually apply here rather than every variable the CLI has ever supported:

# ── form-login · Form login ──
# Username or email to sign in with.
ADAPTER_LOGIN_USERNAME=
# Password for that account.
ADAPTER_LOGIN_PASSWORD=
# Accessible name of a button to click before the form appears, e.g. a region picker.
# ADAPTER_LOGIN_PRE_STEP=

Required variables sit present and empty; optional ones are commented out, because an empty value is not the same as an absent one — an uncommented ADAPTER_LOGIN_SUBMIT_SELECTOR= overrides the default with nothing and breaks a form that worked.

If you choose adapter authentication, merge the needed entries into the existing .env; preserve the API key and URL that initialization saved. Saved-session users do not need to fill in login variables. .env is gitignored; .env.example contains no values and can be committed.

ff adapter init <id> regenerates it when a new adapter declares credentials, and ff doctor --example writes one for a workspace that predates the file or whose adapters have changed.

Check the machine

ff doctor

doctor reports on the workspace directory, the control-plane key, and the credentials each enabled auth adapter declares, unless a valid saved session supplies authentication. Those credential names belong to the adapter rather than to Fixtureframe: one that signs in with a username and password asks for different variables than one using an API token.

It exits non-zero when something required is missing, so it can gate a setup script rather than letting the first run fail halfway through. Add --example to write .env.example at the same time, which is how an existing workspace picks up the file after adopting a new adapter.

Where things live

Path	What it holds
`.fixtureframe/`	Workspace configuration and flow definitions
`.fixtureframe/auth/`	Captured browser storage state — session tokens. Never committed
`.fixtureframe/discovery/`	Adapter discovery output and fixture baselines
`.env`	Credentials this workspace reads. Gitignored, and read from here — the workspace — whatever directory you run from
`.env.example`	The same names with their descriptions and no values. Generated; commit it

The auth and discovery directories are git-ignored deliberately. Adapter commands keep credentials, session state and raw fixtures on the local runner; the control plane receives only explicitly approved governed artefacts.