Environment variables

The CLI usually has what it needs: the active profile knows the API to talk to, the vault holds the credentials, and the config holds your preferences. The FLUI_* variables cover the cases where that is not enough, such as a script, a pipeline or a one-off run against a different installation. They also hold values you would rather not type where your shell will remember them.

All of them are optional. The CLI works without any. They can come from your shell, or from a .env file: the CLI reads ~/.flui/.env and then .env in the current directory. A .env left in a project folder can therefore supply a FLUI_API_KEY without you noticing.

For most values the cascade is:

explicit CLI flag
  >  env var
  >  ./flui.config.json in this directory
  >  active profile value
  >  schema default

flui config show prints each preference next to the layer it came from, which is the quickest way to find out where a value comes from.

Two variables do not follow that order. The next section covers both.

Profile and API targeting

Variable	Effect
`FLUI_PROFILE`	Which profile this one command talks to. Checked in order: `FLUI_PROFILE`, then the `~/.flui/context` file, then `default`.
`FLUI_API_KEY`	The API key to send. Checked before the profile, so it wins over the stored one.
`FLUI_API_URL`	The API to talk to when the profile has none. See the caution below.

FLUI_API_URL is only a fallback. If the active profile has an API URL saved, that URL is used and the variable is ignored. With neither, the CLI derives one from the cluster the profile holds. To point an existing profile somewhere else, change the profile (flui config set api-url …) or use a different one with FLUI_PROFILE.

FLUI_API_KEY works the other way: it is read first, as plain text. A command using it does not need the vault open, which is why pipelines use it.

Preferences

These four mirror the preferences in the layered config, so you can override a stored value without running flui config set. See Profiles and config for the full resolution model.

Variable	Preference	Notes
`FLUI_EMAIL`	`email`	Contact email for Let’s Encrypt and operational notifications. Required; there is no default.
`FLUI_CERTIFICATE_MODE`	`certificateMode`	One of `production` (the default), `staging`, `preflight`. See TLS and certificates.
`FLUI_API_PATH`	`apiPath`	Path to the local `flui-core` repo. Only relevant to contributors using `env export-config` / `dev creds`.
`FLUI_DASHBOARD_PATH`	`dashboardPath`	Path to the local `flui-dashboard` repo. Same scope as `apiPath`.

Preferences are not secrets. They are stored in plain text, and reading or writing one never asks for the vault.

The vault

The vault seals every stored credential behind a passphrase you type once per session. Three variables affect it, and none of them is a passphrase. The passphrase is only ever prompted for, or piped in with --stdin.

Variable	Effect
`FLUI_PROFILE_KEY`	Hands the CLI a profile key directly: 32 bytes, base64. No vault is consulted.
`FLUI_VAULT_IDLE_MINUTES`	How long an unlocked vault stays open with nothing happening. Default `30`.
`FLUI_VAULT_MAX_MINUTES`	How long it stays open at all, however busy you were. Default `480`.

FLUI_PROFILE_KEY is for a caller with no terminal and no home directory that outlives the run, such as a provisioning worker. Generate one with openssl rand -base64 32. The key then lives only in whatever started the CLI. If that caller loses it, nothing the run sealed can be opened again. A value that is present but malformed is an error; the CLI never falls back to the vault.

The two timers are read in whole minutes. Anything that is not a positive whole number falls back to the default, so a typo cannot make a session permanent or unusable. flui vault unlock --idle-minutes and --max-minutes set the same two values for one unlock.

Installing on a machine you own

Variable	Effect
`FLUI_SSH_PASSWORD`	The host password for `flui env create --host`, so an unattended run can authorize its key.

When you install onto a machine you already have, Flui needs to get an SSH key onto it. If it finds a key that already works, it uses that key and ignores this variable. Otherwise Flui authorizes a key, which takes the host password once.

In a terminal you are asked for it. In a pipeline nobody is there to answer, so flui env create also accepts --ssh-password. Prefer the variable: a flag lands in your shell history and in the process list, where anyone on the machine can read it.

The password is held in memory, used only to append the public key to the host, and never written down. Every step after that uses the key.

FLUI_SSH_PASSWORD='…' flui env create \
  --host 203.0.113.10 --non-interactive

See installing on a machine you already own for the rest of that flow.

Rebuilding from a platform backup

Variable	Effect
`FLUI_RESTORE_ENCRYPTION_KEY`	The key the new installation boots with instead of a fresh one, so the restored data can be read.

flui backup platform restore writes it into install-keys.env; export it before flui env create. It has to be the 64-character hex key from that file. Any other value stops the install instead of falling back to a new key. See Rebuild the control plane.

S3 credentials

Read by flui app backup create and flui app backup delete when --access-key / --secret-key are not passed inline.

Variable	Effect
`FLUI_S3_ACCESS_KEY`	Default S3 access key for app-level backups.
`FLUI_S3_SECRET_KEY`	Default S3 secret key for app-level backups.

As with the host password, passing a secret as a flag leaves it in your history.

Identity provider session token

Variable	Effect
`FLUI_SESSION_TOKEN`	Bearer token used by `flui auth generate-api-key` to mint a key when `--token` is not passed.

Use it in automation that already has a session token from elsewhere, instead of running flui auth login with a browser.

Running with nobody watching

A command that stops to ask a question works at your terminal but breaks a pipeline. With no answer coming, it hangs instead of failing, and keeps whatever it had already created.

Variable	Effect
`FLUI_NON_INTERACTIVE`	Set to exactly `1`. Every would-be prompt becomes an immediate error naming the flag that would have answered it.
`FLUI_EVENTS_FD`	A file descriptor number (above 2) to receive progress from `flui env create` as one JSON object per line.

FLUI_NON_INTERACTIVE=1 is the variable form of the --non-interactive flag that flui env create and flui env scrub carry. It also reaches the prompts in flui app env set, flui vault init and flui vault unlock.

FLUI_EVENTS_FD is for a program wrapping the CLI. Milestones go to that descriptor, and the spinner, colours and streamed install log on your terminal are unchanged.

Working on Flui itself

Variable	Effect
`FLUI_RELEASE_FILE`	Path to a JSON file overriding which build gets installed. Without it, the CLI looks for `flui.release.json` in the current directory.
`BOOTSTRAP_SCRIPTS_URL`	Base URL the install scripts are downloaded from. Wins over the release pin and the release file; `flui version` shows it.
`FLUI_DEBUG_SCRIPTS`	Any value saves a copy of each generated install script, secrets removed, under `~/.flui/debug/<cluster-id>/`.

An install pins every component to the release the CLI shipped with. The release file overrides any part of that pin, which is how a development or staging build gets installed. Fields you leave out stay pinned.

Examples

# Run one command against another profile, without
# switching the active one
FLUI_PROFILE=staging flui app list

# Talk to an installation with a key from the environment,
# vault untouched
FLUI_API_KEY=… flui app list

# Override the certificate mode for one run
FLUI_CERTIFICATE_MODE=staging flui env export-config --dry-run

# Back an app up to S3 with credentials from the environment
FLUI_S3_ACCESS_KEY=… FLUI_S3_SECRET_KEY=… \
  flui app backup create my-app \
  --bucket archive --endpoint https://s3.example.com