Overview

The GitGuardian CLI, ggshield, provides security guardrails at every stage of your Software Development Lifecycle (SDLC).
Find and fix 600+ types of hardcoded secrets.

ggshield [COMMAND] [SUBCOMMAND] [OPTIONS]

Core commands

• ggshield auth
• ggshield secret scan
• ggshield machine setup
• ggshield honeytoken create

Additional commands

• ggshield secret ignore
• ggshield api-status
• ggshield install
• ggshield quota

Commands that require git

The following commands need the git executable to be installed and available in PATH.

• ggshield secret scan changes
• ggshield secret scan ci
• ggshield secret scan commit-range
• ggshield secret scan pre-commit
• ggshield secret scan pre-push
• ggshield secret scan pre-receive
• ggshield secret scan repo

Git is optional for the following commands, which need it only for some features. Every other command works without git.

• ggshield install: Git hook types require it; AI coding assistant hook types do not.
• ggshield machine doctor: Without it the git hook checks are reported as skipped and do not affect the exit code.
• ggshield machine setup: It is only needed for the git hooks; without it that step is skipped with a warning.
• ggshield secret scan path: It is only needed with --use-gitignore.

Options

• -h, --help: Show this message and exit.
• --insecure: Skip all certificate verification checks. WARNING: this option makes the transfer insecure.
• -c, --config-path <FILE>: set a custom config file. Ignores local and global config files.
• -v, --verbose: Verbose display mode.
• --version: Show the version.
• --check-for-updates / --no-check-for-updates: After executing commands, check or not if a new version of ggshield is available.
• --log-file <FILE>: Send log output to FILE. Use - to redirect to stderr instead.
• --debug: Show debug information.

JSON outputs

Many ggshield commands come with a --json option to output a JSON document. The format of these JSON outputs are documented as JSON schemas in the doc/schemas folder of ggshield repository.

Exit codes

Depending on the outcome of the command, ggshield exit code will be one of these:

Code	Meaning
0	No problem found. If the command was a scan, it ran successfully and did not find any issue to report.
1	The command ran successfully, but it found issues to report. For example, a secret scan command found leaked secrets.
2	Usage error: the command did not receive the parameters it expected.
3	Authentication error: the command tried to log on a server, but the server rejected it.
128	Unexpected error.