Command line

fluxlint check   [flags] [entrypoint ...]   analyse the repository
fluxlint graph   [flags] [entrypoint]       print the dependency graph
fluxlint explain <rule>                     describe a rule
fluxlint rules                              list all rules
fluxlint contract push|pull <image>         attach a contract to an image, or read one
fluxlint version                            print the version

An entrypoint is the directory a cluster's bootstrap Kustomization points at, relative to the repository root. Entrypoints given on the command line replace the ones in .fluxlint.yaml.

check

Flag	Default	Meaning
--repo	.	the repository root
--config	<repo>/.fluxlint.yaml	the config file. A missing file means defaults.
--base		a Git ref to compare with, such as origin/main. Only new findings fail the run, and the transition is analysed. See Check merge requests.
--format	text	text, json, gitlab (Code Quality), sarif or github (workflow annotations)
--output		write the report to this file and print the text report to stdout
--fail-on	error	the lowest severity that fails the run: error or warning
-v		list suggestions (info) in full
--observed		a file of observed reconcile durations. See Shorten bootstrap time.
--cluster-state		the Flux objects of a real cluster at this commit (kubectl get kustomizations.kustomize.toolkit.fluxcd.io,helmreleases.helm.toolkit.fluxcd.io -A -o json). Every failure that no finding predicted is reported as FL-O001. Takes one entrypoint. See Run beside a cluster test.
--offline		never use the network. A source that is not cached is reported as FL-X001.
--refresh		resolve floating refs again: branches, semver ranges, latest
--cache-dir	the user cache directory	where fetched sources are kept. sources.cacheDir in the config sets it too.

Several entrypoints are analysed in parallel and share their builds.

Exit codes

Code	Meaning
0	no findings at or above --fail-on
1	findings at or above --fail-on
2	fluxlint could not run: bad flags, an unreadable config, no entrypoint

JSON output

--format json prints one document:

{
  "version": "fluxlint v0.2.0 go1.26.0 linux/amd64",
  "entrypoints": [
    {
      "entrypoint": "clusters/production",
      "kubeRelease": "v1.35.0",
      "findings": [
        {
          "rule": "FL-G004",
          "name": "missing-namespace",
          "severity": "error",
          "entrypoint": "clusters/production",
          "component": "flux-system/apps",
          "object": "ConfigMap/team-a/settings",
          "file": "apps/settings.yaml",
          "line": 4,
          "message": "namespace \"team-a\" is not created by any component"
        }
      ],
      "timing": {
        "bound": 300000000000,
        "criticalPath": [
          {"event": "start(flux-system/apps)", "at": 0, "added": 0, "reason": "created by parent"},
          {"event": "ready(flux-system/apps)", "at": 300000000000, "added": 300000000000, "reason": "apply and health timeout"}
        ]
      },
      "components": [
        {"component": "flux-system/apps", "parent": "clusters/production", "rendered": true, "objects": 42, "path": "./apps"},
        {"component": "flux-system/operator", "parent": "clusters/production", "rendered": false,
         "notRendered": "source GitRepository/flux-system/operator unavailable",
         "error": "https://git.example.com/operator (tag v1.2.0): authentication required",
         "objects": 0, "source": "GitRepository/flux-system/operator", "path": "./config/default"}
      ]
    }
  ],
  "elapsedMs": 940
}

Durations are nanoseconds. Some findings carry a detail list of extra lines. With --base, findings that also exist at the base carry "existing": true.

components lists everything the entrypoint reconciles and whether fluxlint could render it. Read it before the findings: a component that was not rendered has no findings because it was not looked at, not because it is clean. kubeRelease is the Kubernetes release whose API schemas built-in objects were checked against; it is absent when they could not be loaded.

To hand a run to someone else, this is the file to send:

fluxlint check -v --format json --output fluxlint-report.json

It holds object names, file paths, source URLs and the text of error messages. It holds no manifest contents, Secret values or credentials.

graph

graph takes the same flags as check for finding the repository, the config and the sources. --format is dot (the default) or mermaid. It draws one entrypoint, which you name unless the config lists exactly one. See Draw the graph.

explain and rules

fluxlint rules lists every rule with its default severity. fluxlint explain FL-G002 prints what a rule means and what to do about it. The same text is in the rules reference.

contract

fluxlint contract push [-f file] <image>
fluxlint contract pull <image>

push attaches a contract to an image that is already in a registry. -f defaults to fluxlint-contract.yaml. pull prints the contract attached to an image, and exits 1 when there is none. --timeout bounds how long the registry may take, and defaults to one minute.