🛠️ CLI Reference

Complete reference for all Guardy CLI commands, global options, and subcommands.

Global Options

These options work with all commands:

guardy [GLOBAL OPTIONS] <COMMAND>

Option	Short	Description
`--directory <DIR>`	`-C`	Run as if started in `<DIR>` instead of current directory
`--verbose`	`-v`	Increase verbosity (can be repeated: `-vv`, `-vvv`)
`--quiet`	`-q`	Suppress non-error output
`--config <FILE>`		Use custom configuration file
`--recursive-config`		Enable/disable recursive config loading from parent directories
`--help`	`-h`	Print help information
`--version`	`-V`	Print version information

Example: guardy -C /path/to/project scan src/

Commands Overview

Command	Description
`hooks`	Git hooks management (install, uninstall, run, status)
`scan`	Scan files or directories for secrets and credentials
`sync`	Protected file synchronization from remote repositories
`config`	Configuration management and validation
`status`	Show current installation and configuration status
`version`	Show version information

`hooks`

Manage git hooks in your repository.

Usage

guardy hooks [OPTIONS] <SUBCOMMAND>

Global Hook Options

Option	Description	Default
`--skip-all`	Skip all hooks globally	`false`
`--parallel`	Run hooks in parallel	`true`

Subcommands

`hooks install`

Install git hooks into the current repository.

guardy hooks install [OPTIONS]

Options:

--hooks <HOOKS> - Specify which hooks to install (comma-separated, default: all)
--force - Overwrite existing hooks

Examples:

# Install all configured hooks
guardy hooks install

# Install only pre-commit and pre-push
guardy hooks install --hooks pre-commit,pre-push

# Overwrite existing hooks
guardy hooks install --force

`hooks uninstall`

Uninstall git hooks from the current repository.

guardy hooks uninstall [OPTIONS]

Options:

--hooks <HOOKS> - Specify which hooks to uninstall (default: all guardy hooks)
--yes / -y - Skip confirmation prompt

Examples:

# Uninstall all guardy hooks (with confirmation)
guardy hooks uninstall

# Uninstall without confirmation
guardy hooks uninstall --yes

# Uninstall specific hooks
guardy hooks uninstall --hooks pre-commit,commit-msg

`hooks run`

Manually run a specific hook for testing.

guardy hooks run <HOOK_NAME> [ARGS...]

Arguments:

<HOOK_NAME> - Name of hook to run (pre-commit, commit-msg, pre-push, etc.)
[ARGS...] - Additional arguments to pass to the hook

Examples:

# Test pre-commit hook
guardy hooks run pre-commit

# Test commit-msg hook with message file
guardy hooks run commit-msg .git/COMMIT_EDITMSG

# Test pre-push hook
guardy hooks run pre-push origin refs/heads/main

`hooks status`

Show hooks installation and configuration status.

guardy hooks status

Displays:

Installed hooks and their locations
Hook configuration details
Enabled built-in actions

`hooks dump`

Dump hooks configuration in various formats.

guardy hooks dump [OPTIONS]

Options:

--format <FORMAT> - Output format (json, yaml, toml)
--lefthook - Output lefthook-compatible configuration

Examples:

# Dump as JSON
guardy hooks dump --format json

# Export to lefthook format
guardy hooks dump --lefthook

`hooks validate`

Validate hooks configuration for errors.

guardy hooks validate

`scan`

Scan files or directories for secrets and credentials.

Usage

guardy scan [OPTIONS] [PATH...]

Arguments

[PATH...] - Files or directories to scan (default: current directory)

Scanning Options

Option	Description	Default
`--include-binary`	Scan binary files	`false`
`--max-file-size <MB>`	Maximum file size to scan in MB	`10`
`--follow-symlinks`	Follow symbolic links	`false`
`--stats`	Show statistics after scanning	`false`

Detection Options

Option	Description	Default
`--no-entropy`	Disable entropy analysis (faster, less accurate)	enabled
`--entropy-threshold <NUM>`	Set entropy threshold	`0.00001`
`--custom-patterns <PATTERNS>`	Custom secret patterns to add (regex, comma-separated)	-
`--list-patterns`	List all available secret detection patterns and exit	-

Filtering Options

Option	Description
`--ignore-patterns <PATTERNS>`	Additional patterns to ignore (regex, comma-separated)
`--ignore-paths <PATHS>`	Additional paths to ignore (glob patterns, comma-separated)
`--ignore-comments <PATTERNS>`	Additional comment patterns to ignore

Output Options

Option	Description	Default
`--format <FORMAT>`	Output format: text, json, csv, files	`text`
`--count-only`	Only count matches, don't show details	`false`
`--show-content`	Show matched text content (potentially sensitive)	`false`
`--show`	Show detailed finding information (gitleaks-style)	`false`
`--sensitive`	Show actual secret values (use with caution)	`false`
`--report <FILES>`	Generate reports in specified formats (comma-separated filenames)	-
`--plain`	Use plain output (disable colors and emojis)	`false`

Performance Options

Option	Description	Default
`--mode <MODE>`	Processing mode: auto, parallel, sequential	`auto`
`--tty`	Enable TTY progress bars	`true`

Examples

# Scan current directory
guardy scan

# Scan specific files
guardy scan src/config.js src/database.ts

# Scan directory with stats
guardy scan --stats ./src

# Generate JSON report
guardy scan --report results.json src/

# Multiple report formats
guardy scan --report results.json,report.html src/

# Add custom secret patterns
guardy scan --custom-patterns 'MY_SECRET_[A-Z0-9]+' src/

# Ignore specific patterns
guardy scan --ignore-patterns 'test_key_.*' src/

# CI-friendly output (no colors, JSON format)
guardy scan --plain --format json src/

# Count only for quick check
guardy scan --count-only src/

`sync`

Protected file synchronization from remote repositories.

Usage

guardy sync [GLOBAL OPTIONS] [SUBCOMMAND]

Global Sync Options

Option	Description	Default
`--force`	Force update without prompts	`false`
`--repo <URL>`	Bootstrap from specific repository	-
`--version <REF>`	Specific version to sync (tag, branch, commit)	-
`--source-path <PATH>`	Source directory in remote repository	`.`
`--dest-path <PATH>`	Destination directory for synced files	`.`
`--include <PATTERNS>`	Include patterns (can be repeated)	-
`--exclude <PATTERNS>`	Exclude patterns (can be repeated)	-

Subcommands

`sync status`

Show sync status and configuration.

guardy sync status

Displays:

Configured sync repositories
Local file status
Last sync information

`sync update`

Update files from configured repositories (interactive by default).

guardy sync update [OPTIONS]

Options:

--force - Force update without interactive prompts
--repo <URL> - Bootstrap from specific repository (initial setup)
--version <REF> - Specific version to sync
--source-path <PATH> - Source directory in remote repository
--dest-path <PATH> - Destination directory
--include <PATTERNS> - Include patterns (can be repeated)
--exclude <PATTERNS> - Exclude patterns (can be repeated)

Examples:

# Interactive update (review changes)
guardy sync update

# Force update all configured repos
guardy sync update --force

# Initial setup from repository
guardy sync update --repo https://gitlab.com/org/dotfiles.git

# Sync specific paths only
guardy sync update --include '*.yaml' --exclude 'secrets/*'

`sync diff`

Show differences between local and remote files.

guardy sync diff

Displays what has drifted between local and remote versions.

`config`

Configuration management.

Usage

guardy config <SUBCOMMAND>

Subcommands

`config show`

Display current merged configuration from all sources (files, environment variables, CLI arguments).

guardy config show [OPTIONS]

Options:

--format <FORMAT> / -f - Output format: json, yaml, or toml (default: yaml)

Examples:

# Show config in YAML format (default)
guardy config show

# Show config in JSON format
guardy config show --format json

# Show config in TOML format
guardy config show -f toml

`status`

Show installation and configuration status.

Usage

guardy status [OPTIONS]

Options

Option	Description
`--show-config`	Include configuration in status output
`--format <FORMAT>`	Output format: `text`, `json`, or `yaml`
`--compact`	Compact output (less detailed)

Displays:

Git repository status and current branch
Installed hooks (managed by guardy)
Scanner configuration (max file size, binary files, entropy analysis)
Pattern library count

Examples:

# Show basic status
guardy status

# Show status with configuration details
guardy status --show-config

# Compact status output
guardy status --compact

Default command: When run without arguments in a git repository, Guardy shows status automatically.

`version`

Show version information.

Usage

guardy version [OPTIONS]

Options

Option	Short	Description
`--detailed`	`-d`	Show detailed version information including branch, Rust edition, and dependencies
`--build-info`	`-b`	Show comprehensive build information (target architecture, rustc version, build timestamp, etc.)

Examples:

# Show basic version
guardy version

# Show detailed version info
guardy version --detailed

# Show comprehensive build information
guardy version --build-info

Displays:

Guardy version and git commit SHA (always shown)
With --detailed: Branch, Rust edition, key dependencies, repository info
With --build-info: Target architecture, rustc version, build timestamp, package details

Exit Codes

Guardy uses standard exit codes to indicate execution status:

Code	Meaning
`0`	Success - no secrets found, hooks passed, operation completed
`1`	Hook failed - secrets found, tests failed, validation errors
`2`	Configuration error - invalid config, missing required values
`3`	Command execution error - runtime errors, file I/O failures

Examples

# Check exit code in scripts
guardy scan src/
if [ $? -eq 0 ]; then
    echo "No secrets found"
else
    echo "Secrets detected!"
    exit 1
fi

Environment Variables

See Configuration for complete list of environment variables that override config file settings.

Common environment variables:

# General
export GUARDY_VERBOSE=2
export GUARDY_CONFIG=~/.config/guardy/custom.yaml

# Hooks
export GUARDY_HOOKS_SKIP_ALL=true
export GUARDY_HOOKS_PARALLEL=false

# Scanner
export GUARDY_SCAN_MAX_THREADS=8
export GUARDY_SCAN_MAX_FILE_SIZE_MB=20

# Sync
export GUARDY_SYNC_FORCE=true
export GUARDY_SYNC_AUTO_UPDATE=false

Common Workflows

Development Workflow

# Initialize project
cd my-project
guardy hooks install

# Test hooks before committing
guardy hooks run pre-commit

# Check what would be scanned
guardy scan --count-only src/

# Scan with detailed output
guardy scan --show --stats src/

CI/CD Integration

# CI-friendly scan
guardy scan --plain --format json --report results.json src/

# Exit with error code if secrets found
guardy scan src/ || exit 1

# Generate multiple report formats
guardy scan --report results.json,report.html,report.csv src/

Configuration Management

# Show current config in YAML format
guardy config show

# Show config in JSON format
guardy config show --format json

# Validate hooks configuration
guardy hooks validate

# Export hooks config to lefthook
guardy hooks dump --lefthook > lefthook.yml

Debugging

# Verbose output
guardy -vv scan src/

# Run from different directory
guardy -C /path/to/project hooks run pre-commit

# Check status
guardy status

# List available patterns
guardy scan --list-patterns

🛠️ CLI Reference

On this page