Environments

The env topic owns the lifecycle of the control cluster — the Flui cluster that runs the platform itself: API, dashboard, identity provider, and observability backend. Workload clusters (the ones that host user applications) are managed via Clusters and nodes.

env destroy permanently deletes the control cluster and all its data. To delete a workload cluster, use flui cluster destroy — never env destroy.

Provisioning

flui env create

The single command that brings the control cluster up. Interactive when provider credentials or admin email are missing (see Getting started for the first-run experience).

flui env create                       # all defaults, streams provisioning live
flui env create --node-size cx32      # pick a specific server size
flui env create --node-count 2        # add two worker nodes
flui env create --region fsn1         # pin a region
flui env create --acme-staging        # use Let's Encrypt staging
flui env create -d                    # detached: queue and exit
flui env create --wait                # block with a single spinner instead of streaming logs

The available node sizes and region codes are provider-specific — a code that exists on one provider means nothing on another. To see what each provider offers, use flui server-types list:

flui server-types list --provider <name>                # all sizes for a provider
flui server-types list --provider <name> --region <r>   # filter by region
flui server-types list --provider <name> --json         # machine-readable

If you omit --node-size or --region, env create picks the provider’s recommended default for each, so most users never need to specify them explicitly.

Flag	Default	Description
-p, --provider	hetzner	Cloud provider — see Getting started for the providers supported today.
-r, --region	provider default	Region code, provider-specific (flui server-types list --provider <name> to list).
--node-size	provider recommended	Server type, provider-specific (flui server-types list --provider <name> to list).
--node-count	0	Number of worker nodes (0 = master-only).
--disk-size	included with the size	Root disk size in GB. Required for network-storage instance types; optional for types that bundle a local SSD.
--configure-firewall	true	Configure the firewall after creation.
--firewall-ip	auto-detect	Source IPs / CIDRs allowed by the firewall (comma-separated).
--acme-staging	false	Use Let’s Encrypt staging — non-trusted cert, no practical rate limits.
--no-shared-storage	false	Disable Flui shared storage (NFS+fscache). Falls back to dedicated local-disk placement on each node. See Storage classes and dedicated placement.
--shared-storage-size	20	Size in GB of the master shared-storage volume (only when shared storage is enabled). Minimum: 10.
-d, --detached	false	Queue the operation and exit immediately.
--wait	false	Block with a single spinner instead of streaming logs.

Default mode streams the cloud-init log of the master live over SSH — this is the recommended path for interactive use. -d and --wait are for scripts/CI and degraded modes respectively; see Getting started for the full rationale.

Status and credentials

flui env status

One-shot status of the control cluster: state (creating / ready / error / stopped), node count, and any in-flight operation.

flui env status

flui env credentials

Prints the public endpoints of the control cluster (API, dashboard, identity provider, Grafana) and, optionally, probes each one.

flui env credentials                  # endpoints only
flui env credentials --test           # probe each endpoint and report reachability
flui env credentials --format json    # machine-readable output
flui env credentials --show-secrets   # include secret values (prefer flui dev creds)

Flag	Effect
--format text|json	Output format. Default: text.
--test	Probe each endpoint for reachability.
--verify	Check that the in-cluster Flui secrets bundle is present.
--show-secrets	Print secret values in plain text. Prefer flui dev creds for local development.

Power state

flui env stop / flui env restart

Power off the control-cluster servers without deleting their volumes, then power them back on. Useful for cutting costs on idle development installations.

flui env stop
flui env restart

flui env destroy

Permanently destroys the control cluster, including its volumes and data. Asks to confirm by default.

flui env destroy
flui env destroy --force              # skip the confirmation prompt

Capacity and scaling

flui env capacity

Reports the control cluster’s master node capacity (allocatable / used / free CPU and memory) and a sorted list of server-type upgrade/downgrade candidates with monthly cost delta. Use it to plan a flui env scale-master operation — especially when an application that wants dedicated placement on the master (a database, typically) doesn’t fit on the current size.

flui env capacity
flui env capacity --top 5                # show 5 candidates instead of 10
flui env capacity --direction upgrade    # only larger sizes
flui env capacity --direction downgrade  # only smaller sizes

Flag	Default	Effect
--top <n>	10	Maximum number of candidates listed.
--direction	all	Filter candidates: all, upgrade, or downgrade.

flui env scale-master / flui env scale-node

Vertically scale the control cluster’s master or a worker node to a different server type. Planned-maintenance operations: the cluster powers the node down, asks the provider to change the type, powers it back up, and waits for the cluster to report healthy. Expected downtime ~3–5 minutes — workloads pinned to the node (typically dedicated databases on the master) are unavailable for that window; snapshot them first. See Storage classes and dedicated placement for the conceptual model.

flui env scale-master                            # auto-pick next upgrade candidate
flui env scale-master --type cpx41               # pick a specific type
flui env scale-node worker-1 --type cpx31        # NAME is positional
flui env scale-node worker-1 --type cx32 --confirm

Flag	Effect
-t, --type <name>	Target server type. If omitted, auto-picks the next-bigger candidate (smallest positive cost delta).
--upgradeDisk	(Hetzner) Also grow the local OS disk. One-way: cannot be reversed by a later downgrade.
--confirm	Skip the typed confirmation prompt.

scale-node requires the worker name as a positional argument (worker-1, worker-2, …); scale-master does not (the master is unambiguous).

flui env storage

Shows the status of the cluster’s shared storage: the underlying provider volume, the NFS export, and a summary of the volume claims mounted by applications.

flui env storage

flui env storage-expand

Grows the cluster’s shared-storage volume on the provider and extends the filesystem on top over SSH. Online operation — no downtime, no pod restarts — but one-way: providers Flui integrates with let volumes grow, not shrink.

flui env storage-expand --size 50              # new size in GB
flui env storage-expand --size 100 --confirm   # skip the typed confirmation
flui env storage-expand                        # defaults to current + 10 GB

Flag	Effect
-s, --size <gb>	New volume size in GB (must be greater than current). Default: current size + 10 GB.
--confirm	Skip the typed confirmation prompt.

Firewall

flui env update-firewall

Updates the allow-list of source IPs / CIDRs for the cluster firewall. If --ip is omitted, the CLI auto-detects the public IP it’s running from. Intended use: re-granting SSH access from your workstation when its public IP changes.

flui env update-firewall                                # auto-detect
flui env update-firewall --ip 203.0.113.42
flui env update-firewall --ip "203.0.113.0/24,198.51.100.5/32"

⚠️ Heads-up: today this command rewrites the entire firewall ruleset with the platform’s default template (SSH from the given IPs, plus 80 and 443 open to the world). Any custom rule you added manually — extra allow-listed IPs, a non-standard port, an internal service exposure — will be wiped out. If you only need to swap the SSH source IP and you have custom rules elsewhere, edit the SSH rule directly on the provider console for now. A targeted SSH-only mode for this command is on the roadmap.

Diagnostics and maintenance

flui env logs

Tails the local log files that the Flui orchestration writes while it drives an infrastructure operation — cluster create, node scale, storage expand, destroy, firewall update, and so on. Each operation produces one file at ~/.flui/logs/<operationId>.log on the workstation that ran the command; this view simply reads from there.

flui env logs                         # most recent operation
flui env logs --tail 50
flui env logs --list                  # list operations that have logs
flui env logs --operation <id>        # logs for one specific operation

This is not where to look for runtime cluster logs (use flui env inspect) or application logs (use flui app logs). It is the diagnostic trail of the operation the CLI just ran: what step it was on, what the provider answered, where it failed.

flui env inspect

Connects to a node over SSH and tails one of its system logs. Useful when the high-level diagnostics aren’t enough and you need to see what the OS itself is doing.

The default invocation — flui env inspect with no flags — is exactly the same view that flui env create streams live during provisioning (the master’s cloud-init-output log). Run it after the fact, or against a different node, when you need to re-watch what happened or see what is happening now.

flui env inspect                                  # master, cloud-init-output, last 100 lines
flui env inspect --node worker-1 --log cloud-init
flui env inspect -f --log k3s                     # follow live

Flag	Default	Effect
-n, --node	master	Node name (master, worker-1, …).
-l, --log	cloud-init-output	One of cloud-init, cloud-init-output, k3s, syslog.
-t, --tail	100	Number of lines to show.
-f, --follow	—	Follow the log in real time.

flui env force-ready

Forces the cluster status to ready when it is actually operational but the platform left it stuck in error or creating after a transient failure during an async operation. Recovery helper — use it only after confirming the cluster really is healthy.

flui env force-ready
flui env force-ready --skip-health-checks   # bypass health validation

flui env uncordon

Recovery helper paired with scale-master / scale-node. Those operations temporarily stop the target node from accepting new workloads before resizing it, then re-open it to new workloads once the resize completes. If the operation is interrupted in the middle — crash, timeout, network blip — the node is left in the closed state and won’t accept anything new. This command flips it back to accepting workloads.

flui env uncordon master
flui env uncordon worker-1                # positional argument: master, worker-1, …

You should never need it on a healthy cluster — successful scale-master / scale-node runs leave nothing to recover.

flui env diag-ca

Diagnoses the cluster’s certificate authority configuration. The first thing to run when you see TLS or self-signed certificate errors from the dashboard or the API.

flui env diag-ca

flui env refresh-kubeconfig

Re-fetches the cluster’s authentication material from the master over SSH and refreshes the locally cached copy. Use it after a manual intervention on the master that may have rotated the credentials.

flui env refresh-kubeconfig

flui env orphan-volumes

Lists or cleans up Flui-managed provider volumes left behind by a previous failed env destroy. Useful to recover quota after an incident; safe to run anytime.

flui env orphan-volumes              # list orphans
flui env orphan-volumes --delete     # delete them

Contributor-only commands

The commands below are not part of the normal operator workflow. They exist for Flui contributors running the flui.api and flui.dashboard repos locally against a remote cluster, or for one-off recovery scenarios that require platform-internal knowledge. End users can skip this section.

flui env sync

Reads the live endpoint URLs (API, identity provider, observability) from the cluster and writes them into the flui.api repo’s .env and the dashboard’s config.json, so a local dev API/dashboard talks to the right remote endpoints. Read-only on the cluster side; never touches database or secret material.

flui env sync
flui env sync --dry-run               # show the diff without writing
flui env sync --debug                 # print the raw cluster discovery output

flui env export-config

Writes the control cluster’s endpoints (and non-sensitive defaults) into the .env of the flui.api repo, so you can run the API locally against a remote cluster. Does not write secrets — use flui dev creds for those.

flui env export-config
flui env export-config --dry-run
flui env export-config --no-backup

Flag	Effect
--dry-run	Show the diff without writing.
--[no-]backup	Back up an existing .env.
--force	Skip confirmation.
--no-dashboard	Do not update the dashboard’s config.json.
--api-path <path>	One-off override of the apiPath preference.
--dashboard-path <path>	Override dashboardPath.
--certificate-mode <mode>	Override certificateMode (production / staging / preflight).
--email <email>	Override email.
--save	Persist any value entered at the prompt into the active profile.