Getting Started

This page walks through the first hour with the CLI: install, create the control cluster that hosts the Flui platform, log in, and deploy an application onto it. The env create command is interactive and prompts for everything it needs (provider credentials, admin email), so the only real prerequisite is the install. Each section links to its dedicated reference page when you need the full flag-by-flag detail.

Install

The CLI is published on npm as @flui-cloud/cli and installs globally:

npm install -g @flui-cloud/cli      # or: pnpm add -g, yarn global add
flui --version

To upgrade later, run flui update — it self-replaces the global install with the latest published version.

flui --help lists the topics available; each command has its own --help with flags and examples.

Create the control cluster

The Flui control plane — API, dashboard, identity provider, observability stack — runs on a dedicated Flui cluster called the control cluster. One command creates it, and it is interactive: if provider credentials or the admin email are missing, the CLI prompts for them and persists the answers before continuing.

flui env create                     # interactive: prompts for missing config, then provisions
flui env create --node-count 2      # add two worker nodes
flui env status                     # one-shot status check
flui env credentials                # public endpoints (dashboard, API, OIDC, Grafana)
flui env credentials --test         # also probes each endpoint

Run it in the default mode — that’s the recommended path. The operation goes through several phases — provider VM, cloud-init, SSH CA enrollment, K3s install, Let’s Encrypt, DNS reconciliation — and the default behavior is built for this: the CLI follows the provider job until the master is reachable, then opens an SSH session to it and streams /var/log/cloud-init-output.log live, so you see every step of the installation as it happens and the auto-reconcile of DNS and TLS at the end.

Two alternative modes exist for niche cases — -d / --detached to queue the job and exit immediately (scripts, CI), and --wait to block with a single spinner instead of streaming logs. Neither is recommended for interactive use; details are in Environments along with the full flag set (provider, region, size, worker count).

Non-interactive setup

For CI or unattended installs, configure the same values up front via flui config set so env create finds them and skips the prompts:

flui config set email you@example.com
flui config set hetzner <HETZNER_API_TOKEN>      # single-token providers: inline OK
flui config set scaleway                          # pair-credential providers: interactive only

The full per-provider credential schema, validation behavior, and storage model are in Profiles and config.

Log in

Authentication is OIDC against the identity provider that lives inside your installation, so this step makes sense only after the control cluster is up — there is nothing to authenticate against beforehand. Joining a pre-existing installation (one a teammate already created) is the same: import its endpoints into a fresh profile first, then log in.

Once the installation is reachable, flui auth login opens the browser, completes an OIDC code-with-PKCE flow against your installation’s identity provider, then uses the resulting access token to mint a long-lived M2M API key and saves it in the active profile. From that point on every command that talks to the API uses the key transparently.

flui auth login              # opens the browser
flui auth login --headless   # prints the authorization URL instead of opening one

The CLI listens for the OAuth callback on http://localhost:8899 (it falls back through 8900–8910). Plain flui auth login only works on a host that has a graphical browser; on a remote host without one, use --headless and SSH-forward the callback port so the redirect can reach the listener — e.g. ssh -L 8899:localhost:8899 server.

For CI or scripting, swap the interactive step for a one-shot key generation — see Authentication.

Connect GitHub

Before the first flui deploy of an Application (source-built) repo, three one-off connections need to happen for your user: the Flui GitHub App has to be installed on your GitHub account/org, a GHCR PAT has to be saved so the cluster can pull the built images, and the specific repository has to be imported into your Flui account. All three live under the integration and repo topics.

flui integration connect github      # installs the Flui GitHub App (and grants OAuth)
flui integration ghcr-pat set         # saves a classic PAT with read:packages scope
flui repo connect dawit-io/my-app     # imports a specific repo (or omit for picker)
flui integration list                 # shows both GitHub and GHCR PAT status
flui repo list                        # lists repos already connected

integration connect github opens the browser to the GitHub App install flow and waits for the local callback (8899, falling back through 8900–8910 — same as auth login). The same browser round-trip also covers the OAuth grant Flui needs to commit the .github/workflows/flui.yml workflow on first deploy. Pass --headless to print the install URL instead of opening one — useful over SSH.

integration ghcr-pat set opens the GitHub token-creation page pre-filled with the right scopes (read:packages, delete:packages), then prompts for the generated token. Without a PAT the cluster fails the image pull with ImagePullBackOff even when the build succeeds — GitHub App and OAuth tokens cannot read container packages.

repo connect accepts the full owner/repo slug, or no argument for an interactive picker over the repos accessible through the connected integration. The repo must be visible to the Flui GitHub App installation; if it isn’t, re-run integration connect github and add it during the install.

A flui deploy on a repo that hasn’t been imported fails up front with Repository "<owner>/<repo>" is not connected to your account — that is the signal to run flui repo connect. CatalogApps (kind: CatalogApp) don’t need any of these steps; they pull a pre-built image from a public registry.

The operator who runs the installation has one additional one-time step that comes before all of the above: registering the Flui GitHub App’s credentials in Flui itself with flui integration setup-github-app. Full reference, including the GitHub-side App registration walkthrough, is in Integrations.

Deploy an application

An application is described by a flui.yaml at the root of its repository. The minimum loop is:

cd my-app/                          # repo with flui.yaml at the root
flui catalog validate ./flui.yaml   # optional: offline schema validation
flui deploy                         # auto-detects manifest, repo, branch, cluster
flui app status my-api              # live runtime status
flui app logs my-api --tail 200     # recent logs

With no arguments, flui deploy reads ./flui.yaml, auto-detects the GitHub repo from git remote origin and the branch from git branch --show-current, and targets the active profile’s only cluster. Override any of these with --repo, --branch, -c, --cluster, or by passing the manifest path as the first positional argument.

The build runs on the CI of the platform that hosts the source repo; when it finishes, the image is rolled onto the target cluster. The manifest reference is in Deploy and the post-deploy operations in Applications.

Multiple installations

Everything you just did happens inside the auto-created default profile — one isolated Flui installation on this machine. If you need a second installation (production vs staging, or a separate provider/region) the CLI handles them as additional profiles:

flui context create staging --switch # new profile, switch to it
flui context use default             # switch back

The full model is in Profiles and config; for a single-installation setup, the auto-created profile is enough and this section can be ignored.

Quick reference

# Profile & login
flui context show
flui auth login

# Config
flui config list
flui config set email you@example.com
flui config set hetzner <token>
flui config set scaleway                  # interactive

# Control cluster
flui env create
flui env status
flui env credentials --test

# GitHub
flui integration connect github
flui integration ghcr-pat set
flui integration list
flui repo connect <owner/repo>
flui repo list

# App
flui deploy
flui app list
flui app status my-api
flui app logs my-api --tail 500
flui app redeploy my-api <tag-or-digest>
flui app delete my-api --force

# Diagnostics
flui ssh master
flui app crashes my-api
flui app metrics my-api
flui env logs --tail 200