> 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/prevent/cli.md). # CLI Run Heeler security checks locally and in CI for repositories hosted on GitHub, GitLab, Bitbucket, and Azure DevOps. `heelercli` runs security checks against a local directory or Git working tree. Run individual checks while developing, or use `heelercli ci` for a combined CI suite. The CLI works with repositories hosted on **GitHub, GitLab, Bitbucket, and Azure DevOps**. Heeler distributes the CLI through GitHub Releases, but the repository does not need to be hosted on GitHub or connected to Heeler. {% hint style="info" %} **Not installed yet?** [Install the CLI](/mrecEO40m5D6bt7Pq5pE/get-started/set-up-developer-tooling/cli.md) covers installation, authentication, pre-commit hooks, and CI setup for all four SCM providers. {% endhint %} ## Choose a task | Goal | Command | | ------------------------------------------------------------------ | ----------------------------------------- | | Scan staged changes for secrets | `heelercli secrets --pre-commit` | | Scan application code, Dockerfiles, and infrastructure as code | `heelercli sast` | | Find vulnerable dependencies | `heelercli vulnerabilities` | | Enforce dependency license and minimum-age policy | `heelercli dependency-policy` | | Detect malicious or compromised packages | `heelercli detect-malicious-packages` | | Check an agent skill, instruction file, hook, or MCP configuration | `heelercli scan-agent-file --path ` | | Run the default combined CI suite | `heelercli ci` | This page covers security scans and policy enforcement. See the [CLI Command Reference](/mrecEO40m5D6bt7Pq5pE/reference/cli-command-reference.md) for every command and flag, including SBOM assessment, dependency recommendations, fixes, and threat-model workflows. ## Security checks | Command | What it checks | Authentication | | ------------------------------------- | --------------------------------------------------------------------------------------- | -------------- | | `heelercli secrets` | Exposed secrets, tokens, and API keys | Not required | | `heelercli sast` | Application code, Dockerfiles, and infrastructure-as-code templates | Required | | `heelercli vulnerabilities` | Dependencies with known vulnerabilities | Required | | `heelercli licenses` | Dependency licenses against an allowlist or denylist | Required | | `heelercli dependency-policy` | Dependency licenses and minimum package age | Required | | `heelercli detect-malicious-packages` | Typosquatting, malware, and compromised packages | Required | | `heelercli scan-agent-file` | Prompt injection, data exfiltration, unsafe execution, and other malicious instructions | Required | Authenticate platform-backed checks with `heelercli login` or `HEELER_API_KEY`. A secrets-only run, including `heelercli ci --checks secrets`, does not require authentication. ### Run a local check Run a check from the repository or directory you want to scan: ```bash heelercli vulnerabilities --fail-on-severity critical,high ``` A configured policy violation returns a nonzero exit code: ```console $ heelercli vulnerabilities --fail-on-severity critical,high Vulnerability Summary - total: 1 - critical: 1 high: 0 medium: 0 low: 0 unknown: 0 - policy violations: 1 $ echo $? 1 ``` An exit code of `0` means the command completed without violating its configured failure policy. It does not always mean that the scan found nothing. For example, a vulnerability scan without a failure policy reports its findings and exits `0`. ### Check detector coverage Dependency scans continue when one manifest cannot be analyzed and report the incomplete coverage in their output. Review the coverage block before treating a passing result as complete. * JSON output includes a `coverage` object. * SARIF output includes a `heeler.coverage` warning for each manifest that was not analyzed. * Text output identifies any manifest without coverage. See [Scan coverage](/mrecEO40m5D6bt7Pq5pE/reference/cli-command-reference.md#scan-coverage) for the coverage states and troubleshooting steps. ### Vet an agent file or skill Scan an agent file or a directory that represents one agent component: ```bash heelercli scan-agent-file \ --path .claude/skills/deploy \ --fail-on-intent suspicious ``` Each file receives a 0–100 safety score, a severity band, and an assessed intent of `benign`, `suspicious`, or `malicious`. Without a failure flag, the command reports findings but does not fail on them. One request can contain up to three files, with a limit of 250,000 bytes per file and 750,000 bytes in total. Scan a single skill directory rather than an entire agent-configuration tree. To scan every supported agent file in a repository, add `agent-files` to `heelercli ci`. ## Run the combined CI suite By default, `heelercli ci` runs: * `vulnerabilities` * `dependency-policy` * `malicious-packages` * `secrets` Run the suite and write SARIF output: ```bash heelercli ci --format sarif --output results.sarif -q ``` Add repository-wide agent-file scanning when required: ```bash heelercli ci \ --checks vulnerabilities,dependency-policy,malicious-packages,secrets,agent-files ``` The `licenses` check is also available through `--checks`, but `licenses` and `dependency-policy` cannot run together in the same `ci` invocation. Run `heelercli sast` separately; SAST is not a `heelercli ci` check. Store `HEELER_API_KEY` in the protected secret store for your CI system. The CLI command is the same for repositories hosted on GitHub, GitLab, Bitbucket, and Azure DevOps. See [Run in CI](/mrecEO40m5D6bt7Pq5pE/get-started/set-up-developer-tooling/cli.md#run-in-ci) for complete examples for GitHub Actions, GitLab CI, Bitbucket Pipelines, and Azure Pipelines. If a selected check cannot complete, `heelercli ci` continues the other checks, writes the report, marks the affected check as `status: error`, and exits `1`. JSON output records the number of operational errors in `checks_errored`, which lets a pipeline distinguish an execution error from a policy failure. Current CLI releases batch dependency assessments and use bounded retries for read-only requests that receive `429` responses. See [Rate Limits](/mrecEO40m5D6bt7Pq5pE/reference/rate-limits.md) for platform limits and response headers. ## Configure policy as code Place `.heeler.yaml` in the repository root to share vulnerability gates, dependency policy, secret suppressions, and named profiles. ```yaml version: v1 vulnerabilities: fail_on_severity: [critical, high] licenses: fail_on: [GPL-3.0-only, AGPL-3.0-only] secrets: suppressions: [] ``` Validate and inspect the effective policy: ```bash heelercli policy validate heelercli policy explain ``` Test a saved findings report against the policy: ```bash heelercli policy test --findings ``` To migrate Snyk ignore rules, run: ```bash heelercli policy import-snyk --input .snyk ``` The command writes `.heeler.yaml` by default. Use `--output` to select a different path. ### Fail only on new vulnerabilities Create a baseline report: ```bash heelercli vulnerabilities \ --format json \ --output .heeler-baseline-vulnerabilities.json ``` Add it to the policy configuration: ```bash heelercli policy set-baseline \ --baseline .heeler-baseline-vulnerabilities.json \ --create-config \ --enable-new-findings-only ``` You can also enable regression mode with command-line flags. For a standalone vulnerability scan: ```bash heelercli vulnerabilities \ --baseline .heeler-baseline-vulnerabilities.json \ --new-findings-only ``` For the combined CI suite: ```bash heelercli ci \ --vulnerabilities-baseline .heeler-baseline-vulnerabilities.json \ --vulnerabilities-new-findings-only ``` ## Output formats Most commands support `--format` and `--output`. Depending on the command, available formats include `detailed`, `table`, `json`, `llm`, and `sarif`. The secrets command does not accept either flag. See the [CLI Command Reference](/mrecEO40m5D6bt7Pq5pE/reference/cli-command-reference.md#commands) for the format supported by each command. ## Supported dependency ecosystems Dependency checks support: * C# and .NET * Go * Java with Maven or Gradle * JavaScript and TypeScript with npm, pnpm, Yarn, or Bun * PHP * Python with uv, Poetry, Pipenv, or requirements files * Ruby * Rust See [Supported ecosystems](/mrecEO40m5D6bt7Pq5pE/reference/cli-command-reference.md#supported-ecosystems) for detector requirements and [Install the CLI](/mrecEO40m5D6bt7Pq5pE/get-started/set-up-developer-tooling/cli.md#requirements) for supported operating systems and architectures. ## Troubleshooting | Symptom | Resolution | | -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `heelercli` is not on `PATH` | Use the automatic pre-commit hook or install the binary on `PATH`. See [Install the CLI](/mrecEO40m5D6bt7Pq5pE/get-started/set-up-developer-tooling/cli.md). | | Authentication fails | Run `heelercli login` or set `HEELER_API_KEY`. Set `HEELER_BASE_URL` when the tenant does not use `https://app.heeler.com`. | | A dependency manifest was not analyzed | Review the detector-coverage output and install any required local ecosystem tool. | | macOS reports an incompatible binary | Run the terminal natively. The automatic hook selects `darwin-arm64` on Apple Silicon and `darwin-amd64` on Intel Macs; Rosetta-translated shells are not supported. | | A CI check reports `status: error` | Inspect `checks_errored` and the check summary for authentication, connectivity, or rate-limit errors. Other selected checks still run. | ## Related * [Install the CLI](/mrecEO40m5D6bt7Pq5pE/get-started/set-up-developer-tooling/cli.md) — install the binary or hooks and configure CI. * [CLI Command Reference](/mrecEO40m5D6bt7Pq5pE/reference/cli-command-reference.md) — review every command, flag, environment variable, and output format. * [Agent Skills](/mrecEO40m5D6bt7Pq5pE/prevent/agent-skills.md) — run the same security workflows from an AI coding agent. * [Agent Files](/mrecEO40m5D6bt7Pq5pE/findings/agentic-supply-chain-agent-files.md) — understand agent-file inventory and scoring. * [PR Guardrails](/mrecEO40m5D6bt7Pq5pE/prevent/pr-guardrails.md) — enforce policy before merge. --- # 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/prevent/cli.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.