CLI Deployment Guide

This guide walks you through setting up the Heeler CLI (heelercli) in your development environment and repositories. By the end, every commit will be automatically scanned for secrets, and you'll have access to vulnerability, license, and malicious package scanning from the command line.

Prerequisites

• A Heeler account with an API key (available from app.heeler.com)

• Git installed

• Python 3.x and pip (for the pre-commit framework)

• macOS (Apple Silicon only), Linux (amd64/arm64), or Windows (amd64 with Git Bash)

Step 1: Authenticate (optional for secrets scanning)

Secret scanning works without authentication, so you can start scanning for secrets immediately after installing the pre-commit hook. For all other commands (vulnerabilities, licenses, malicious package detection, etc.), you need to authenticate with your Heeler API key.

heelercli login https://app.heeler.com YOUR_HEELER_API_KEY

This saves your credentials to ~/.config/heeler/config.json (Linux/macOS) or %AppData%\heeler\config.json (Windows).

Alternatively, set the environment variable (useful for CI):

export HEELER_API_KEY=YOUR_HEELER_API_KEY

The environment variable takes precedence over the config file.

Step 2: Install the pre-commit framework

pre-commit is a framework for managing git pre-commit hooks. Install it with pip:

pip install pre-commit

Verify the installation:

pre-commit --version

Step 3: Add the hook configuration

Create a .pre-commit-config.yaml file in your repository root:

repos:
  - repo: https://github.com/Heeler-Security/heelercli
    rev: 1.0.0  # replace with the latest release tag
    hooks:
      - id: heelercli-auto

The heelercli-auto hook automatically downloads the correct heelercli binary for your OS and architecture on first run, then caches it for subsequent commits. No manual binary installation required.

If you already have heelercli installed on your PATH, you can use the heelercli hook ID instead, which calls the system binary directly.

Step 4: Activate the hooks

Install the git hooks in your repository:

pre-commit install

This registers the hooks so they run automatically on every git commit.

Step 5: Verify the setup

Test that the hook is working:

# Stage any file
git add .

# Attempt a commit — the heelercli hook should run
git commit -m "test: verify heelercli hook"

You should see output from the heelercli (auto-install) hook. On first run, it will download the binary. Subsequent commits use the cached version.

Optional: Policy configuration

For teams that want to enforce specific security policies (e.g., fail on critical vulnerabilities, block certain licenses), you can add a .heeler.yaml file to your repository root. The CLI auto-discovers this file and applies the policy rules to all scans.

# Copy the example policy file to get started
cp .heeler.yaml.example .heeler.yaml

# Validate your policy file
heelercli policy validate

# View the effective resolved policy
heelercli policy explain

The policy file supports vulnerability severity gates, license allowlists, suppression rules with expiry dates, and named profiles. Contact your Heeler account team for guidance on configuring policies for your organization.

---

CLI Command Reference

heelercli secrets

Scan a repository for exposed secrets, tokens, credentials, and API keys. This command does not require authentication — it works out of the box.

heelercli secrets [flags]

Flag	Description
--pre-commit	Scan only staged changes (used automatically by the pre-commit hook)
--exclude <pattern>	Exclude paths matching a glob pattern (repeatable)
--fail-on <types>	Fail only on specific secret types, e.g. aws,github,slack
--only-validated	Show only validated findings (reduces noise)

Examples:

# Scan the full repo, excluding build output
heelercli secrets --exclude "dist/**" --exclude "vendor/**"

# Fail only on AWS and GitHub secrets
heelercli secrets --fail-on aws,github

# Show only validated findings
heelercli secrets --only-validated

---

heelercli vulnerabilities

Scan dependencies for known CVEs. Auto-discovers dependency manifests, generates SBOMs, and evaluates findings against your policy.

heelercli vulnerabilities [flags]

Flag	Description
--fail-on-any	Fail if any vulnerability is found
--fail-on-severity <severities>	Fail on specific severities, e.g. critical,high
--fail-on-id <ids>	Fail on specific CVE/GHSA IDs
--baseline <path>	Baseline findings JSON for diff/regression mode
--new-findings-only	Only fail on findings not in the baseline
--exclude-dir <paths>	Exclude directories from scanning (repeatable)
--format <format>	Output format: detailed, table, json, sarif, llm
--output <path>	Write output to file

Examples:

# Fail on critical and high severity
heelercli vulnerabilities --fail-on-severity critical,high

# Regression mode — only new issues since baseline
heelercli vulnerabilities --baseline .heeler-baseline-vulns.json --new-findings-only

# JSON output for CI integration
heelercli vulnerabilities --format json --output vulns.json

---

heelercli licenses

Check dependencies for license compliance violations.

heelercli licenses [flags]

Flag	Description
--ok <licenses>	Accepted SPDX licenses (allowlist)
--fail-on <licenses>	SPDX licenses that always fail, e.g. GPL-3.0-only
--unknown-license-policy <allow|fail>	How to handle unknown/missing licenses (default: allow)
--exclude-dir <paths>	Exclude directories from scanning
--format <format>	Output format: detailed, table, json, sarif, llm
--output <path>	Write output to file

Examples:

# Check licenses with an allowlist
heelercli licenses --ok MIT,Apache-2.0 --unknown-license-policy fail

# Print the effective allowed license set
heelercli licenses valid

---

heelercli detect-malicious-packages

Detect typosquatting, malware, and other supply-chain risks in your dependencies.

heelercli detect-malicious-packages [flags]

Flag	Description
--fail-on-any	Fail if any malicious package is detected
--exclude-dir <paths>	Exclude directories from scanning
--show-dependency-paths	Include dependency path details (default: true)
--format <format>	Output format: detailed, table, json, sarif, llm
--output <path>	Write output to file

Examples:

# Fail the build if any malicious package is found
heelercli detect-malicious-packages --fail-on-any

# JSON output for CI
heelercli detect-malicious-packages --format json --output malicious.json

---

heelercli ci (alias: pre-commit)

Run multiple checks in a single command. Generates SBOMs once and reuses them across vulnerability, license, and malicious package checks. Also runs secrets scanning.

heelercli ci [flags]

Flag	Description
--checks <checks>	Checks to run: vulnerabilities, licenses, malicious-packages, secrets (default: all)
--exclude-dir <paths>	Exclude directories from all checks
--format <format>	Output format: detailed, json, sarif
--output <path>	Write combined output to file
--sarif-findings <failing|all>	For SARIF output, include only failing or all findings

Per-check policy flags are also available (e.g., --vulnerabilities-fail-on-severity, --licenses-ok, --malicious-fail-on-any, --secrets-pre-commit). See heelercli ci --help for the full list.

Examples:

# Run all checks with default policy
heelercli ci

# Run only vulnerability and secrets checks
heelercli ci --checks vulnerabilities,secrets

# SARIF output for GitHub Code Scanning
heelercli ci --format sarif --output results.sarif

---

heelercli assess-sbom

Assess an existing CycloneDX JSON SBOM file for vulnerabilities.

heelercli assess-sbom --sbom ./sbom.json [flags]

Flag	Description
--sbom <path>	Path to CycloneDX JSON SBOM file (required)
--format <format>	Output format: detailed, table, json, sarif
--output <path>	Write output to file

---

heelercli get-recommended-version

Get the recommended version for a package — the most-used version in your environment with no active vulnerabilities.

heelercli get-recommended-version <package-name> --package-ecosystem <ecosystem>

Flag	Description
--package-ecosystem <ecosystem>	Package ecosystem: NPM, PYPI, MAVEN, etc. (required)
--format <format>	Output format: detailed, json

Examples:

heelercli get-recommended-version lodash --package-ecosystem NPM
heelercli get-recommended-version requests --package-ecosystem PYPI

---

heelercli download-sbom

Download a platform-generated SBOM for a service or application.

# By service ID
heelercli download-sbom --service_id <id>

# By application ID
heelercli download-sbom --application_id <id>

---

heelercli policy

Policy-as-code management commands for local verification.

Subcommand	Description
policy validate	Validate policy file syntax and schema
policy explain	Print the effective resolved policy (after profile overrides)
policy test --findings <path>	Test vulnerability findings against the effective policy
policy import-snyk --input .snyk	Convert .snyk ignore rules into .heeler.yaml suppressions
policy set-baseline --baseline <path>	Update baseline settings in the policy config

Examples:

# Validate your policy file
heelercli policy validate

# Show the effective policy for a profile
heelercli policy explain --profile strict

# Test findings against policy
heelercli policy test --findings findings.json --baseline baseline.json

# Migrate from Snyk
heelercli policy import-snyk --input .snyk --output .heeler.yaml

---

heelercli login

Authenticate to the Heeler platform.

# Save base URL only
heelercli login https://app.heeler.com

# Save base URL and validate/save API key
heelercli login https://app.heeler.com HEELER_API_KEY

---

heelercli version

Print the CLI version.

heelercli version

---

Global flags

Flag	Description
-h, --help	Show help
-v, --version	Print version
-q, --quiet	Suppress spinners and progress output (recommended for CI and automation)
--config <path>	Path to policy file (overrides auto-discovery)
--profile <name>	Policy profile name from config file

---

Supported ecosystems

Ecosystem	Manifest/lockfile types	Notes
C# / .NET	NuGet	Requires dotnet toolchain
Go	go.mod	Requires go toolchain
Java	pom.xml	Requires mvn and Java toolchain
JavaScript / TypeScript	npm (package-lock.json), pnpm	Requires npm or pnpm
PHP	Composer (composer.lock)	Requires composer
Python	uv.lock, poetry.lock, Pipfile.lock, requirements*.txt	Priority: uv > poetry > pipenv > requirements
Ruby	Bundler / RubyGems	Requires bundle
Rust	Cargo.lock	Requires cargo

Platform notes

OS	Architecture	Archive format
Linux	amd64, arm64	.tgz
macOS	arm64 only	.tgz
Windows	amd64	.zip

macOS note: Only arm64 binaries are published. Run your terminal natively on Apple Silicon (not under Rosetta), or the hook will fail with a clear error.

Windows note: The auto-install hook requires Git for Windows (Git Bash), which provides the POSIX shell environment (bash, curl, unzip) the hook needs.

---

Automating setup across your organization

Repo templates

Add .pre-commit-config.yaml and .heeler.yaml to your GitHub (or GitLab) repository template. Every new repository created from the template will include the Heeler hook configuration from day one.

my-repo-template/
  .pre-commit-config.yaml   # heelercli-auto hook
  .heeler.yaml               # org-wide security policy
  ...

Bootstrap script

Create a developer setup script that installs dependencies and activates hooks. Include this in your repo's Makefile or as a standalone script:

Makefile example:

.PHONY: setup
setup:
	pip install pre-commit
	pre-commit install
	@echo "Heeler pre-commit hooks activated."

Standalone script (scripts/dev-setup.sh):

#!/usr/bin/env bash
set -euo pipefail

echo "Installing pre-commit framework..."
pip install pre-commit

echo "Activating git hooks..."
pre-commit install

echo "Done. Heeler security scanning is active for this repository."

Add a note to your repo's README:

## Developer Setup

After cloning, run:

​```bash
make setup
​```

Global git hooks

For machine-wide enforcement without per-repo configuration, use the provided installer script:

# Download the installer
curl -fsSL https://raw.githubusercontent.com/Heeler-Security/heelercli/main/install-heelercli-precommit.sh -o install-heelercli-precommit.sh
chmod +x install-heelercli-precommit.sh

# Install globally (applies to all repositories on this machine)
./install-heelercli-precommit.sh --global

This sets core.hooksPath in your global git config (defaults to ~/.git-hooks) and installs a pre-commit hook that runs heelercli on every commit in every repository.

To uninstall:

./install-heelercli-precommit.sh --global --uninstall

CI/CD enforcement

Add a GitHub Actions workflow to enforce checks even if developers skip local hooks. This ensures nothing slips through.

.github/workflows/heeler.yml:

name: Heeler Security Checks

on:
  pull_request:
  push:
    branches: [main]

jobs:
  heeler:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install heelercli
        run: |
          curl -fsSL https://github.com/Heeler-Security/heelercli/releases/latest/download/heelercli-linux-amd64.tgz | tar xz
          chmod +x heelercli
          echo "$PWD" >> $GITHUB_PATH

      - name: Run all security checks
        env:
          HEELER_API_KEY: ${{ secrets.HEELER_API_KEY }}
        run: heelercli ci --format sarif --output results.sarif -q

      - name: Upload SARIF results
        if: always()
        uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: results.sarif

Store your HEELER_API_KEY as a repository or organization secret in GitHub.

---

Environment variable reference

Variable	Description
HEELER_API_KEY	API key for Heeler platform (overrides config file)
HEELER_PROFILE	Policy profile name (overrides --profile flag)
HEELERCLI_VERSION	Pin a specific release version for the auto-install hook (default: latest)
HEELERCLI_CACHE_DIR	Override the binary cache directory
HEELERCLI_FULL_SECRETS_SCAN	Set to 1 to force full-repo scan mode in the hook
HEELERCLI_SECRETS_ONLY_VALIDATED	Set to 1 to add --only-validated to the hook scan
HEELERCLI_SECRETS_MODE	Set to pre-commit or full to select scan mode
XDG_CACHE_HOME	Fallback cache location (used when HEELERCLI_CACHE_DIR is not set)

---

Troubleshooting

"heelercli is not on PATH"

If using the heelercli (system) hook, ensure the binary is installed and available on your PATH. If using heelercli-auto, this is handled automatically.

Authentication errors

Verify your API key is configured:

# Check if the config file exists
cat ~/.config/heeler/config.json

# Or set the environment variable
export HEELER_API_KEY=your-key-here

macOS Rosetta errors

The CLI only ships arm64 macOS binaries. If you're running your terminal under Rosetta on Apple Silicon, switch to a native terminal session.

Skipping the hook temporarily

In rare cases where you need to bypass the hook (e.g., during a hotfix):

git commit --no-verify -m "hotfix: emergency patch"

Use --no-verify sparingly. CI enforcement (see above) ensures checks still run on the server side.