Configuration

This page is the complete reference for configuring the HoundDog.ai code scanner: its subcommands, command-line options, environment variables, configuration file, and ignore files.

Subcommands

Command	Description
hounddog scan [path]	Scan a file or directory (defaults to the current directory).
hounddog data-elements list	List the data elements the scanner detects. Aliases: show, ls.
hounddog data-sinks list	List the data sinks the scanner detects. Aliases: show, ls.
hounddog info	Show details about the CLI, including version, environment, and whether an API key is configured.
hounddog mcp [path]	Run an MCP server that serves scan insights to AI coding agents over stdio.

Run hounddog <subcommand> --help to see the options for each subcommand. Browsable, always-current catalogs of the built-in rules are published on GitHub: data-elements.md and data-sinks.md.

Scan Options

Options for hounddog scan:

Option	Description
--include-data-element <ID>	Data element IDs to include in scan results (comma-separated or repeated).
--exclude-data-element <ID>	Data element IDs to exclude from scan results.
--include-data-sink <ID>	Data sink IDs to include in scan results.
--exclude-data-sink <ID>	Data sink IDs to exclude from scan results.
--include-data-sink-tag <TAG>	Data sink tags to include: database, blob-storage, browser, third-party, intermediary, payment, ai, queue, orm, cache.
--exclude-data-sink-tag <TAG>	Data sink tags to exclude (same tag set).
--severity <SEV>	Only show dataflows with the given severities: critical, medium, low, info, or all (default: all). Safe dataflows carry the info severity, so --severity=critical,medium,low hides them.
--fail-severity-threshold <SEV>	Exit with code 1 if a risky dataflow at or above the given severity is found: critical, medium, low, or info. See CI/CD Pipelines.
--output-format <FORMAT>	Scan results output format (default: console). See Scan Results.
--output-path <PATH>	Scan results output file path.
--trace	Display step-by-step dataflow traces.
--full-path	Display absolute file paths instead of repository-relative ones.
--no-git	Ignore .git metadata (branch, commit, remote URL).
--no-file-stats	Do not display the file statistics table.
--no-tips	Do not display tips in console output.
--no-ai-review	Disable the AI-powered dataflow review for this run.
--no-cache	Ignore locally stored scan results and force a full scan. See Local Scan State.
--scm <ID>	Override the auto-detected source control platform: github-cloud, github-enterprise-cloud, github-enterprise-server, gitlab-cloud, gitlab-self-managed, bitbucket-cloud, bitbucket-data-center, azure-devops-cloud, azure-devops-server.
--ci <ID>	Override the auto-detected CI system. See CI/CD Pipelines for the supported systems.

The Fail-Severity Gate

--fail-severity-threshold turns the scanner into a CI quality gate: when a risky dataflow at or above the threshold is found, the scan exits with code 1 and the message Found a risky dataflow with <severity> severity or higher. Stopping. The gate runs last — after all outputs and the results upload — so reports and the Cloud Platform always receive the results even when the build fails. Dataflows excluded by your rules or marked as false positives by the AI review never fail the build. Without this flag, the scanner always exits with code 0 unless an error occurs.

Caution

The --severity display filter also applies to the gate: a dataflow whose severity is filtered out of the output cannot fail the build. Do not combine --severity with --fail-severity-threshold in CI unless you intend to narrow the gate.

Global Options

hounddog --version prints the scanner version. It is accepted only at the top level, not on subcommands.

These options work with every subcommand:

Option	Description
--no-color	Disable colored console output.
--debug	Enable debug logging and full error backtraces.
--no-cloud	Ignore the HoundDog.ai Cloud Platform entirely and use local settings only. Alias: --local.
--no-cloud-download	Do not download scan settings from the Cloud Platform.
--no-cloud-upload	Do not upload scan results to the Cloud Platform.

Environment Variables

Variable	Description
HOUNDDOG_API_KEY	Your API key. Unlocks paid features and enables cloud rules and result uploads.
HOUNDDOG_ORG_ID	Selects the organization when your user account belongs to multiple HoundDog.ai organizations.
HOUNDDOG_ENV	Target environment: prod (default) or self-hosted. See Scanner Setup for Self-Hosted.
HOUNDDOG_URL	The URL of your self-hosted HoundDog.ai deployment (only used when HOUNDDOG_ENV=self-hosted).
HOUNDDOG_GIT_BRANCH	Override the git branch name when auto-detection fails (for example, detached HEAD checkouts in CI).
HOUNDDOG_GIT_COMMIT	Override the git commit SHA when auto-detection fails.
HOUNDDOG_GIT_USERNAME / HOUNDDOG_GIT_PASSWORD	Git credentials for repositories that require authentication.
HOUNDDOG_DEBUG	Enable debug logging (same as --debug).
HOUNDDOG_AI_PROVIDER, HOUNDDOG_AI_MODEL_ID, HOUNDDOG_AI_API_KEY, HOUNDDOG_AI_BASE_URL, HOUNDDOG_AI_AWS_REGION	Configure the AI-powered dataflow review.

Configuration File

The scanner reads a configuration file at:

• Linux/macOS: ~/.config/hounddog/.env
• Windows: %APPDATA%\hounddog\.env

The file uses shell .env syntax — one KEY=value per line, with optional export prefixes and quotes:

~/.config/hounddog/.env

export HOUNDDOG_API_KEY='your_hounddog_api_key_here'
export HOUNDDOG_AI_PROVIDER='anthropic'
export HOUNDDOG_AI_MODEL_ID='claude-opus-5'
export HOUNDDOG_AI_API_KEY='your_provider_api_key_here'

The following keys are honored from the file: HOUNDDOG_ENV, HOUNDDOG_URL, HOUNDDOG_API_KEY, HOUNDDOG_AI_PROVIDER, HOUNDDOG_AI_MODEL_ID, HOUNDDOG_AI_API_KEY, HOUNDDOG_AI_BASE_URL, and HOUNDDOG_AI_AWS_REGION. Real environment variables always take precedence over values in the file.

Tip

The self-hosted installer writes this file for you, pointing the scanner at your deployment.

Excluding Files and Directories from Scans

By default, the scanner respects your .gitignore and skips a built-in list of directories and files that rarely contain application dataflows — dependency directories (node_modules/, vendor/), build outputs (dist/, build/), tests, lockfiles, binaries, and similar. Minified, bundled, and packed JavaScript (*.min.js, *-min.js, *_min.js, *.bundle.js, *.pack.js) is always skipped, as is any JavaScript or TypeScript file detected as generated from its content (very long single lines).

To exclude additional files and folders, create a .hounddogignore file at the root of your repository using the .gitignore pattern format:

.hounddogignore

# Ignore a directory
generated/

# Ignore a specific file
config.js

# Ignore all files in the sandbox directory
sandbox/*

Enterprise organizations can also manage ignore patterns centrally — per organization or per repository — on the Cloud Platform.

Local Scan State

The scanner persists the results of each scan in a local database so that:

• Repeat scans of an unchanged repository reuse the stored results instead of re-scanning.
• Scans of a partially changed repository re-analyze only the affected files (differential scans).
• Scan data stays queryable after a scan — this is what powers the MCP server.

This happens automatically; no configuration is required. The database lives at:

• Linux/macOS: ~/.local/share/hounddog/hounddog.db
• Windows: %LOCALAPPDATA%\hounddog\hounddog.db

One shared database holds the state for every scanned repository, with separate state per git branch. The store is a cache: deleting it is always safe and only costs one full scan per repository. Store failures (an unreadable or locked database) never fail a scan — the scanner logs a warning and falls back to a full scan.

When Stored Results Are Reused

A scan skips analysis entirely and reuses the stored results only when all of the following hold:

1. The scan targets the repository root directory (single-file and sub-directory scans never touch the store).
2. Nothing that affects results has changed: the scanner version, the bundled rules, your organization’s cloud rules, and the SCM type all match the previous scan.
3. The repository’s git remote URL matches the previous scan.
4. No scannable file changed since the previous scan.

When some files did change, the scanner runs a differential scan: it re-analyzes only the changed and added files plus any files whose analysis depends on them (for example, callers of a function you modified), and reuses the stored results for everything else. A differential scan produces results identical to a full scan of the same tree; if too much of the repository changed (for example after a branch switch or a large rebase), the scanner runs a plain full scan instead, which is faster in that case.

Change detection works like git’s index — file size, timestamps, and content hashes — so it works in any directory, not just git repositories.

What Still Runs on Fast Paths

Even when results are reused or hydrated from the store, everything downstream of the analysis runs as normal: include/exclude filters, the AI review for not-yet-reviewed dataflows, all outputs, the results upload, and the fail-severity CI gate. Stored AI review verdicts are reused, so repeated scans do not re-review unchanged dataflows.

Retention

The store keeps the most recent 50 scans per branch. Branches not scanned for 90 days are evicted along with their state. Moving a repository to a new path starts fresh state.

Forcing a Full Scan

Use --no-cache to ignore the stored results and force a full scan (the fresh results are still persisted afterwards):

bash

hounddog scan --no-cache