Global flags apply to every subcommand. They can be placed before or after the subcommand name.
Output and formatting
Flag
Values
Default
Env variable
Description
--format
human, json, sarif
human
PYDEPGATE_FORMAT
Output format
--color
auto, always, never
auto
PYDEPGATE_COLOR
ANSI color control. auto emits color when stdout is a TTY. always forces color through pipes. never disables color.
--no-color
PYDEPGATE_NO_COLOR, NO_COLOR
Alias for --color=never. Kept for compatibility.
--no-map
false
PYDEPGATE_NO_MAP
Suppress the finding-distribution map in human output
Severity and exit behavior
Flag
Values
Default
Env variable
Description
--min-severity
info, low, medium, high, critical
info
PYDEPGATE_MIN_SEVERITY
Suppress findings below this severity in output
--ci
false
PYDEPGATE_CI
CI mode: if --format is not set, forces json; if --color is auto, forces never. Does not change --min-severity.
--strict-exit
false
PYDEPGATE_STRICT_EXIT
Compute exit code from all findings regardless of --min-severity. Use when you want filtered display but unfiltered exit behavior.
Rules
Flag
Values
Default
Env variable
Description
--rules-file
path
auto-discover
PYDEPGATE_RULES_FILE
Path to a .gate rules file. Auto-discovery checks ./pydepgate.gate then ~/.config/pydepgate/pydepgate.gate.
Engine parallelism
Flag
Values
Default
Env variable
Description
--workers
integer or auto
unset (serial)
PYDEPGATE_WORKERS
Worker count for the per-file scan pool. auto resolves to CPU count (cgroup-aware on Linux via sched_getaffinity, falling back to cpu_count elsewhere). Below 1000 files in scope, the pool is suppressed and execution runs serial regardless of this setting. Warns at 2x available CPUs, severe warning at 4x, refuses with exit code 3 at 8x.
--force-parallel
false
PYDEPGATE_FORCE_PARALLEL
Bypass the 1000-file threshold and run parallel regardless of file count. Useful when the operator knows parallel is the right choice for the workload, or for testing the parallel path in CI without a large fixture.
Payload peek
Flag
Values
Default
Env variable
Description
--peek
false
PYDEPGATE_PEEK
Enable the payload-peek enricher. Required for --decode-payload-depth to produce output.
--peek-depth
integer
3
PYDEPGATE_PEEK_DEPTH
Maximum decode depth in the enricher pass. Floor 1, ceiling 10.
--peek-budget
integer (bytes)
524288 (512 KB)
PYDEPGATE_PEEK_BUDGET
Cumulative byte budget across all unwrap layers. Floor 1024.
--peek-min-length
integer
1024
PYDEPGATE_PEEK_MIN_LENGTH
Minimum literal length, in bytes, before the enricher attempts to decode it. Floor 16.
--peek-chain
false
PYDEPGATE_PEEK_CHAIN
Print verbose per-layer hex dumps in the enricher output
Decode pipeline
Flag
Values
Default
Env variable
Description
--decode-payload-depth
integer
unset (decode disabled)
PYDEPGATE_DECODE_PAYLOAD_DEPTH
Maximum recursion depth for the decode pipeline. Must be in [1, 8] when enabled. Requires --peek.
--decode-location
path
./decoded/
PYDEPGATE_DECODE_LOCATION
Output directory for decode reports, sidecars, and archives. Created if missing.
--decode-format
text, json
text
PYDEPGATE_DECODE_FORMAT
Format of the decode-pipeline report. text for a human-readable tree; json for structured downstream tooling.
Use STORED compression instead of DEFLATE for the full mode archive. Slightly larger archive but bypasses zlib entirely. Useful when byte-verifiable archive contents matter.
SARIF
Flag
Values
Default
Env variable
Description
--sarif-srcroot
path
PYDEPGATE_SARIF_SRCROOT
Source root for SARIF PROJECTROOT URI base. Only meaningful with --format sarif. Emits a warning if set with other formats.
Precedence
When a flag is set via both an environment variable and the command line, the command line wins. When a flag is set via both an environment variable and the default, the environment variable wins.
explicit CLI flag > environment variable > built-in default
Tab completion
Shell completion is available for bash, zsh, and fish. See completions for setup instructions.