Deploy and catalog validate

flui deploy takes a flui.yaml manifest and rolls the application onto a cluster. The same command handles both manifest kinds:

kind: CatalogApp — the image already exists in a registry; Flui pulls and deploys it.
kind: Application — the image is built from source by the CI of the platform that hosts the repo, then the resulting image is deployed.

The user-visible flow is the same in both cases: read the manifest, target a cluster, run; the difference is whether there is a build step in front. See the concept chapters Catalog vs Application and Build pipeline, today and tomorrow for the model.

`flui deploy [<file>]`

flui deploy                                # ./flui.yaml, auto-detect repo/branch/cluster
flui deploy ./apps/api/flui.yaml           # explicit manifest path
flui deploy --repo acme/my-app --branch main
flui deploy --env DATABASE_URL=postgres://... --env API_KEY=secret
flui deploy --detach                       # queue and exit
flui deploy --validate-only                # check the manifest, don't deploy
flui deploy --cluster my-cluster           # pin a target cluster

Argument / Flag	Effect
`<file>`	Path to the manifest. Default: `./flui.yaml`.
`-c, --cluster <name\|id>`	Target cluster. Auto-detected when the active profile has only one.
`-r, --repo <owner/repo>`	Source repo. For `kind: Application`, auto-detected from `git remote origin`.
`-b, --branch <name>`	Branch to build. For `kind: Application`, auto-detected from the current branch.
`-d, --domain <fqdn>`	Custom FQDN for the app. Auto-assigned from the cluster’s DNS zone otherwise.
`--hostname <ip\|domain>`	How the app is exposed: `ip` (a `nip.io` address derived from the cluster IP) or `domain` (a hostname under the cluster’s DNS zone). Default: taken from the manifest or the cluster setup. `kind: CatalogApp` only.
`--cert-challenge <http-01\|dns-01>`	How the TLS certificate is validated. `http-01` issues a dedicated per-host certificate and works on any reachable domain; `dns-01` uses the cluster’s wildcard certificate and needs a DNS zone. Default: chosen from the cluster setup. `kind: CatalogApp` only.
`--cert-provider <lets-encrypt\|lets-encrypt-staging>`	Which issuer signs the certificate. `lets-encrypt-staging` issues untrusted test certificates and avoids rate limits while you iterate. Default: the cluster’s configured issuer. `kind: CatalogApp` only.
`--name <name>`	Display name override. Default: `metadata.name` from the manifest.
`-e, --env KEY=VALUE`	Per-deploy env override. Repeatable.
`--detach`	Return as soon as the build/deploy is queued. Track with `flui app status`.
`--no-wait`	Alias of `--detach`, kept for symmetry with other commands.
`--no-build`	Skip the build step and redeploy the current image. Useful when you only changed `flui.yaml` settings (env, ports, healthcheck, endpoint).
`--image <ref>`	Deploy a specific image reference (e.g. `registry/owner/repo:sha`). Skips the build pipeline; useful for rollbacks.
`--skip-endpoint`	Skip DNS and TLS provisioning. `kind: CatalogApp` only.
`--validate-only`	Validate the manifest against the spec and exit, without deploying.
`--skip-checks`	Bypass the framework pre-flight checks (e.g. the Next.js standalone-output check). Only use when you are certain the build will succeed despite the warnings. `kind: Application` only.

Auto-detect rules

flui deploy with no arguments behaves as follows:

The manifest is ./flui.yaml.
For kind: Application: the repo is whatever git remote origin points at, the branch is the current one (from git branch --show-current).
The cluster is the only one in the active profile; with more than one cluster, pass -c, --cluster.

Any of these can be overridden with the corresponding flag.

Fast iteration

When you change only configuration in flui.yaml (env vars, ports, healthcheck, endpoint) and don’t need a new image:

flui deploy --no-build                              # re-deploy the current image
flui deploy --image registry/owner/repo:abc123      # deploy a known-good image

--no-build skips the build entirely; --image lets you pin a specific image you already trust (rollback, hand-picked tag).

Endpoint and TLS

For kind: CatalogApp, Flui provisions the app’s public endpoint (hostname plus TLS certificate) at install time. Left alone, it reads the cluster setup:

with a DNS zone and a wildcard certificate, the app reuses the shared wildcard (dns-01, no per-app validation);
otherwise it issues a dedicated per-host certificate validated over HTTP (http-01).

Override that choice when you need to:

flui deploy --cert-challenge http-01              # force a dedicated per-host certificate
flui deploy --cert-provider lets-encrypt-staging  # untrusted test certs, no rate limits
flui deploy --hostname ip                          # expose on a nip.io address instead of a domain

--cert-challenge http-01 is the one to reach for when you want an app to hold its own certificate even though the cluster has a wildcard available. --skip-endpoint skips this step entirely — you can set the domain and certificate later from the app.

These flags act on kind: CatalogApp endpoints, where you install from a manifest you don’t own and override on the command line. For kind: Application (your own repo) the same settings live in your flui.yaml under domain: — hostnameMode, certChallenge, certificateProvider — and the deploy reads them from there:

domain:
  auto: true
  tls: true
  certChallenge: http-01      # dedicated per-host certificate

`flui catalog validate <file>...`

Validates one or more flui.yaml manifests against the Flui spec. Read-only: nothing is deployed, nothing on the cluster is touched.

flui catalog validate ./flui.yaml
flui catalog validate ./catalog/vaultwarden.flui.yaml ./catalog/memos.flui.yaml

<file>... is repeatable: pass several manifests in one shot. The validator covers both kind: CatalogApp (full schema check) and kind: Application (lighter checks — some fields are populated by the build pipeline so they are not required at validation time).

The same check is also available inline as flui deploy --validate-only, which is convenient when you are about to deploy and want a quick gate.