> For the complete documentation index, see [llms.txt](https://docs.heeler.com/mrecEO40m5D6bt7Pq5pE/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.heeler.com/mrecEO40m5D6bt7Pq5pE/reference/cli-command-reference.md). # CLI Command Reference Commands, flags, authentication, output formats, environment variables, ecosystems, and platforms for heelercli. This page documents the current `heelercli` release. Run `heelercli --help` to check the exact options available in your installed version. Use the CLI with repositories hosted on **GitHub, GitLab, Bitbucket, or Azure DevOps**. The repository host does not change the commands. The CLI scans local files and can also scan a plain directory, exported source tree, or Subversion working copy. * [Install the CLI](/mrecEO40m5D6bt7Pq5pE/get-started/set-up-developer-tooling/cli.md) — install, verify, and add pre-commit or global hooks. * [Use the CLI](/mrecEO40m5D6bt7Pq5pE/prevent/cli.md) — choose checks, configure policy, and run local or CI workflows. ## Command index | Command | Purpose | Heeler authentication | Output | | --------------------------------------------------------------------------- | ---------------------------------------------- | ----------------------------------------------------------------- | --------------------------------------- | | [`secrets`](#heelercli-secrets) | Find exposed credentials | No | Console only | | [`sast`](#heelercli-sast) | Scan source and infrastructure-as-code | Yes | Detailed, table, JSON, SARIF | | [`vulnerabilities`](#heelercli-vulnerabilities) | Find vulnerable dependencies | Yes | Detailed, table, JSON, LLM, SARIF | | [`licenses`](#heelercli-licenses) | Inventory and enforce dependency licenses | Yes; `licenses valid` can use local policy without authentication | Detailed, table, JSON, LLM, SARIF | | [`dependency-policy`](#heelercli-dependency-policy) | Enforce license and package-age policy | Yes | Detailed, table, JSON, LLM, SARIF | | [`detect-malicious-packages`](#heelercli-detect-malicious-packages) | Find malicious and suspicious packages | Yes | Detailed, table, JSON, LLM, SARIF | | [`scan-agent-file`](#heelercli-scan-agent-file) | Assess agent instructions and skills | Yes | Detailed, table, JSON, LLM, SARIF | | [`ci`](#heelercli-ci) (`pre-commit` alias) | Run several checks in one command | Yes, except a secrets-only run | Detailed, JSON, LLM, SARIF | | [`fix`](#heelercli-fix) | Start agentic remediation | Yes | Console | | [`threat-model`](#heelercli-threat-model) | Export threat-model context or prompts | Yes | Subcommand-specific | | [`assess-sbom`](#heelercli-assess-sbom) | Assess an existing CycloneDX SBOM | Yes | Detailed, table, JSON, LLM, SARIF | | [`get-recommended-version`](#heelercli-get-recommended-version) | Find the safest observed package version | Yes | Detailed, JSON, LLM | | [`download-sbom`](#heelercli-download-sbom) | Download a platform-generated SBOM | Yes | CycloneDX JSON to stdout | | [`policy`](#heelercli-policy) | Validate, test, import, or update local policy | No Heeler authentication | Console and local files | | [`login`, `version`, `completion`](#heelercli-login-version-and-completion) | Authenticate and manage the CLI | `login` establishes authentication | Console, configuration, or shell script | ## Output and exit behavior Commands that support `--format` use these values: | Commands | Formats | | ----------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- | | `vulnerabilities`, `licenses`, `dependency-policy`, `detect-malicious-packages`, `assess-sbom`, `scan-agent-file` | `detailed` (default), `table`, `json`, `llm`, `sarif` | | `sast` | `detailed` (default), `table`, `json`, `sarif` | | `ci` | `detailed` (default), `json`, `llm`, `sarif` | | `get-recommended-version` | `detailed` (default), `json`, `llm` | | `secrets` | No `--format` or `--output` option | `--output ` writes the selected format to a file. Without it, output goes to stdout. A command exits non-zero when: * a finding violates an active gate or policy; * input or configuration is invalid; or * the scan cannot complete. Finding a vulnerability does not always mean exit `1`. Without a failure policy, reporting commands can show findings and exit `0`. `assess-sbom` is always report-only: it does not apply policy gates or exit non-zero only because it found vulnerabilities. {% hint style="info" %} **Git is optional for directory scans.** `secrets`, `sast`, and `ci` scan the Git repository root when run inside a repository and the current directory otherwise. `secrets` and `sast` accept `--path`; `ci` does not, so change to the directory you want to scan. Staged pre-commit scanning and Git-tracked agent-file discovery require Git. {% endhint %} ## Commands ### `heelercli secrets` Find exposed secrets, tokens, credentials, and API keys. No authentication is required. | Flag | Description | | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--pre-commit` | Scan staged changes only. | | `--path ` | Directory to scan. Defaults to the enclosing Git repository or the current directory outside Git. | | `--exclude ` | Exclude a glob pattern. Repeat for multiple patterns. `*` and `?` stay within one path segment; `**` crosses segments. A plain name matches the scan root only; use `**/vendor/**` to match at any depth. | | `--exclude-dir ` | Exclude a directory. Repeat for multiple directories. | | `--fail-on ` | Fail only on the specified comma-separated secret rule families, such as `aws,github,slack`. | | `--only-validated` | Fail only on live-validated active credentials and key material whose liveness cannot be tested. All findings remain visible. | | `--timeout ` | Maximum scan time. Default: `5m`. | ```bash heelercli secrets heelercli secrets --pre-commit heelercli secrets --path . --exclude '**/fixtures/**' ``` Values are masked in output. Each file-and-line occurrence includes a stable fingerprint. Suppress a false positive in `.heeler.yaml`: ```yaml secrets: suppressions: - fingerprint: "10459047045948343115" reason: Test credential used by integration fixtures expires_on: 2026-12-31 ``` `reason` is required. `expires_on` is optional. Suppressions apply to both `secrets` and the secrets check in `ci`; suppressed findings remain visible but do not fail the scan. Exclude binary caches and build output. Large binaries can produce many credential-like byte sequences. Supplying exclusions can also make the engine traverse `.git` before the CLI removes those findings, which can slow the scan. ### `heelercli sast` Run static analysis over application code, Dockerfiles, Terraform/OpenTofu, CloudFormation, Kubernetes, and Pulumi. Authentication is required. The CLI downloads, verifies, and caches the scan engine unless `HEELER_SKULLY_BINARY` is set. | Flag | Description | | ------------------------ | --------------------------------------------------------------------------------------------------------------------- | | `--fail-on ` | Comma-separated severities: `critical`, `high`, `medium`, `low`, `info`. When the flag is omitted, any finding fails. | | `--path ` | Directory to scan. Defaults to the enclosing Git repository or the current directory outside Git. | | `--repo-profile` | Include repository profiling. | | `--exclude ` | Exclude a glob pattern. Repeat for multiple patterns. Invalid patterns fail before scanning. | | `--exclude-dir ` | Exclude a directory from the scan. Repeat for multiple directories. | | `--timeout ` | Maximum scan time. Default: `10m`. | | `--format ` | `detailed`, `table`, `json`, or `sarif`. | | `--output ` | Write findings to a file. | ```bash heelercli sast --fail-on critical,high ``` Infrastructure-as-code findings use the `iac` category, matching [IaC findings](/mrecEO40m5D6bt7Pq5pE/findings/iac.md) in the web interface. ### `heelercli vulnerabilities` Discover dependency manifests, generate SBOMs, assess known vulnerabilities, and apply vulnerability policy. Authentication is required. | Flag | Description | | --------------------------------- | --------------------------------------------------------------------------------------- | | `--fail-on-any` | Fail when any vulnerability is found. | | `--fail-on-severity ` | Fail on comma-separated `critical`, `high`, `medium`, `low`, or `unknown` findings. | | `--fail-on-id ` | Fail on comma-separated CVE or GHSA identifiers. | | `--baseline ` | Read baseline findings JSON for diff mode. | | `--new-findings-only` | Evaluate only findings absent from the baseline. | | `--dependency-class ` | Filter by `required`, `optional`, `excluded`, `dev`/`development`, or `unknown`. | | `--exclude-dir ` | Exclude a directory from SBOM collection and analysis. Repeat for multiple directories. | | `--show-dependency-paths` | Include dependency paths. Default: `true`. | | `--max-dependency-paths ` | Maximum paths per finding. Default: `5`; `0` also uses the default. | | `--format ` | `detailed`, `table`, `json`, `llm`, or `sarif`. | | `--output ` | Write the report to a file. | ```bash heelercli vulnerabilities --fail-on-severity critical,high ``` The `exploitation` block includes the exploitation level, EPSS score and percentile, KEV status, ransomware status, and exploit-link count. `upgrade` identifies the direct dependency that introduces the vulnerable package; use `fixed` to see versions containing a fix. If findings exist but no failure policy is configured, the command reports them and exits `0`. ### `heelercli licenses` Inventory dependency licenses and apply license policy. Authentication is required for the dependency scan. | Flag | Description | | ---------------------------------------- | -------------------------------------------------------------------------------- | | `--ok ` | Comma-separated accepted SPDX licenses. | | `--fail-on ` | Comma-separated SPDX licenses that always fail. | | `--unknown-license-policy ` | Handle unknown or missing licenses. Default: `allow`. | | `--min-age-days ` | Deprecated here; use `dependency-policy`. | | `--unknown-publish-policy ` | Deprecated here; use `dependency-policy`. | | `--dependency-class ` | Filter by `required`, `optional`, `excluded`, `dev`/`development`, or `unknown`. | | `--exclude-dir ` | Exclude a directory. Repeat for multiple directories. | | `--show-dependency-paths` | Include dependency paths. Default: `true`. | | `--max-dependency-paths ` | Maximum paths per finding. Default: `5`; `0` also uses the default. | | `--format ` | `detailed`, `table`, `json`, `llm`, or `sarif`. | | `--output ` | Write the report to a file. | SPDX expressions such as `MIT OR X11` and `GPL-3.0-only AND MIT` are evaluated as expressions. Unknown or unparseable values follow `--unknown-license-policy`. #### `heelercli licenses valid` Print the effective allowed-license set. Resolution order is command flags, local policy, then Heeler platform defaults when neither provides a license list. | Flag | Description | | ---------------------- | ------------------------------------------------------ | | `--ok ` | Comma-separated accepted SPDX licenses. | | `--fail-on ` | Comma-separated SPDX licenses that should always fail. | | `--llm-output` | Print a concise LLM-friendly list. | Authentication is not needed when flags or local policy resolve the list. The fallback to platform defaults requires authentication. ### `heelercli dependency-policy` Apply license policy and minimum-package-age policy in one dependency scan. Authentication is required. | Flag | Description | | ---------------------------------------- | --------------------------------------------------------------------------------- | | `--min-age-days ` | Fail when a dependency is newer than this number of days. `0` disables the check. | | `--unknown-publish-policy ` | Handle an unknown publish date when minimum age is enabled. Default: `allow`. | | `--ok ` | Comma-separated accepted SPDX licenses. | | `--fail-on ` | Comma-separated SPDX licenses that always fail. | | `--unknown-license-policy ` | Handle unknown or missing licenses. Default: `allow`. | | `--dependency-class ` | Filter by `required`, `optional`, `excluded`, `dev`/`development`, or `unknown`. | | `--exclude-dir ` | Exclude a directory. Repeat for multiple directories. | | `--show-dependency-paths` | Include dependency paths. Default: `true`. | | `--max-dependency-paths ` | Maximum paths per finding. Default: `5`; `0` also uses the default. | | `--format ` | `detailed`, `table`, `json`, `llm`, or `sarif`. | | `--output ` | Write the report to a file. | ### `heelercli detect-malicious-packages` Detect malware, typosquatting, and other package supply-chain risks. Authentication is required. | Flag | Description | | ------------------------------ | -------------------------------------------------------------------------------- | | `--fail-on-any` | Fail when any malicious package is detected. | | `--dependency-class ` | Filter by `required`, `optional`, `excluded`, `dev`/`development`, or `unknown`. | | `--exclude-dir ` | Exclude a directory. Repeat for multiple directories. | | `--show-dependency-paths` | Include dependency paths. Default: `true`. | | `--max-dependency-paths ` | Maximum paths per finding. Default: `5`; `0` also uses the default. | | `--format ` | `detailed`, `table`, `json`, `llm`, or `sarif`. | | `--output ` | Write the report to a file. | ### `heelercli scan-agent-file` Scan one agent file or one agent/skill directory for prompt injection, data exfiltration, and other [agent-file risks](/mrecEO40m5D6bt7Pq5pE/findings/agentic-supply-chain-agent-files.md). Authentication is required. A directory is bundled and assessed as one agent, so its instruction file and supporting scripts are judged together. The scan is synchronous and stateless; the report is returned to the CLI and is not persisted by this command. | Flag | Description | | --------------------------- | ------------------------------------------------------------------------------- | | `--path ` | File or directory to scan. Required. | | `--fail-on ` | Fail at or above `info`, `low`, `medium`, `high`, or `critical`. | | `--fail-on-intent ` | Fail at or above `suspicious` or `malicious`. | | `--exclude-dir ` | Exclude a directory when scanning a directory. Repeat for multiple directories. | | `--format ` | `detailed`, `table`, `json`, `llm`, or `sarif`. | | `--output ` | Write the report to a file. | With no failure flags, the command reports findings and exits `0`. It does not read gates from `.heeler.yaml`; the `agent-files` check in `ci` does. Local limits are 3 files, 250,000 bytes per file, 750,000 bytes of content, and 1,048,576 uploaded bytes per scan. Scan one skill directory at a time; use `ci --checks agent-files` to scan a repository. Scores range from 0 to 100; higher is safer. Bands are `info` (90–100), `low` (70–89), `medium` (40–69), `high` (20–39), and `critical` (0–19). Intent is `benign`, `suspicious`, or `malicious`. SARIF carries individual findings but not scores, bands, or assessed intent; use JSON for lossless machine-readable output. The command retries transient platform failures up to three times and honors `Retry-After`. Authentication failures and invalid requests are not retried. ### `heelercli ci` Run several checks and return one result for a hook or pipeline. Default checks are `vulnerabilities`, `dependency-policy`, `malicious-packages`, and `secrets`. `licenses` and `agent-files` are optional. `sast` is not part of `ci`; run it separately. Authentication is required unless `--checks secrets` is the only selected check. `pre-commit` is an alias for `ci`. #### General flags | Flag | Description | | --------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | | `--checks ` | Comma-separated `vulnerabilities`, `dependency-policy`, `licenses`, `malicious-packages`, `secrets`, and `agent-files`. | | `--exclude-dir ` | Exclude a directory from dependency analysis and secrets scanning. Repeat for multiple directories. | | `--dependency-class ` | Filter dependency findings by `required`, `optional`, `excluded`, `dev`/`development`, or `unknown`. | | `--max-dependency-paths ` | Maximum dependency paths per finding. Default: `5`; `0` also uses the default. | | `--format ` | `detailed`, `json`, `llm`, or `sarif`. | | `--output ` | Write the combined report to a file. | | `--sarif-findings ` | Include only failing findings or all findings in SARIF. Default: `failing`. | #### Vulnerability flags | Flag | Description | | ------------------------------------------------- | ------------------------------------------------ | | `--vulnerabilities-fail-on-any` | Fail on any vulnerability. | | `--vulnerabilities-fail-on-severity ` | Fail on comma-separated severities. | | `--vulnerabilities-fail-on-id ` | Fail on comma-separated vulnerability IDs. | | `--vulnerabilities-baseline ` | Read baseline vulnerability JSON. | | `--vulnerabilities-new-findings-only` | Evaluate only findings absent from the baseline. | #### License and dependency-policy flags | License flag | Dependency-policy alias | Description | | ------------------------------------------------- | -------------------------------------------- | --------------------------------------------------------- | | `--licenses-ok ` | `--dependency-policy-ok` | Accepted SPDX licenses. | | `--licenses-fail-on ` | `--dependency-policy-fail-on` | SPDX licenses that always fail. | | `--licenses-unknown-license-policy ` | `--dependency-policy-unknown-license-policy` | Handle unknown or missing licenses. | | `--licenses-min-age-days ` | `--dependency-policy-min-age-days` | Minimum package age; `0` disables the check. | | `--licenses-unknown-publish-policy ` | `--dependency-policy-unknown-publish-policy` | Handle unknown publish dates when package age is enabled. | The two names in each row configure the same value. Package-age flags affect `dependency-policy`, not the license-only check. #### Malicious-package, secret, and agent-file flags | Flag | Description | | --------------------------------------- | ----------------------------------------------------------------------------------------- | | `--malicious-fail-on-any` | Fail when any malicious package is detected. | | `--secrets-pre-commit` | Scan staged changes only. | | `--secrets-fail-on ` | Fail on comma-separated secret rule families. | | `--secrets-only-validated` | Fail only on validated credentials and assumed-valid key material. | | `--secrets-exclude ` | Add a directory exclusion for secret scanning. Repeat for multiple directories. | | `--secrets-timeout ` | Maximum secret-scan time. Default: `5m`. | | `--agent-files-fail-on ` | Fail a file at or above the selected band. | | `--agent-files-fail-on-intent ` | Fail a file at or above `suspicious` or `malicious`. Default without policy: `malicious`. | | `--agent-files-exclude ` | Add a directory exclusion for agent-file discovery. Repeat for multiple directories. | ```bash # Default checks heelercli ci # Secrets only; no Heeler authentication required heelercli ci --checks secrets --secrets-pre-commit # Add agent-file scanning heelercli ci --checks vulnerabilities,dependency-policy,malicious-packages,secrets,agent-files ``` A check that cannot finish has `status: error`. Other checks continue, the report is still written, and `ci` exits `1`. In JSON, inspect `checks_errored`; in detailed output, inspect each check status. In SARIF, an errored check is a result at `level: error`. The `agent-files` check discovers known agent instructions, skills, commands, subagents, hook scripts, and agent/MCP configuration. Inside Git, discovery uses tracked files; untracked and ignored files are not scanned. Outside Git, it walks the directory. Oversize files, binaries, and symlinks are counted as skipped. Configure agent-file gates in `.heeler.yaml`: ```yaml ci: agent_files: fail_on: high fail_on_intent: malicious exclude: - testdata ``` ### `heelercli fix` Start the Fix Now remediation agent for one or more comma-separated remediation IDs. Authentication is required. ```bash heelercli fix ``` | Flag | Description | | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | `--skip-review` | Open the pull request immediately. Use `--skip-review=false` to require administrator approval; omit the flag to use the tenant default. | | `--separate-prs` | Create one pull request per remediation instead of grouping by repository. | Get remediation IDs from the [Remediation Workbench](/mrecEO40m5D6bt7Pq5pE/operate/dashboards/remediation-workbench.md). See [Automate Remediation](/mrecEO40m5D6bt7Pq5pE/fix/automate-remediation.md) for the full workflow. ### `heelercli threat-model` Build threat-modeling artifacts from Heeler service decomposition. Authentication is required. | Subcommand | Purpose | | --------------------------------- | ------------------------------------------------------------------------------- | | `threat-model context` | Fetch a service-decomposition context export. | | `threat-model prompt` | Build an LLM-ready threat-modeling prompt. | | `threat-model resolve-service-id` | Resolve a service from a flag, environment variable, or `.heeler.yaml` mapping. | Shared flags are `--service-id`, `--deployment-id`, `--path` (default `.`), `--framework `, `--output `, and `--format`. `context` supports `json` (default) and `llm`; `prompt` supports `markdown` (default) and `json`. `threat-model prompt` also accepts `--redact-secrets` (default `true`). `resolve-service-id` always writes JSON; its inherited `--format` value is not used. See [Threat Modeling with the Service Decomposition Export](/mrecEO40m5D6bt7Pq5pE/solutions-and-use-cases/threat-modeling-with-service-decomposition.md). ### `heelercli assess-sbom` Assess an existing CycloneDX JSON SBOM for vulnerabilities. Authentication is required. | Flag | Description | | -------------------- | ----------------------------------------------- | | `--sbom ` | CycloneDX JSON SBOM. Required. | | `--format ` | `detailed`, `table`, `json`, `llm`, or `sarif`. | | `--output ` | Write the report to a file. | | `--sbom_file ` | Deprecated compatibility alias for `--sbom`. | ```bash heelercli assess-sbom --sbom bom.json --format json --output assessment.json ``` This command reports findings but does not evaluate vulnerability policy. Vulnerabilities alone do not make it exit non-zero. ### `heelercli get-recommended-version` Return the most-used version of a package in your Heeler environment that has no active vulnerabilities. Authentication is required. ```bash heelercli get-recommended-version --package-ecosystem ``` | Flag | Description | | --------------------------------- | ------------------------------------------------------------------------------------------------------ | | `--package-ecosystem ` | Required. `maven`, `pypi`, `npm`, `go`, `nuget`, `rubygems`, `composer`, or `cargo`; case-insensitive. | | `--format ` | `detailed`, `json`, or `llm`. | | `--output ` | Write the result to a file. | Detailed and LLM output include observed usage as a confidence signal and identify unpinned ranges, sparse evidence, or an empty recommendation. ### `heelercli download-sbom` Download a platform-generated SBOM. Authentication is required. Supply exactly one identifier; output is written to stdout. | Flag | Description | | ----------------------- | ----------------------- | | `--service_id ` | Numeric service ID. | | `--application_id ` | Numeric application ID. | ```bash heelercli download-sbom --service_id 123 > sbom.json ``` ### `heelercli policy` Manage local policy-as-code. These commands do not require Heeler authentication. | Subcommand | Options and behavior | | ------------------------------- | ------------------------------------------------------------------------------------- | | `policy validate` | Validate policy syntax and schema. | | `policy explain` | Print the effective policy after profile overrides. | | `policy test --findings ` | Test vulnerability findings JSON. Add `--baseline ` for new-findings-only mode. | | `policy import-snyk` | Convert Snyk ignore rules to Heeler suppressions. | | `policy set-baseline` | Update baseline settings in the policy file. | `policy import-snyk` flags: | Flag | Description | | ------------------------------ | --------------------------------------------------------------------------- | | `--input ` | Source Snyk policy. Default: `.snyk`. | | `--output ` | Destination Heeler policy. Default: `.heeler.yaml`. | | `--resolve-cve` | Resolve Snyk vulnerability IDs through `security.snyk.io`. Default: `true`. | | `--resolve-timeout ` | HTTP timeout for Snyk CVE lookups. Default: `8s`. | | `--overwrite` | Replace an existing output file. | `policy set-baseline` flags: | Flag | Description | | ------------------------------------- | ---------------------------------------------------------- | | `--baseline ` | Baseline vulnerability report path. Required. | | `--scope ` | Sections to update. Default: `both`. | | `--create-profile` | Create a missing profile block when used with `--profile`. | | `--create-config` | Create the policy file if it does not exist. | | `--dry-run` | Print the resulting file without writing it. | | `--yes` | Allow a lossy rewrite of a JSON policy file. | | `--enable-new-findings-only` | Set `new_findings_only: true` in updated sections. | | `--disable-new-findings-only` | Set `new_findings_only: false` in updated sections. | YAML updates preserve comments, key order, and indentation. JSON is rebuilt from the policy schema, so key order and keys outside the schema do not survive. The command stops and warns before a lossy JSON rewrite unless `--yes` is set. ### `heelercli login`, `version`, and `completion` ```bash heelercli login heelercli login https://app.heeler.com YOUR_API_KEY heelercli version heelercli completion bash ``` `login` accepts an optional base URL and API key. With an API key, it validates and saves the key. Without one, it starts browser-based OAuth. The default base URL is `https://app.heeler.com`. | Login flag | Description | | ---------------------------- | --------------------------------------------------------- | | `--oauth-client-id ` | OAuth client ID. Default: `heeler-cli`. | | `--oauth-redirect-uri ` | Redirect URI. Default: `http://127.0.0.1:38080/callback`. | Credentials are stored at: * Linux: `~/.config/heeler/config.json` * macOS: `~/Library/Application Support/heeler/config.json` * Windows: `%AppData%\heeler\config.json` `completion` supports `bash`, `zsh`, `fish`, and `powershell`. ## Global flags | Flag | Description | | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | `-h`, `--help` | Show help. | | `-v`, `--version` | Print the CLI version. | | `-q`, `--quiet` | Disable progress output. Recommended for CI. | | `--config ` | Use a specific policy file. Auto-discovery checks `.heeler.yaml`, `.heeler.yml`, `.heeler.config.yaml`, `.heeler.config.yml`, then `.heeler.config.json`. | | `--profile ` | Apply a named profile from the policy file. | ## Environment variables `HEELER_*` variables configure the CLI. `HEELERCLI_*` variables configure the [auto-install pre-commit hook](/mrecEO40m5D6bt7Pq5pE/get-started/set-up-developer-tooling/cli.md#install-the-pre-commit-hook), not direct binary invocations. The base URL resolves in this order: `HEELER_BASE_URL`, the `heeler_base_url` saved by `heelercli login`, then `https://app.heeler.com`. | Variable | Description | | ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `HEELER_API_KEY` | API key. Does not change the configured base URL. | | `HEELER_BASE_URL` | Platform base URL. | | `HEELER_LOG_FILE` | Debug-log path. Defaults to `~/.cache/heeler/heelercli.log` on Linux, `~/Library/Caches/heeler/heelercli.log` on macOS, and `%LocalAppData%\heeler\heelercli.log` on Windows. | | `HEELER_PROFILE` | Policy profile. `--profile` takes precedence. | | `HEELER_SERVICE_ID` | Default service ID for `threat-model`. `--service-id` takes precedence. | | `HEELER_SKULLY_BINARY` | Path to a prebuilt SAST engine. The CLI uses it without download, version-floor, or checksum checks. | | `HEELER_PYTHON_DEBUG_GRAPH` | Set to `1`, `true`, `yes`, or `on` to add a Python dependency-graph summary to scan warnings. | | `HEELERCLI_VERSION` | Release used by the auto-install hook. Default: `latest`. | | `HEELERCLI_CACHE_DIR` | Override the hook binary-cache directory. | | `XDG_CACHE_HOME` | Base hook cache directory when `HEELERCLI_CACHE_DIR` is unset. | | `HEELERCLI_FULL_SECRETS_SCAN` | Set to `1` for a full-repository hook scan. | | `HEELERCLI_SECRETS_ONLY_VALIDATED` | Set to `1` to add `--only-validated` to the hook scan. | | `HEELERCLI_SECRETS_MODE` | Set hook scan mode to `pre-commit` or `full`. | ## Supported ecosystems Dependency commands discover these files. Some formats are parsed directly; others require the ecosystem toolchain. | Ecosystem | Manifests and lockfiles | | ----------------------- | ----------------------------------------------------------------------------------------------------------- | | C# / .NET | `.csproj` files; resolved with the .NET CLI | | Go | `go.mod` | | Java | Maven `pom.xml`; Gradle `build.gradle` and `build.gradle.kts` | | JavaScript / TypeScript | npm `package.json` and `package-lock.json`; pnpm lockfiles; Yarn `yarn.lock`; Bun `bun.lock` | | PHP | `composer.json` and `composer.lock` | | Python | `uv.lock`, `poetry.lock`, `Pipfile.lock`, `requirements*.txt`; priority is uv, Poetry, Pipenv, requirements | | Ruby | `Gemfile` and `Gemfile.lock` | | Rust | `Cargo.toml`; resolved with `cargo metadata` | Yarn v1 and Berry lockfiles and Bun 1.2+ text lockfiles are parsed directly. The older binary `bun.lockb` format is not parsed directly and may require npm-based regeneration. ## Scan coverage Dependency scans report manifests that could not be resolved. For example, a Maven manifest cannot be analyzed when `mvn` is unavailable. The scan can still exit `0`, so check coverage separately from findings. ```console Coverage: INCOMPLETE - 1 of 4 manifest(s) could not be analyzed - maven at services/payments/pom.xml: mvn: command not found Findings below cover only the manifests that were analyzed. ``` JSON output includes `coverage.complete`, counts, and a failure list. SARIF reports each unresolved manifest as a `heeler.coverage` warning. A complete scan omits the coverage block. {% hint style="warning" %} Treat `coverage.complete: false` as a pipeline signal. A findings-only gate can pass when the toolchain needed to inspect a manifest is missing. {% endhint %} ## Gate value validation Invalid severity, secret-family, agent-file band, or agent-file intent values fail before scanning. | Command | Validated flags | | ----------------- | ------------------------------------------------------------------------------- | | `sast` | `--fail-on` | | `vulnerabilities` | `--fail-on-severity` | | `secrets` | `--fail-on` | | `scan-agent-file` | `--fail-on`, `--fail-on-intent` | | `ci` | Corresponding `--vulnerabilities-*`, `--secrets-*`, and `--agent-files-*` flags | License lists accept arbitrary SPDX identifiers. A misspelled identifier that matches no dependency never fires, so compare values with the `licenses` inventory. ## Platforms Releases use the filename `heelercli--.`: | OS | Architectures | Archive | | ------- | ------------------- | ------- | | Linux | amd64, arm64 | `.tgz` | | macOS | amd64, arm64 | `.tgz` | | Windows | amd64, for Git Bash | `.zip` | Each archive has a `.sha256` checksum and `.bundle` Sigstore attestation. See [Install the binary directly](/mrecEO40m5D6bt7Pq5pE/get-started/set-up-developer-tooling/cli.md#install-the-binary-directly). ## Related * [Install the CLI](/mrecEO40m5D6bt7Pq5pE/get-started/set-up-developer-tooling/cli.md) — install, verify, and configure hooks. * [Use the CLI](/mrecEO40m5D6bt7Pq5pE/prevent/cli.md) — choose checks, configure policy, and build workflows. * [Agent Skills](/mrecEO40m5D6bt7Pq5pE/prevent/agent-skills.md) — run checks from an AI coding agent. * [Rate Limits](/mrecEO40m5D6bt7Pq5pE/reference/rate-limits.md) — API limits and retry behavior. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.heeler.com/mrecEO40m5D6bt7Pq5pE/reference/cli-command-reference.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.