Clusters, nodes, and SSH

This page covers the topics that operate on a cluster as a whole or on the nodes inside it: cluster, node, server-types, and ssh.

A note on which cluster these commands target: the CLI keeps a local list of every cluster in the active profile — both the control cluster (the one that runs Flui itself) and any workload clusters (the ones that host user applications). The commands in this page do not distinguish between the two: by default they pick the only cluster in the profile, or refuse to run if more than one exists without an explicit --cluster. So flui node add against a profile that only contains the control cluster will add a worker to the control cluster.

If you specifically want to manage the control cluster’s lifecycle (create, status, destroy, scale-master, …), use the dedicated env topic — it is the only surface that always targets the control cluster and exposes operations specific to it.

flui cluster destroy

Permanently destroys a workload cluster and all its nodes. The command asks the user to confirm by retyping the cluster name before proceeding.

flui cluster destroy <cluster-name-or-id>
flui cluster destroy <cluster> --force                # skip confirmation
flui cluster destroy <cluster> --force --no-wait      # queue and exit

Argument / Flag	Effect
<cluster>	Cluster name or ID (required).
-f, --force	Skip the typed confirmation prompt.
--no-wait	Queue the destroy operation and return immediately.

The control cluster is not in scope here. For that one, use flui env destroy.

Nodes

The node topic operates on the workers of a cluster. The master is listed by node list but cannot be added or removed through this topic — it is provisioned when the cluster is created and goes away only with cluster destroy / env destroy.

The target cluster is auto-detected when the active profile has only one cluster, otherwise it has to be passed with -c, --cluster <name-or-id>. As noted in the intro, “the active profile’s only cluster” today is most often the control cluster — node add works against it the same way it works against a workload cluster.

flui node list

Lists every node in the target cluster (master plus workers), with status and role.

flui node list
flui node list --cluster my-cluster
flui node list --output json

Flag	Default	Effect
-c, --cluster <name|id>	auto-detect	Target cluster.
-o, --output table|json	table	Output format.

flui node add

Provisions one or more new worker servers from the target cluster’s provider and joins them to the cluster. Workers are created in the same provider/region/server-type configuration as the existing cluster — node add has no flag to override the size.

flui node add                            # add one worker, auto-detect cluster
flui node add --cluster my-cluster       # target a specific cluster
flui node add --no-wait                  # queue and exit

Flag	Default	Effect
-c, --cluster <name|id>	auto-detect	Target cluster.
-n, --count <n>	1	Number of workers to add. Range: 1–5.
--no-wait	false	Queue the operation and return immediately.

flui node remove

Removes a worker from the cluster. The flow is: stop scheduling new workloads on the node, move existing workloads off to other nodes, then delete the server on the provider side. The master cannot be removed through this command — node remove refuses, and you destroy the whole cluster instead.

flui node remove <node-id>
flui node remove <node-id> --cluster my-cluster
flui node remove <node-id> --no-wait

Get <node-id> from flui node list. The CLI validates the ID against the cluster’s current nodes before queuing the operation: an unknown ID fails immediately with a pointer back to flui node list, so you never end up with a queued operation that is doomed to fail.

The wait window is 5 minutes by default. If the removal takes longer (slow drain, contended workloads), the CLI returns control with a note that the operation is still running — flui node list shows the final state once it completes. --no-wait short-circuits this and returns as soon as the operation is queued.

Argument / Flag	Effect
<node-id>	Node ID to remove (required, master IDs are rejected).
-c, --cluster <name|id>	Target cluster (auto-detect when only one).
--no-wait	Queue and return immediately.

Server types

flui server-types list

Lists the server types a provider offers, with CPU / RAM / disk / monthly price. Use it before flui env create (the only Flui command that asks for --node-size and --region) to pick a meaningful combination. Results are cached locally — --force-refresh re-fetches from the provider API.

flui server-types list --provider <name>
flui server-types list --provider <name> --region <r>
flui server-types list --provider <name> --json
flui server-types list --provider <name> --force-refresh

Flag	Required	Effect
-p, --provider <name>	yes	Cloud provider — see Getting started for the providers supported today.
-r, --region <code>	no	Filter by region / location code.
--json	no	Machine-readable output.
--force-refresh	no	Skip the local cache and re-fetch from the provider.

SSH access

flui ssh <node>

Opens a shell on a cluster node, authenticating with the SSH CA that the active profile manages. No SSH key setup required on the user side — the CLI signs a short-lived certificate transparently.

flui ssh master
flui ssh worker-1
flui ssh worker-2

Argument	Effect
<node>	Node alias: master, worker-1, worker-2, …

SSH is the lowest-level surface Flui exposes on a node. Use it for direct shell work — local debugging, development against the running cluster, ad-hoc inspection of system processes, or driving the underlying orchestrator with kubectl from the master where it is preconfigured. For most everyday operations (metrics, logs, restarts, deploys) the higher-level Flui commands are the right entry point and you should not need a shell.