# 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](https://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.

```bash
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):

```bash
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](https://pre-commit.com/) is a framework for managing git pre-commit hooks. Install it with pip:

```bash
pip install pre-commit
```

Verify the installation:

```bash
pre-commit --version
```

### Step 3: Add the hook configuration

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

```yaml
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:

```bash
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:

```bash
# 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.

```bash
# 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.

```bash
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:**

```bash
# 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.

```bash
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:**

```bash
# 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.

```bash
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:**

```bash
# 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.

```bash
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:**

```bash
# 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.

```bash
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:**

```bash
# 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.

```bash
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.

```bash
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:**

```bash
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.

```bash
# 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:**

```bash
# 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.

```bash
# 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.

```bash
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](https://gitforwindows.org/) (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:**

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

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

```bash
#!/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:

````markdown
## Developer Setup

After cloning, run:

​```bash
make setup
​```
````

#### Global git hooks

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

```bash
# 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:

```bash
./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`:**

```yaml
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:

```bash
# 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):

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

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