Flux CLI
Installation
brew install fluxcd/tap/flux
# or: curl -s https://fluxcd.io/install.sh | sudo bash
Default namespace is flux-system. Uses ~/.kube/config.
Command Map
Bootstrap — Initialize Flux on a cluster via GitOps
flux bootstrap github|gitlab|gitea|bitbucket-server|git|azure-devops
# Example
flux bootstrap github \
--owner=my-org \
--repository=fleet-infra \
--branch=main \
--path=clusters/production \
--personal
Sources — Where Flux pulls manifests and charts from
# Create sources
flux create source git <name> --url=<repo-url> --branch=<branch>
flux create source helm <name> --url=<chart-repo-url>
flux create source oci <name> --url=<oci-url>
flux create source bucket <name> --bucket-name=<name> --endpoint=<url>
# Query sources
flux get sources all|git|helm|oci|bucket|chart
flux export source git|helm|oci|bucket [name] [--all]
flux reconcile source git|helm|oci|bucket|chart <name>
flux suspend source git|helm|oci|bucket <name>
flux resume source git|helm|oci|bucket <name>
flux delete source git|helm|oci|bucket <name>
Kustomizations — Deploy manifests from sources
# Create
flux create kustomization <name> \
--source=GitRepository/<source-name> \
--path=./path \
--prune=true
# Build locally (preview what would be applied)
flux build kustomization <name> --path=./local/path
# Diff against cluster (exit 0=no diff, 1=has diff)
flux diff kustomization <name> --path=./local/path
# Manage
flux get kustomizations
flux reconcile kustomization <name>
flux suspend kustomization <name>
flux resume kustomization <name>
flux export kustomization <name>
flux delete kustomization <name>
Helm Releases — Deploy Helm charts
# From a HelmRepository
flux create helmrelease <name> \
--source=HelmRepository/<repo-name> \
--chart=<chart-name> \
--chart-version=">=1.0.0" \
--values=./values.yaml
# From a GitRepository
flux create helmrelease <name> \
--source=GitRepository/<repo-name> \
--chart=./charts/my-chart
# Manage
flux get helmreleases
flux reconcile helmrelease <name>
flux suspend helmrelease <name>
flux resume helmrelease <name>
flux export helmrelease <name>
flux delete helmrelease <name>
flux debug helmrelease <name>
Image Automation — Auto-update images
# Set up image scanning
flux create image repository <name> --image=<registry/image>
flux create image policy <name> \
--image-ref=<repo-name> \
--select-semver=">=1.0.0"
# Set up auto-update
flux create image update <name> \
--git-repo-ref=<git-source> \
--git-repo-path=./clusters \
--checkout-branch=main \
--push-branch=main \
--author-name=flux \
--author-email=flux@example.com
# Query
flux get images all|repository|policy|update
flux reconcile image repository|policy|update <name>
Alerts & Receivers — Notifications
# Create an alert provider (Slack, Teams, GitHub, etc.)
flux create alert-provider <name> \
--type=slack \
--channel=general \
--address=https://hooks.slack.com/...
# Create an alert
flux create alert <name> \
--provider-ref=<provider-name> \
--event-source="Kustomization/*"
# Webhook receivers (trigger reconciliation from external events)
flux create receiver <name> \
--type=github \
--event=push \
--resource=GitRepository/<source-name> \
--secret-ref=webhook-secret
Secrets — Authentication for sources
flux create secret git <name> --url=<repo-url> --username=<u> --password=<p>
flux create secret helm <name> --username=<u> --password=<p>
flux create secret oci <name> --url=<registry> --username=<u> --password=<p>
flux create secret tls <name> --cert-file=cert.pem --key-file=key.pem
flux create secret proxy <name> --address=<proxy-url>
flux create secret githubapp <name> --app-id=<id> --app-installation-id=<id> \
--app-private-key-file=key.pem
OCI Artifacts — Push/pull manifests as OCI images
# Push local manifests to an OCI registry
flux push artifact oci://<registry>/<name>:<tag> \
--path=./manifests \
--source=https://github.com/org/repo \
--revision=main@sha1:abc123
# Pull artifact locally
flux pull artifact oci://<registry>/<name>:<tag> --output=./output
# Tag, list, diff
flux tag artifact oci://<registry>/<name>:<tag> --tag=latest
flux list artifacts oci://<registry>/<name>
flux diff artifact oci://<registry>/<name>:<tag> --path=./local
Diagnostics & Debugging
# View controller logs
flux logs [-f] [--level=error] [--kind=Kustomization] [--name=my-app] [-A]
# View events
flux events [--for=Kustomization/<name>] [-A]
# Trace an object through the GitOps pipeline
flux trace <kind> <name> [-n <namespace>]
# View resource tree under a Kustomization/HelmRelease
flux tree kustomization|helmrelease <name> [-n <namespace>]
# Reconciliation statistics
flux stats
# Check Flux prerequisites and installation
flux check
Installation & Lifecycle
# Install Flux controllers (without bootstrap)
flux install [--components=source-controller,kustomize-controller,...]
# Uninstall Flux
flux uninstall
# Check installation health
flux check
# Version info
flux version
Common Workflows
Bootstrap + deploy an app
# 1. Bootstrap Flux on a cluster
flux bootstrap github --owner=my-org --repository=fleet --path=clusters/prod --personal
# 2. Verify bootstrap succeeded
flux check
flux get all
# 3. Create a source
flux create source git my-app \
--url=https://github.com/my-org/my-app \
--branch=main --interval=1m
# 4. Deploy via Kustomization
flux create kustomization my-app \
--source=GitRepository/my-app \
--path=./deploy --prune=true --interval=5m
# 5. Verify reconciliation
flux get kustomization my-app
Deploy a Helm chart
# 1. Add the chart repo
flux create source helm bitnami \
--url=https://charts.bitnami.com/bitnami --interval=1h
# 2. Create the release
flux create helmrelease nginx \
--source=HelmRepository/bitnami \
--chart=nginx \
--chart-version=">=15.0.0" \
--values=./nginx-values.yaml
# 3. Verify release is ready
flux get helmrelease nginx
Preview changes before applying
# Build locally
flux build kustomization my-app --path=./deploy
# Diff against live cluster
flux diff kustomization my-app --path=./deploy
Debug a failing reconciliation
# Check what's failing
flux get all -A --status-selector ready=false
# View logs for errors
flux logs --level=error -f
# Trace a specific object
flux trace deployment my-app -n default
# Debug a HelmRelease
flux debug helmrelease my-release -n default
Export for backup / migration
# Export everything
flux export source git --all > sources.yaml
flux export kustomization --all > kustomizations.yaml
flux export helmrelease --all > helmreleases.yaml
Maintenance window
# Suspend all kustomizations
flux suspend kustomization --all -n flux-system
# Do maintenance...
# Resume
flux resume kustomization --all -n flux-system
References
Global Flags
All commands inherit standard Kubernetes flags:
| Flag | Default | Description |
|---|
--kubeconfig | ~/.kube/config | Path to kubeconfig |
--context | — | Kubeconfig context |
-n, --namespace | flux-system | Namespace scope |
--timeout | 5m | Operation timeout |
--verbose | — | Print generated objects |
--export | — | Output YAML to stdout instead of applying |
Tips
--export on any create command generates YAML without applying — pipe to a file
and commit to Git for true GitOps.flux get all -A --status-selector ready=false finds problems fast.flux diff kustomization exits with code 1 if there are differences — useful for
CI pipeline gates.flux reconcile triggers an immediate sync instead of waiting for the interval.flux trace walks backward from any Kubernetes object to its Flux source.