Open Source CLI

The Plumber CLI analyzes GitLab CI/CD pipelines and GitHub Actions workflows from the command line, checking them against a single .plumber.yaml policy. Both providers share the same engine (OPA / Rego), the same output format, and the same exit codes: write a policy once, scan both.

Install the CLI first, then pick the page for the platform you scan. Each provider page is a complete, self-contained guide (authentication, running a scan, the control catalog, the issues, and configuration):

This page is the shared reference: the provider-agnostic command set and the output formats (PBOM, CycloneDX, JSON shape).

This is useful for local testing, CI/CD integration, security-team audits, or automated compliance checks across either platform.

Command Reference

The full CLI reference. The analyze command takes provider-specific flags and tokens; the config commands, plumber explain, and exit codes behave identically for both providers.

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 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

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

Pipeline Bill of Materials (PBOM) & CycloneDX

Plumber can generate a PBOM: a complete inventory of all dependencies in your CI/CD pipeline (container images, components, templates, includes). Two formats are available:

Native PBOM (detailed, pipeline-specific):

plumber analyze --pbom pbom.json

CycloneDX SBOM (standard format for security tool integration):

plumber analyze --pbom-cyclonedx pipeline-sbom.json

The CycloneDX output follows the CycloneDX 1.5 specification and is compatible with tools like Grype, Trivy, and Dependency-Track. When using the GitLab CI component, the CycloneDX file is automatically uploaded as a GitLab CycloneDX report.

Output JSON shape

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 auth section above: control, reason, affectedBranches (when relevant), remediation. CI gates should fail loud when this array contains anything, even if compliance reads 100.