CLI Reference

The provider-agnostic reference for the Plumber CLI. The analyze command takes provider-specific flags and tokens; the config commands, plumber explain, exit codes, and output formats behave identically for both GitLab and GitHub. For installation, see the Installation page. For provider specifics, see the GitHub and GitLab pages.

Configuration

Plumber reads its policy from .plumber.yaml (override the path with --config). There are three ways to run it:

No configuration

plumber analyze works with no setup at all. When there is no .plumber.yaml and no explicit --config, Plumber runs with the default configuration embedded in the binary and prints a one-line notice on stderr. A terminal and a CI job behave identically: there is no interactive prompt. Inspect what runs in this mode with plumber config view.

If you pass --config and the file does not exist, that is a hard error; Plumber never silently substitutes the default for a file you named.

Extended configuration (recommended)

Add extends: plumber:default to make your .plumber.yaml a sparse overlay on Plumber’s shipped baseline. You write only what you change; everything else is inherited, and new controls Plumber ships in future releases apply automatically without touching your file:

extends: plumber:default
version: "2.0"

github:
  controls:
    githubActionMustComeFromAuthorizedSources:
      includePlumberDefaults: true # keep Plumber's curated trusted orgs (default)
      trustedGithubActions:
        - myorg

A section left empty in an overlay inherits the baseline rather than wiping it. On allowlist controls (authorized sources, trusted owners, and so on), includePlumberDefaults: true (the default) unions your entries with Plumber’s curated list; set it to false to use only your own list.

The commands built for this mode:

• plumber config generate --overlay writes a minimal overlay starter.
• plumber config resolve prints the full effective configuration an overlay expands to.
• plumber config view --explain shows, per control, whether the value comes from the baseline or your overlay.
• plumber config slim collapses an existing full config into a minimal overlay.

Full configuration

A .plumber.yaml without extends is a complete, self-contained policy: what is in the file is exactly what runs, and a control you leave out does not run. Nothing is inherited, so new controls Plumber ships stay off until you add them; you own and maintain the whole file (~1000 lines for the complete template).

Author one with plumber config generate (the full commented template) or plumber config init (interactive wizard). This is the right mode when your policy must be fully explicit, with nothing inherited; for auditing, plumber config resolve turns an overlay into an equivalent full file you can commit.

Command Reference

plumber analyze

The main command for analyzing GitLab CI/CD pipelines and GitHub Actions workflows.

plumber analyze [flags]

Flags

Environment variables

plumber config init

Interactive wizard to create a minimal .plumber.yaml: pick policy areas (container images, pipeline composition, branch protection, variables) and only those controls are written. For each selected area, prompts cover the tunable fields in the schema (lists, booleans, GitLab access levels, required expressions for catalog components and file templates, and so on).

Requires an interactive terminal (TTY). In CI or Docker without a TTY, use plumber config generate instead and edit the file.

Contrast: plumber config generate writes the full default template with comments (or a minimal overlay starter with --overlay); init writes a short file shaped by your answers. Both init and the plain generate produce a full configuration: nothing is inherited from the baseline afterwards.

plumber config init [flags]

Examples:

plumber config init
plumber config init -o configs/plumber.yaml

plumber config generate

Writes the official default .plumber.yaml: the full template Plumber ships with, including comments and every control documented inline. Safe for scripts and CI (no prompts). Use plumber config init when you have a TTY and want a smaller file with only the checks you pick.

With --overlay, writes a minimal overlay starter instead: a few commented lines beginning with extends: plumber:default that inherit the whole baseline. This is the recommended starting point.

plumber config generate [flags]

Examples:

plumber config generate --overlay
plumber config generate
plumber config generate --output my-plumber.yaml
plumber config generate --force

plumber config migrate

Upgrades a .plumber.yaml from schema v1 (top-level controls:) to schema v2 (per-provider gitlab.controls: / github.controls:). Comments and YAML anchors are preserved. The migration is idempotent: running it against a file already on v2 is a no-op with a friendly exit message.

By default the tool writes a sibling .plumber.yaml.v2 so you can diff before swapping. Pass --in-place to overwrite the original; the previous file is backed up to .plumber.yaml.bak.

plumber config migrate [flags]

Examples:

# Write a sibling .plumber.yaml.v2; diff before swapping.
plumber config migrate
diff .plumber.yaml .plumber.yaml.v2
mv .plumber.yaml.v2 .plumber.yaml

# Or migrate in place, with backup.
plumber config migrate --in-place

plumber config view

Display a clean, human-readable view of the effective configuration without comments.

plumber config view [flags]

Booleans are colorized for quick scanning: true in green, false in red. Color is automatically disabled when piping output.

Examples:

# View the default .plumber.yaml
plumber config view

# View a specific config file
plumber config view --config custom-plumber.yaml

# View without colors (for piping or scripts)
plumber config view --no-color

# Show where each control's value comes from (base vs overlay)
plumber config view --explain

plumber config resolve

Resolve extends and includePlumberDefaults and print the complete effective .plumber.yaml. Use it to see exactly what a scan with an overlay config will run, or to materialize an overlay into a full, self-contained file you can commit (nothing left implicit).

With no config file and no --config, it prints the built-in default configuration, i.e. what a zero-config run uses.

plumber config resolve [flags]

Examples:

plumber config resolve
plumber config resolve -c overlay.yaml -o full.plumber.yaml

plumber config slim

The inverse of plumber config resolve: collapse a full .plumber.yaml into a minimal overlay that extends plumber:default, keeping only the values that differ from the baseline. The right migration path for an existing full config you no longer want to maintain line by line.

The result is a fresh minimal file (comments are not preserved) and it is safe by construction: a control your full config disabled or omitted stays disabled, and a trust list you narrowed stays narrowed; slim then resolve never widens trust or re-enables a control. Review the output, then commit it.

plumber config slim [flags]

Examples:

plumber config slim -o .plumber.yaml
plumber config slim -c old.yaml -o slim.yaml

plumber config diff

Display a clean, human-readable view of the differences between the current configuration and the defaults, so you can see exactly what you have changed.

plumber config diff [flags]

Examples:

plumber config diff
plumber config diff --config custom-plumber.yaml
plumber config diff --config custom-plumber.yaml --no-color

plumber config validate

Validate a configuration file for correctness. Detects unknown control names and sub-keys with typo suggestions using fuzzy matching.

plumber config validate [flags]

Warnings are printed to stderr so they don’t interfere with scripted output. Use --fail-warnings to exit with code 2 when warnings are found (useful in CI).

Examples:

# Validate the default .plumber.yaml
plumber config validate

# Validate a specific config file
plumber config validate --config custom-plumber.yaml

# Fail on warnings (for CI pipelines)
plumber config validate --fail-warnings

Sample output with typos:

Configuration validation warnings:
  - Unknown control in .plumber.yaml: "containerImageMustNotUseForbiddenTag". Did you mean "containerImageMustNotUseForbiddenTags"?
  - Unknown key "tag" in control "containerImageMustNotUseForbiddenTags". Did you mean "tags"?
  - Unknown key "allowForcePushes" in control "branchMustBeProtected". Did you mean "allowForcePush"?

plumber explain

Look up detailed information for an issue code directly from the terminal.

plumber explain [ISSUE-CODE] [flags]

ISSUE-CODE supports both full and shorthand forms:

• ISSUE-412
• 412

plumber explain ISSUE-412
plumber explain 412
plumber explain --list
plumber explain --all

Sample output (plumber explain ISSUE-412):

ISSUE-412: Docker-in-Docker service detected
Control:     pipelineMustNotUseDockerInDocker

Description:
  A CI/CD job uses a Docker-in-Docker (dind) service. On shared runners
  running in privileged mode, this enables container escape, lateral
  movement, and access to secrets from other jobs on the same runner.

Remediation:
  Replace Docker-in-Docker with a safer alternative such as Kaniko or
  Buildah for building container images. These tools do not require
  privileged mode and avoid the security risks of running a Docker daemon
  inside a CI container.

Documentation: https://getplumber.io/docs/use-plumber/issues/ISSUE-412

Exit Codes

Automatic Version Check

When running locally, Plumber checks GitHub for newer releases on every invocation and prints an upgrade notice if one is available. The check runs asynchronously and has a 3-second timeout, so it never slows down the analysis.

The check is automatically skipped when:

• Running in CI environments (CI or GITLAB_CI environment variables are set)
• Using a development build (version is dev)

To disable it manually:

export PLUMBER_NO_UPDATE_CHECK=1

Output formats & artifacts

By default Plumber prints a colorized, human-readable report to your terminal (--print, on by default). Every machine-readable format below is opt-in: pass the matching flag with a destination path. Formats can be combined in a single run, so one scan can emit JSON, a SARIF report, and an SBOM at once.

Outputs that post back to the provider (not files):

PBOM & CycloneDX

--pbom writes Plumber’s native, pipeline-specific inventory; --pbom-cyclonedx writes the same inventory as a CycloneDX 1.5 SBOM, compatible with tools like Grype, Trivy, and Dependency-Track. With the GitLab CI component, the CycloneDX file is automatically uploaded as a GitLab CycloneDX report.

JSON report structure

plumber analyze --output report.json writes a single JSON object. The keys below are stable for scripting; additional keys may be added in minor versions, existing keys will not be renamed or removed.

Top-level keys

Per-control *Result block

Each *Result block has the same baseline shape. Some controls add a few control-specific keys on top.

issues entry

Each entry describes one finding. Beyond the keys below, a rule adds its own structured payload naming what it flagged (uses for an action reference, tag and link for a container image, branchName, variableName, and so on).

To track a control across runs (history, remediation state, trend dashboards), key on the pair controlName + status: controlName is the check’s stable identity and status its verdict for that run. To track one individual finding within a control, use its fingerprint.

partialControls entry

When non-empty, each entry has the shape shown in the GitHub authentication section: control, reason, affectedBranches (when relevant), remediation. CI gates should fail loud when this array contains anything, even if passed reads true.

CSV columns

plumber analyze --csv results.csv writes one header row followed by every control in the catalog, not just the ones that found something. A control that passed, was skipped, or could not be evaluated gets a single summary row; a control that failed gets one row per finding. Non-failing controls are listed first, then the failing ones with their findings, so the clean posture reads at the top and the problems are grouped at the bottom.

Because every control is present on every run, a clean scan is a full report rather than an empty file, and an empty code column never has to be interpreted as “compliant”.

Column order is fixed and will not change:

To build per-control history, group on controlName and read status for each run. To follow one specific finding, use fingerprint.

Codeless findings (none currently exist) are skipped, since they have no stable identifier to report against.

Finding fingerprint

Every finding carries a fingerprint: a short, stable identifier for that one finding, so you can tell across runs whether it is the same problem, a new one, or resolved. controlName answers “how is this check doing”; fingerprint answers “is this particular finding still there”.

The same value appears in every format, so a finding can be correlated between them:

It is derived from what the finding is about rather than how it is worded: the issue code, the file, the job it sits in when there is one, the subject the rule flagged (an action reference, a branch, an image, a variable, an include path), and the workflow step name when there is one. Line numbers are deliberately excluded, so editing unrelated code above a finding does not change its fingerprint.

For the exact recipe, the subject-key priority, and worked examples of each case (a rule with a structured subject, the same action used twice in one job, the message fallback, repository-level findings), see docs/FINGERPRINT.md.

The identity block

The fingerprint is a hash, so it cannot tell a consumer which fields it was built from. Each issue entry in the JSON report therefore also carries an identity block: the selected field set itself, as data.

Every identity carries code, file, and job, then exactly one subject key naming what the rule flagged, and finally step when the workflow resolved one. Only the single most specific subject key appears, not every field in the finding’s payload: the recipe walks a fixed priority list and takes the first key the finding carries.

"identity": {
  "version": 2,
  "subjectFromMessage": false,
  "fields": [
    { "key": "code", "value": "ISSUE-701" },
    { "key": "file", "value": ".github/workflows/build.yaml" },
    { "key": "job",  "value": "build/compile" },
    { "key": "uses", "value": "some-org/some-action@master" },
    { "key": "step", "value": "Build image" }
  ]
}

The fields, in order:

Everything else in a finding’s payload is deliberately not part of identity: line and url move whenever unrelated code above the finding is edited, advisories grows as CVEs are published, latestVersion moves on any upstream release, and status fields track current settings rather than identity. Any of those in the field set would make an unchanged finding look new.

A platform ingesting Plumber reports should store the identity fields the CLI selected instead of re-deriving them, so the two sides can never disagree about which findings are the same finding. Go consumers can use the public finding/identity package (identity.Of, identity.Fingerprint, identity.FromMap) to work with the same recipe programmatically.