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.

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 always writes the full default template with comments; init writes a short file shaped by your answers.

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.

plumber config generate [flags]

Examples:

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

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.

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 compliance reads 100.