cmd

Active contributors: Zachary Rice, Richard Gomez

Purpose

The cmd/ package wires Gitleaks's command-line interface using Cobra. It owns the persistent flag set, the construction of detect.Detector from CLI flags, the wiring of report.Reporter for output, and the lifecycle of the diagnostics manager.

Directory layout

cmd/
├── root.go            # rootCmd + persistent flags + Detector/Config helpers
├── git.go             # `gitleaks git`
├── directory.go       # `gitleaks dir` (aliases: file, directory)
├── stdin.go           # `gitleaks stdin`
├── detect.go          # legacy `detect` (hidden)
├── protect.go         # legacy `protect` (hidden)
├── version.go         # `gitleaks version`
├── diagnostics.go     # --diagnostics CPU/mem/trace/http manager
├── scm/scm.go         # SCM platform enum
└── generate/          # `go generate` rule compiler (offline tool)

Key abstractions

Symbol	File	Description
rootCmd	cmd/root.go	The Cobra root with persistent flags
Execute()	cmd/root.go	Public entry point called from main.go; maps unknown-flag errors to exit 126
Config(cmd)	cmd/root.go	Unmarshals Viper into a config.ViperConfig and translates to config.Config
Detector(cmd, cfg, source)	cmd/root.go	Builds a fully-flagged detect.Detector (entropy, redact, allowlist paths, reporter, …)
findingSummaryAndExit	cmd/root.go	Writes the report, prints the totals, sets the exit code
gitCmd, directoryCmd, stdInCmd, detectCmd, protectCmd, versionCmd	per file	The Cobra subcommands
DiagnosticsManager	cmd/diagnostics.go	Coordinates CPU/mem/trace pprof and the HTTP pprof endpoint
scm.Platform, scm.PlatformFromString	cmd/scm/scm.go	SCM platform enum used for finding links

How it works

graph TD
    Main["main.go: cmd.Execute()"] --> Root[rootCmd]
    Root -->|gitleaks git| GitC[gitCmd.Run]
    Root -->|gitleaks dir| DirC[directoryCmd.Run]
    Root -->|gitleaks stdin| StdC[stdInCmd.Run]
    GitC --> InitC[initConfig + initDiagnostics]
    DirC --> InitC
    StdC --> InitC
    InitC --> Build["Config(cmd)<br/>Detector(cmd, cfg, source)"]
    Build --> SrcG[sources.Git or<br/>sources.Files or<br/>sources.File]
    SrcG --> Run[detector.DetectSource]
    Run --> Out[findingSummaryAndExit]
    Out -->|writer| Report[report.Reporter]
    Out -->|exit code| Shell

The three live entry points (git, dir, stdin) and the two hidden legacy ones (detect, protect) all converge on the same Detector(cmd, cfg, source) constructor and the same findingSummaryAndExit finalizer. The differences are purely in which sources.Source they instantiate.

Persistent flags

init() in cmd/root.go registers the flags every command shares:

Flag	Default	Notes
-c, --config	empty	Overrides every other config-resolution path
--exit-code	1	Exit code when leaks are found
-r, --report-path	empty	Output file (or - for stdout)
-f, --report-format	inferred	json/csv/junit/sarif/template
--report-template	empty	Path to a Go template (forces format=template)
-b, --baseline-path	empty	JSON baseline to subtract
-l, --log-level	info	trace/debug/info/warn/error/fatal
-v, --verbose	false	Pretty-print findings to stdout
--no-color	false	Disable lipgloss colors
--max-target-megabytes	0	Skip individual files larger than this
--ignore-gitleaks-allow	false	Don't honor gitleaks:allow markers
--redact	0 (100 with no value)	Percentage redaction
--no-banner	false	Suppress ASCII banner on stderr
--enable-rule	none	Whitelist of rule IDs to apply
-i, --gitleaks-ignore-path	.	Where to find .gitleaksignore
--max-decode-depth	5	Recursive base64/hex/percent decoding cap
--max-archive-depth	0	Archive recursion cap (off by default)
--timeout	0	Whole-command timeout in seconds
--diagnostics	empty	cpu,mem,trace or http
--diagnostics-dir	empty	Where to drop pprof/trace outputs

Config resolution

initConfig(source) in cmd/root.go resolves the active config in this order:

1. --config / -c flag
2. GITLEAKS_CONFIG env var (path)
3. GITLEAKS_CONFIG_TOML env var (file content)
4. <source>/.gitleaks.toml
5. The embedded default (config/gitleaks.toml)

If source is a file (not a directory), only step 5 applies — there's nothing to look at relative to a single file path.

Diagnostics manager

cmd/diagnostics.go defines DiagnosticsManager. It's started before any source is iterated and stopped at the start of findingSummaryAndExit. The manager supports four modes:

• cpu — runtime/pprof CPU profile written to cpu.pprof
• mem — pprof.WriteHeapProfile written to mem.pprof after a forced GC
• trace — runtime/trace written to trace.out
• http — starts net/http/pprof on localhost:6060. Mutually exclusive with the others.

Integration points

• main.go is one line: cmd.Execute() after wiring an interrupt-signal handler.
• detect/ is constructed from CLI flags in Detector(cmd, cfg, source).
• config/ is loaded by initConfig and translated by Config(cmd).
• sources/ is selected by each subcommand based on its mode.
• report/ is selected by --report-format and wired into the detector.
• cmd/scm/ parses --platform into a scm.Platform for finding-link rendering.

Entry points for modification

If you're adding a new CLI flag, the change usually lives entirely in cmd/root.go's init() plus the Detector(...) constructor that pulls it off cmd.Flags(). If the flag's effect needs to be visible deeper than the detector (e.g., inside a source), thread it through the relevant struct in sources/.

If you're adding a new subcommand, copy the shape of cmd/stdin.go — it's the smallest of the three live commands. Register it via init() and add a *cobra.Command with a Run that calls initConfig, initDiagnostics, builds a detector, drives a source, and ends with findingSummaryAndExit.

If you're touching the legacy detect/protect commands, beware: they remain hidden but still flow through real code paths; users are still on them. The header comment in cmd/detect.go documents the migration mapping.