Environment variables
Every variable the CLI reads, what wins when two of them disagree, and which names belong to the control plane instead.
The CLI reads a small, fixed set of variables, plus whatever the auth adapter you are using
declares. This page is the fixed set; ff adapter inspect <id> is the other half, because those
names belong to the adapter rather than to Fixtureframe.
What wins
Three sources, and they are consulted in this order:
- A flag on the command —
--api-url,--directory,--environment - The shell environment — an
export, or whatever CI injects .envin the workspace
.env never overwrites a value the shell already set, which is how CI supplies a secret without
writing a file. And the file is read from the workspace — the directory holding
.fixtureframe/ — not from wherever you happened to run the command, so one file serves every
command however it is invoked.
FIXTUREFRAME_PROJECT_DIR cannot live in .env usefully. The workspace has to be known before a .env can be
read from it, so a value set inside that file is applied only to the commands that run afterwards — which is a good
way to have doctor and record disagree about which workspace they are in. Set it in your shell, or pass
--directory.
The workspace
| Variable | What it does |
|---|---|
FIXTUREFRAME_PROJECT_DIR | The workspace: the directory holding .fixtureframe/. Beaten by --directory; defaults to the current directory. Not the product's source — ff suggest --source takes that. |
FIXTUREFRAME_API_URL | Control plane to publish to and read flows from. Beaten by --api-url. The installer writes it into the launcher, so it is usually already set. |
FIXTUREFRAME_API_KEY | Key for that control plane. ff init writes it to .env when you paste it at the prompt. |
FIXTUREFRAME_ENVIRONMENT_ID | Which environment commands act against. Beaten by --environment-id, then --environment, then the workspace's config.json, then the only environment there is. |
FIXTUREFRAME_WORKSPACE_ID | Which workspace a deck, media or suggest belongs to. Beaten by --workspace-id. |
Capture
| Variable | What it does |
|---|---|
FIXTUREFRAME_SCRIPT_TIMEOUT_MS | How long a scripted walk may take before it is abandoned. Raise it for a genuinely long flow rather than to paper over a locator that never resolves. |
Rendering is not on this list, and needs nothing from you: video, narration and music are composed by the control plane.
Signing in
These are not on this page, deliberately. Each adapter declares its own credentials — name, description, and whether it can start without them — so the authoritative list is the one your workspace can print:
ff doctor # every enabled adapter, and whether each variable is set
ff adapter inspect form-login # one adapter, in detail
ff doctor --example # writes .env.example: the names, with their descriptionsThe built-in three are documented with their own pages: form-login for a username and password, and the token and API-key adapters for products that issue a credential instead. A workspace adapter of your own declares its variables the same way and shows up in all three commands above.
And if your product signs in through an identity provider, no variable will get you in — that is what a saved session is for.