CLI

Active contributors: Alex Goodman, Christopher Phillips, Keith Zantow, Will Murphy

Purpose

The grype CLI is the only deployable artifact in this repository. It catalogues packages from a target, looks them up against a local vulnerability database, applies user-defined ignore rules and VEX documents, and renders the results in one of several formats.

Directory layout

cmd/grype/
├── main.go              # binary entry point
├── internal/            # build-time identification (version, gitCommit, ...)
└── cli/
    ├── cli.go           # clio.Application wiring
    ├── commands/        # cobra commands: root, db, explain, completion, update
    ├── options/         # option structs for each subcommand
    └── ui/              # bubbletea-based progress UI

Command tree

Command	File	Purpose
grype <input>	cmd/grype/cli/commands/root.go	Default scan. Accepts an image, directory, file, SBOM, PURL, or CPE.
grype db check	db_check.go	Compare local DB to remote listing; exits 100 if upgrade available.
grype db delete	db_delete.go	Remove the local DB.
grype db diff	db_diff.go	Diff two database archives.
grype db import	db_import.go	Install a DB from a local archive.
grype db list	db_list.go	List candidate DBs from the listing file.
grype db providers	db_providers.go	Show the data providers (NVD, distro feeds, GitHub, ...) backing the current DB.
grype db search	db_search.go	Subcommands for searching packages and vulnerabilities.
grype db search vuln	db_search_vuln.go	Look up a vulnerability ID directly.
grype db status	db_status.go	Print location, schema, and validity of the local DB.
grype db update	db_update.go	Refresh the local DB.
grype explain	explain.go	Produce a per-vulnerability rationale from a JSON report on stdin.
grype completion	completion.go	Generate shell completion scripts.
grype version	(provided by clio.VersionCommand)	Print version, including bundled syft and DB schema.
grype config	(provided by clio.ConfigCommand)	Show resolved configuration (after CLI flags + env + YAML).

Key abstractions

Symbol	Where	Description
cli.Application(id)	cmd/grype/cli/cli.go	Build the top-level clio.Application with options, UI, bus, and post-runs wired.
commands.Root(app)	cmd/grype/cli/commands/root.go	Build the cobra root command and runGrype invocation.
runGrype(ctx, app, opts, userInput)	same	Orchestrates the full scan: parallel DB load + cataloging, matching, filtering, presenting.
options.Grype	cmd/grype/cli/options/grype.go	The CLI option struct (~280 fields across all flags).
ui.New(...)	cmd/grype/cli/ui/	Bubbletea-based progress UI. Falls back to ui.None outside a tty.
SetupConfig(id)	cmd/grype/cli/cli.go	Wires global config flag (-c), logging flags, UI selection, exit-code mapping.

How it works

sequenceDiagram
    participant User
    participant main as cmd/grype/main.go
    participant cli as cli.Application
    participant root as commands.Root
    participant runGrype
    participant lib as grype.LoadVulnerabilityDB
    participant pkg as pkg.Provide
    participant matcher as VulnerabilityMatcher
    participant present as presenter

    User->>main: grype alpine:latest
    main->>cli: cli.Application(id)
    cli->>root: SetupRootCommand(opts)
    User->>root: cobra parses args
    root->>runGrype: runGrype(ctx, app, opts, "alpine:latest")
    par parallel
        runGrype->>lib: load DB
    and
        runGrype->>pkg: catalog packages
    end
    lib-->>runGrype: vulnerability.Provider
    pkg-->>runGrype: []pkg.Package + pkg.Context
    runGrype->>matcher: FindMatches(packages, ctx)
    matcher-->>runGrype: matches + ignored
    runGrype->>present: write(presenter.Config)
    present-->>User: stdout / file

The parallel(...) helper in cmd/grype/cli/commands/root.go runs three goroutines: one for DB load, one for package cataloging, and one for the version-update check. Errors from any of them are collected before matching begins.

Exit codes

Wired in cmd/grype/cli/cli.go::SetupConfig::WithMapExitCode:

Code	Meaning
0	Scan succeeded; nothing exceeded the fail-on threshold.
1	Generic error (DB load, cataloging, presenter).
2	At least one match met or exceeded --fail-on (grypeerr.ErrAboveSeverityThreshold).
100	grype db check found that an upgrade is available (grypeerr.ErrDBUpgradeAvailable).

Configuration

The CLI uses clio + fangs for layered configuration. Sources, in priority order:

1. CLI flags
2. Environment variables (GRYPE_*)
3. Config file (-c <path>, otherwise default search: ./.grype.yaml, ~/.grype.yaml, etc.)
4. Defaults from options.DefaultGrype()

grype config prints the resolved configuration after merging all sources — useful when debugging unexpected matcher behavior.

UI selection

SetupConfig::WithUIConstructor chooses between two UIs:

• ui.New — bubbletea-driven progress with multiple panels for syft and grype. Selected when stdin is a tty and --quiet is not set.
• ui.None — no rendering. Used in CI, when piping output, or when --quiet is set.

The CI environment variable is intentionally hidden from lipgloss/termenv via environWithoutCI so users who want color rendering in CI can opt in (see Fun facts).

Integration points

• clio — anchore/clio wires logging, config, bus, and redact store and provides initialization hooks. cli.go::SetupConfig::WithInitializers is where Grype hoists these into its internal singletons (internal/log, internal/bus, internal/redact).
• stereoscope and syft — cli.go calls stereoscope.SetBus, syft.SetBus, syft.SetLogger, and stereoscope.SetLogger so library logs flow into the same handler. WithPostRuns calls stereoscope.Cleanup() to clean temp dirs.
• bubbletea / bubbly — UI components in cmd/grype/cli/ui/.
• cobra — command tree.

Entry points for modification

• New flag → add to the relevant struct in cmd/grype/cli/options/, set its default in the Default* function, and consume it in runGrype or the relevant subcommand.
• New subcommand → create a file under cmd/grype/cli/commands/, define a cobra.Command constructor, and register it in cli.go::create (rootCmd.AddCommand(...)).
• New exit code → add a sentinel to grype/grypeerr/ and extend WithMapExitCode in cli.go.
• New UI panel → modify cmd/grype/cli/ui/handler.go and the bubbletea model.