---
title: "StackHawk CLI"
description: "HawkScan is the StackHawk CLI for dynamic application security testing (DAST)."
url: https://docs.stackhawk.com/stackhawk-cli/
---

# StackHawk CLI

The StackHawk CLI, `hawk`, also known as *HawkScan*, is a command-line tool for performing dynamic application security tests.

The StackHawk CLI has many sub commands, most notably [hawk scan](#hawk-scan), which can be used to perform a DAST vulnerability scan of your running web application, just like using the [`stackhawk/hawkscan`](https://hub.docker.com/r/stackhawk/hawkscan) Docker image.

The StackHawk CLI will use valid [stackhawk.yml](https://docs.stackhawk.com/hawkscan/configuration/) files to configure the scan behavior.

See the [usage](#usage) section to learn more about running CLI commands, and how to optionally configure the scanner with environment variables. Details of specific commands and their controls can be found in the [commands](#commands) section.

## QuickStart

Visit the [Install & Run HawkScan](https://docs.stackhawk.com/getting-started/install-and-run/) guide to complete your first scan with the StackHawk CLI.

Visit the [Downloads](https://docs.stackhawk.com/downloads/) page to get HawkScan on the command line or in your pipeline.

## Docker vs. CLI

The [HawkScan Docker image](https://hub.docker.com/r/stackhawk/hawkscan) contains the StackHawk CLI and the [ENTRYPOINT](https://docs.docker.com/reference/dockerfile/#entrypoint) for the container is the `hawk scan` command.

The StackHawk CLI and HawkScan Docker image are released on the same versioning cycle and are feature compatible.

For most CI/CD pipelines, the CLI, installed with the [install script](#install-with-a-script), is the simplest choice: it needs no Docker daemon and installs the latest release on every run. The HawkScan Docker image suits pipelines that run each step as a container image, such as Kubernetes Jobs. The dependency on Docker can be prohibitive—for instance, when running from your local machine or in CI/CD environments without Docker-in-Docker support. Depending on your OS, an entire virtual machine may be required to run Docker.

Docker can also present some networking issues when trying to scan applications listening on localhost, which is common for local web development.

The CLI is ideal for those learning to use HawkScan and are trying to configure their `stackhawk.yml` configuration files. Most commands including `hawk scan` will run faster with the CLI than Docker due to lower runtime overhead in most operating systems. This lower overhead makes the CLI well-suited for testing `stackhawk.yml` configuration files locally, as well as for iterating on complex scan configurations like [scripted authentication](https://github.com/kaakaww/hawkscan-examples#authentication-and-session-management-scripts).

## Installation Overview

As of HawkScan 6.0.0, `hawk` ships as a **self-contained native binary** — no Java installation required. Download the binary for your platform, make it executable, and run it. A trimmed Java runtime is bundled inside and extracted to `~/.hawk/bin/` on first launch.

Visit the [Downloads](https://docs.stackhawk.com/downloads/) page to get the right binary for your OS and architecture.

Which install method to use:

- **On your own machine:** use [Homebrew](#install-with-homebrew-macos) on macOS, the [install script](#install-with-a-script) on Linux, and the [MSI installer](#install-with-msi-windows) on Windows. Homebrew and the MSI put `hawk` on your PATH and update cleanly.
- **In CI/CD pipelines, containers, and other automation:** use the [install script](#install-with-a-script). It needs no `sudo` or administrator access, verifies the download’s checksum, and installs the latest release unless you pin a version. On GitHub Actions and Azure Pipelines, the [HawkScan GitHub Action](https://docs.stackhawk.com/integrations/ci-cd/github-actions/) and the [Azure extension](https://docs.stackhawk.com/integrations/ci-cd/azure/azure-extension/) install `hawk` for you.
- **Air-gapped or mirrored environments:** download the binary yourself and check its checksum, as described in [Install Programmatically](#install-programmatically).

### Prerequisites

**File Access Requirements**

HawkScan writes its configuration, scan logs, and session state to `~/.hawk`, which is under the `HOME` directory. HawkScan requires read/write access to the `HOME` directory; operating systems or controlled runtimes that lock down access to this directory cannot run HawkScan.

### Install with a Script

StackHawk publishes a hawk CLI install script for each platform:

| Platform | Script |
| - | - |
| macOS and Linux | `https://download.stackhawk.com/hawk/install.sh` |
| Windows (PowerShell) | `https://download.stackhawk.com/hawk/install.ps1` |
| Windows (cmd.exe) | `https://download.stackhawk.com/hawk/install.bat`, which runs `install.ps1` |

Each script detects your OS and architecture, downloads the latest HawkScan release, checks the download’s SHA-256 checksum against the published value, installs `hawk` to `~/.hawk/bin` (`%USERPROFILE%\.hawk\bin` on Windows), and then runs `hawk version`. It needs no `sudo` or administrator access.

**The scripts never change your PATH.** The second command in each tab below adds the install directory to the PATH of your current shell, so `hawk` works right away:

**Tab: macOS/Linux**

```bash
curl -fsSL https://download.stackhawk.com/hawk/install.sh | sh
export PATH="$HOME/.hawk/bin:$PATH"
hawk version
```

**Tab: Windows (PowerShell)**

```powershell
irm https://download.stackhawk.com/hawk/install.ps1 | iex
$env:Path = "$env:USERPROFILE\.hawk\bin;$env:Path"
hawk version
```

**Tab: Windows (cmd)**

```bat
curl -fsSL -o "%TEMP%\hawk-install.bat" https://download.stackhawk.com/hawk/install.bat && call "%TEMP%\hawk-install.bat"
set "PATH=%USERPROFILE%\.hawk\bin;%PATH%"
hawk version
```

To keep `hawk` on your PATH in new shells, add the `export` line to your shell profile (for example `~/.bashrc` or `~/.zshrc`). On Windows, the script prints a command that saves the install directory to your user PATH.

The scripts read two environment variables:

| Variable | Default | Description |
| - | - | - |
| `HAWK_INSTALL_VERSION` | The latest release, read from `https://api.stackhawk.com/hawkscan/version` | The HawkScan version to install, for example `6.6.0`. Any version from 6.0.0 onward works. |
| `HAWK_INSTALL_DIR` | `~/.hawk/bin` (`%USERPROFILE%\.hawk\bin` on Windows) | The directory to install `hawk` into. On Windows it cannot be under `Program Files`, which belongs to the MSI installer. |

For example, to install HawkScan 6.6.0 into `/usr/local/bin`, which is already on the PATH, in a Dockerfile or golden image:

```bash
curl -fsSL https://download.stackhawk.com/hawk/install.sh | HAWK_INSTALL_VERSION=6.6.0 HAWK_INSTALL_DIR=/usr/local/bin sh
```

In PowerShell, set `$env:HAWK_INSTALL_VERSION = '6.6.0'` before you run the script. In cmd.exe, run `set "HAWK_INSTALL_VERSION=6.6.0"` first.

**Latest or pinned?** Leave `HAWK_INSTALL_VERSION` unset and every run installs the newest release, so your pipelines pick up scanner fixes and new tests without anyone editing them. Set it when you need the same scanner version on every run. An installed `hawk` does not upgrade itself in CI (see [hawk upgrade](#hawk-upgrade)), so “latest” means the latest release at install time.

**Requirements.** `install.sh` needs `curl`, `mktemp`, and `sha256sum` or `shasum`. It supports Linux (x64 and arm64) and macOS (Intel and Apple Silicon). The Linux binaries need glibc, so they don’t run on Alpine Linux or other musl-based images; in containers, use a Debian- or Ubuntu-based image. `install.ps1` needs Windows PowerShell 5.1 or later and supports Windows x64 and arm64. `install.bat` also needs `curl.exe`, which ships with Windows 10 version 1803 and later and Windows Server 2019 and later.

**Already have `hawk`?** If another copy of `hawk` is on your PATH, for example from Homebrew, the pkg installer, or the MSI, the script warns you that you will have two copies. Use `hawk upgrade` to update the copy you already have instead.

For CI/CD examples on each platform, see [Automate (CI/CD)](https://docs.stackhawk.com/integrations/ci-cd/#the-hawk-cli).

## MacOS Install

MacOS users may install the StackHawk CLI using [Homebrew](#install-with-homebrew-macos) or our [pkg installer](#install-with-pkg-macos). For a per-user install with no `sudo`, use the [install script](#install-with-a-script).

#### Install with HomeBrew (MacOS)

To install the latest version of the StackHawk CLI with [Homebrew](https://brew.sh/), you’ll need to install the [StackHawk Tap](https://github.com/stackhawk/homebrew-cli) and the CLI tool `hawk`.

Tap, trust, then install:

```shell title="brew tap install"
brew tap stackhawk/cli
brew trust stackhawk/cli
brew install hawk
```

`brew trust` tells Homebrew it may load formulae from this third-party tap. It is required when `HOMEBREW_REQUIRE_TAP_TRUST` is set, and becomes mandatory for all non-official taps in Homebrew 6.0.0 (or 5.2.0).

#### Install with Pkg (MacOS)

The pkg installer includes the self-contained `hawk` binary and adds `hawk` to your PATH automatically.

You can install it from the [downloads page](https://download.stackhawk.com), or from the command line:

```shell
# download the latest .pkg installer for your architecture
VERSION=$(curl -fsSL https://api.stackhawk.com/hawkscan/version)
case "$(uname -m)" in
  arm64)  PLATFORM=darwin-arm64 ;;
  x86_64) PLATFORM=darwin-x64 ;;
  *) echo "Unsupported architecture: $(uname -m)"; exit 1 ;;
esac
curl -fL "https://download.stackhawk.com/hawk/${VERSION}/${PLATFORM}/hawk.pkg" -o hawk.pkg
# install HawkScan
sudo installer -pkg hawk.pkg -target /
```

> **Note:** **NOTE:** Because HawkScan reads and writes state from the `~/.hawk` directory, users may be prompted that HawkScan on macOS will need to access ‘Photos, Apple Music, Documents’ directories. Because these are also directories under HOME and macOS security is explicit, installing HawkScan on macOS requires allowing access to these folders when prompted for the first time.

## Linux Install

Install `hawk` with the [install script](#install-with-a-script), then add it to your PATH:

```bash
curl -fsSL https://download.stackhawk.com/hawk/install.sh | sh
export PATH="$HOME/.hawk/bin:$PATH"
```

Add the `export` line to your shell profile, such as `~/.bashrc`, to keep `hawk` on your PATH in new shells.

To install the binary by hand instead, for example on a machine that can’t run the script, see [Verify your download](#verify-your-download).

## Windows Install

Windows users may install the StackHawk CLI using our [msi installer](#install-with-msi-windows), which installs `hawk` for all users and adds it to the system PATH. For a per-user install with no administrator access, or to install `hawk` in automation, use the [install script](#install-with-a-script): `install.ps1` for PowerShell, or `install.bat` for cmd.exe.

> **Note:** **NOTE:** PowerShell and other Windows terminals may not support [UTF-8](https://www.utf8.com/) encoding by default. HawkScan can still be used, but the terminal output may appear garbled. There are a few workarounds:

- HawkScan Users can toggle the `no-color=true` [command option](#command-options) to disable color and control sequences in HawkScan output.
- Windows users can use the [Windows terminal](https://apps.microsoft.com/store/detail/windows-terminal/9N0DX20HK701) with unicode support.
- Windows users *should* change their regional language locale to use UTF-8 for worldwide language support. Run `intl.cpl`, and under the *Administrative* tab, select *Change system locale* and enable `Beta: Use Unicode UTF-8 for worldwide language support`.

### Install with MSI (Windows)

The msi installer is the most convenient way for Windows users to install HawkScan. It includes the self-contained `hawk` binary and adds `hawk` to your PATH automatically.

You can install it from the [downloads page](https://download.stackhawk.com), or from PowerShell:

```ps1
# download and install the .msi installer
$ProgressPreference = 'SilentlyContinue'   # large download; progress rendering is slow on PS 5.1
$Version  = (Invoke-WebRequest https://api.stackhawk.com/hawkscan/version -UseBasicParsing).Content.Trim()
$Platform = if ([System.Runtime.InteropServices.RuntimeInformation]::OSArchitecture -eq 'Arm64') { 'windows-arm64' } else { 'windows-x64' }
Invoke-WebRequest "https://download.stackhawk.com/hawk/$Version/$Platform/hawk.msi" -OutFile hawk.msi -UseBasicParsing
Start-Process msiexec.exe -ArgumentList "/i hawk.msi /passive" -Wait
```

## Install Programmatically

For most CI/CD pipelines, provisioning scripts, and container images, the [install script](#install-with-a-script) is the simplest programmatic install: it resolves the version, picks the right binary, and checks its checksum for you. Use the endpoints and paths below when you need to download a binary yourself, for example to mirror it into an air-gapped network or to install the `.pkg` or `.msi` installers.

HawkScan publishes two public endpoints for discovering the current release. Neither requires an API key.

| Endpoint | Returns |
| - | - |
| `https://api.stackhawk.com/hawkscan/version` | The current release version as plain text, for example `6.6.0`. Use this when you just need a version string and don’t want a JSON parser. Note that this endpoint is served with a `Content-Type: application/json` header even though the body is a bare version string — read it as text, don’t pipe it to `jq`. |
| `https://download.stackhawk.com/hawkdocs/hawk.manifest.json` | Full release metadata — the download URL, SHA-256 checksum, and file size for every published asset, under a `latest` and a `dev` release. Use this when you want to verify your download. |

Binaries and installers live at a versioned, platform-specific path:

```
https://download.stackhawk.com/hawk/<VERSION>/<PLATFORM>/<FILE>
```

### Platforms

| Operating system | Architecture | `<PLATFORM>` | Available `<FILE>` |
| - | - | - | - |
| macOS | Apple Silicon | `darwin-arm64` | `hawk`, `hawk.pkg` |
| macOS | Intel | `darwin-x64` | `hawk`, `hawk.pkg` |
| Linux | x86_64 | `linux-x64` | `hawk` |
| Linux | arm64 | `linux-aarch64` | `hawk` |
| Windows | x64 | `windows-x64` | `hawk.exe`, `hawk.msi` |
| Windows | arm64 | `windows-arm64` | `hawk.exe`, `hawk.msi` |

> **Note:** **NOTE:** The arm64 naming differs by platform. Linux uses `linux-aarch64`, while macOS and Windows use `darwin-arm64` and `windows-arm64`.

### Verify your download

Every published asset has a sidecar manifest at `<FILE>.manifest.json` containing its SHA-256 checksum. Verifying the checksum is recommended for any automated install.

**Tab: macOS/Linux**

```bash
VERSION=$(curl -fsSL https://api.stackhawk.com/hawkscan/version)
case "$(uname -s)/$(uname -m)" in
  Darwin/arm64)              PLATFORM=darwin-arm64 ;;
  Darwin/x86_64)             PLATFORM=darwin-x64 ;;
  Linux/x86_64)              PLATFORM=linux-x64 ;;
  Linux/aarch64|Linux/arm64) PLATFORM=linux-aarch64 ;;
  *) echo "Unsupported platform: $(uname -s)/$(uname -m)"; exit 1 ;;
esac
URL="https://download.stackhawk.com/hawk/${VERSION}/${PLATFORM}/hawk"

curl -fL "$URL" -o hawk
EXPECTED=$(curl -fsSL "${URL}.manifest.json" | grep -oE '"sha256"[[:space:]]*:[[:space:]]*"[^"]*"' | cut -d'"' -f4)
[ -n "$EXPECTED" ] || { echo "Could not read a checksum from ${URL}.manifest.json"; exit 1; }

# sha256sum on most Linux distros, shasum on macOS
if command -v sha256sum >/dev/null; then
  ACTUAL=$(sha256sum hawk | cut -d' ' -f1)
else
  ACTUAL=$(shasum -a 256 hawk | cut -d' ' -f1)
fi
[ "$ACTUAL" = "$EXPECTED" ] || { echo "Checksum mismatch for $URL"; exit 1; }

chmod +x hawk
sudo mv hawk /usr/local/bin/hawk
```

**Tab: Windows**

```powershell
$ProgressPreference = 'SilentlyContinue'   # large download; progress rendering is slow on PS 5.1
$Version  = (Invoke-WebRequest https://api.stackhawk.com/hawkscan/version -UseBasicParsing).Content.Trim()
$Platform = if ([System.Runtime.InteropServices.RuntimeInformation]::OSArchitecture -eq 'Arm64') { 'windows-arm64' } else { 'windows-x64' }
$Url      = "https://download.stackhawk.com/hawk/$Version/$Platform/hawk.exe"

Invoke-WebRequest $Url -OutFile hawk.exe -UseBasicParsing
# Get-FileHash returns uppercase hex; the manifest stores lowercase
$Expected = (Invoke-RestMethod "$Url.manifest.json").sha256.ToLower()
$Actual   = (Get-FileHash hawk.exe -Algorithm SHA256).Hash.ToLower()

# remove the bad download before failing, so no unverified hawk.exe is left behind
if ($Actual -ne $Expected) { Remove-Item hawk.exe -Force; throw "Checksum mismatch for $Url" }

# same directory the install script uses
$Dest = "$env:USERPROFILE\.hawk\bin"
New-Item -ItemType Directory -Force -Path $Dest | Out-Null
Move-Item hawk.exe $Dest -Force
# add $Dest to your PATH, or use the MSI installer above, which does it for you
```

> CMD users: run [`install.bat`](#install-with-a-script), which downloads `hawk.exe` and checks its checksum for you.

### Pin to a specific version

With the [install script](#install-with-a-script), set `HAWK_INSTALL_VERSION`:

```bash
curl -fsSL https://download.stackhawk.com/hawk/install.sh | HAWK_INSTALL_VERSION=6.6.0 sh
```

For a manual download, replace the version lookup with a literal version:

```bash
VERSION=6.6.0
case "$(uname -s)/$(uname -m)" in
  Darwin/arm64)              PLATFORM=darwin-arm64 ;;
  Darwin/x86_64)             PLATFORM=darwin-x64 ;;
  Linux/x86_64)              PLATFORM=linux-x64 ;;
  Linux/aarch64|Linux/arm64) PLATFORM=linux-aarch64 ;;
  *) echo "Unsupported platform: $(uname -s)/$(uname -m)"; exit 1 ;;
esac
curl -fL "https://download.stackhawk.com/hawk/${VERSION}/${PLATFORM}/hawk" -o hawk
```

An installed CLI can also upgrade or pin itself — see [hawk upgrade](#hawk-upgrade). Note that `hawk upgrade` will not self-replace a standalone binary when it detects a CI environment: it prints pinning guidance and exits 0 rather than upgrading. Pipelines get new releases by installing fresh on each run, which the install script does by default, or by pinning a version as shown above.

## Usage

Once your PATH has been updated, you can use the `hawk` command.

With the `hawk` command available on the path, you can run `hawk --help/-h` to get help on the available options and commands. The `--help/-h` flag is supported by all sub commands, for example `hawk scan -h` will show help for the `scan` command.

Before going any further run [hawk init](#hawk-init) to set your StackHawk API Key, which is required for many commands.

When running a `hawk scan` command the API key you supplied to `hawk init` will be used by reading it from the `$HOME/.hawk/hawk.properties` file, or it can be supplied as an option on the command line.

```shell
hawk --api-key=xxxxx scan
```

### Command Options

Command options in the StackHawk CLI can be supplied from a file or environment variable in addition to the command line option, ie: `--option`. The property values in `$HOME/.hawk/hawk.properties` will be used if a command line option is not specified. For example if the `hawk --api-key` option is not specified the value from the `api-key=xxxx` property in the `$HOME/.hawk/hawk.properties` file will be used.

The three forms of options can be used together and will be loaded in the preference order: Command Line Option -> Environment Variable -> `hawk.properties`

See the table below for command line options:

#### Base Options

| Command Line Option | `hawk.properties` | Environment Variable | Description |
| - | - | - | - |
| `--api-key=xxxxx` | `api-key=xxxxx` | `API_KEY=xxxxx` | StackHawk Platform API key. |
| `--hawk-mem=1g` | `hawk-mem=1g` | `HAWK_MEM=1g` | Maximum memory allocation for the scanner. |
| `--no-color` | `no-color=true` | `NO_COLOR=true` | Do not use colors in the terminal output. |
| `log-roll-size` | `log-roll-size=100MB` | `LOG_ROLL_SIZE` | The roll size of the log file. |
| `log-files-count` | `log-files-count=10` | `LOG_FILES_COUNT` | The maximum number of rolled log files to upload with the scan. |

#### Advanced Scan Options

The StackHawk CLI is designed for flexibility to scan a variety of APIs.

| Command Line Option | `hawk.properties` | Environment Variable | Description |
| - | - | - | - |
| `--debug` | `debug=true` | `DEBUG=true` | Enable debug logging. |
| `--verbose` | `verbose=true` | `VERBOSE=true` | Enable logging to the foreground. |
| `--trace` | `trace=true` | `TRACE=true` | Enable trace level logging of http traffic. |
| `--hawk-mem=1g` | `hawk-mem=1g` | `HAWK_MEM=1g` | Maximum memory allocation for the scanner. |
| `--no-color` | `no-color=true` | `NO_COLOR=true` | Do not use colors in the terminal output. |
| `--no-progress` | `no-progress=true` | `NO_COLOR=true` | Do not show terminal progress bars. |
| `--session-home=..` | `session-home=..` | `SESSION_HOME=~/.hawk/sessions` | Working directory for HawkScan. |
| `--proxy-port` | `proxy-port=20000` | `PROXY_SERVER_PORT=20000` | Starts the scanner proxy on the given port. |
| `--enable-preflight` | `enable-preflight=true` | `ENABLE_PREFLIGHT=true` | toggles Preflight Checks - advanced monitoring for conditions of hosted web applications that may lead to incomplete or failed scans. |
| `--profile-scan-mode=business-logic` | `profile-scan-mode=business-logic` | `PROFILE_SCAN_MODE=business-logic` | How to distribute plugin coverage across authentication profiles: `business-logic` (default), `primary-full`, or `all-full`. See [Multi-Profile Testing](https://docs.stackhawk.com/hawkscan/business-logic-testing/#choosing-scan-coverage-per-profile). |
| `--full-scan-profile=admin` | `full-scan-profile=admin` | `FULL_SCAN_PROFILE=admin` | Which authentication profile receives the full scan policy under `--profile-scan-mode=primary-full`. Defaults to the first profile declared in your configuration. |
| `--log-http` | `log-http=true` | `LOG_HTTP=true` | When enabled, it will log all HTTP requests and responses. |
| `--hawk-jvm-opts=-Xmx2g` | `hawk-jvm-opts=-Xmx2g` | `HAWK_JVM_OPTS=-Xmx2g` | JVM options to pass into the scanner process. |
| `--git-url=https://...` | `git-url=https://...` | `HAWK_GIT_URL=https://...` | URL of the git repository to scan; instructs HawkScan to clone this repo before starting scan. |
| `--git-rev=main` | `git-rev=main` | `HAWK_GIT_REV=main` | Revision or branch of the git repo to checkout. Defaults to HEAD if unspecified. |
| `--git-dev=main` | `git-dev=main` | `HAWK_GIT_DEV=main` | Git branch to use from the specified `--git-url`. |
| `--sarif-artifact` | `sarif-artifact=true` | `SARIF_ARTIFACT=true` | Save results in Sarif format upon scan completion. |
| `--sarif-ghas` | `sarif-ghas=true` | `SARIF_GHAS=true` | Save results as `stackhawk-ghas.sarif`, a SARIF file that GitHub Advanced Security code scanning accepts. See [GitHub Code Scanning](https://docs.stackhawk.com/integrations/ci-cd/github-actions/github-code-scanning/#upload-individual-findings-as-sarif). Available in HawkScan 6.6.0 and later. |
| `--json-output` | | | Output scan results as a single JSON object to stdout, suppressing all other console output. Cannot be used with `--trace`. |
| `--application-id=xxxx` | `application-id=xxxx` | `APPLICATION_ID=xxxx` | The application ID for the application being scanned. |
| `--environment-name=dev` | `environment-name=dev` | `ENVIRONMENT_NAME=dev` | The environment the application being scanned is running in. |

#### Outbound Proxy Config Options

The StackHawk CLI has first-class support for enterprise network proxies.

Starting with HawkScan 6.0.0, **OS-native certificate trust is enabled by default** — the binary automatically picks up certificates from your OS trust store (macOS Keychain, Windows Certificate Store, Linux system PEM bundle). This means most transparent/intercepting proxies (Zscaler, Netskope, corporate CAs) work with no configuration. See [OS-Native Certificate Trust](https://docs.stackhawk.com/hawkscan/6-0-0/#os-native-certificate-trust) for details.

For proxies that require explicit credentials or a custom CA cert file, use the `--outbound-proxy-*` options below.

> **Note:** These outbound-proxy options apply to `hawk scan` and can be set via a command-line flag, an environment variable, or `hawk.properties` (see the table below). The `hawk init` command exposes its own, narrower set of proxy flags — basic auth with an optional PEM CA certificate only. See [`hawk init`](#hawk-init).

| Command Line Option | `hawk.properties` | Environment Variable | Description |
| - | - | - | - |
| `--outbound-proxy-host=host:port` | `outbound-proxy-host=host:port` | `OUTBOUND_PROXY_HOST=host:port` | The host of the outbound proxy, including port (e.g. <https://localhost:8888>) |
| `--outbound-proxy-username=username` | `outbound-proxy-username=username` | `OUTBOUND_PROXY_USERNAME=username` | Username for outbound proxy authentication. |
| `--outbound-proxy-password=password` | `outbound-proxy-password=password` | `OUTBOUND_PROXY_PASSWORD=password` | Password for outbound proxy authentication. |
| `--outbound-proxy-auth-scheme=scheme` | `outbound-proxy-auth-scheme=scheme` | `OUTBOUND_PROXY_AUTH_SCHEME=scheme` | Authentication scheme for outbound proxy credentials: `NTLM` or `BASIC`. |
| `--outbound-proxy-ca-cert-path=/path/to/cert` | `outbound-proxy-ca-cert-path=/path/to/cert` | `OUTBOUND_PROXY_CA_CERT_PATH=/path/to/cert` | Path to a root CA certificate file for transparent proxies. Use when the proxy CA is not in your OS trust store. |
| `--ssl-trust-store=/path/to/truststore` | `ssl-trust-store=/path/to/truststore` | `SSL_TRUST_STORE=/path/to/truststore` | Path to a custom SSL truststore file (e.g., /path/to/truststore.jks). |
| `--ssl-trust-store-type=type` | `ssl-trust-store-type=type` | `SSL_TRUST_STORE_TYPE=type` | Type of SSL truststore (e.g., PKCS12, JKS). |
| `--ssl-trust-store-password=password` | `ssl-trust-store-password=password` | `SSL_TRUST_STORE_PASSWORD=password` | Password for the custom SSL truststore. |
| `--no-native-truststore` | `use-native-truststore=false` | `USE_NATIVE_TRUSTSTORE=false` | Disable OS-native certificate trust. Reverts to bundled-roots-only behavior. Enabled by default since HawkScan 6.0.0. |

The SSL truststore options control which **server** certificates HawkScan trusts. To have HawkScan present a **client** certificate to your application (mutual TLS), see [Mutual TLS (Client Certificates)](https://docs.stackhawk.com/hawkscan/configuration/#mutual-tls-client-certificates).

**Diagnosing certificate trust**

HawkScan logs one line describing what OS-native trust resolution produced, which is the quickest way to confirm your proxy or enterprise CA was actually picked up:

```
OS-native trust: source=launcher-bundle(/tmp/hawk-os-ca-bundle.pem), proxyCAs=1, store=/tmp/hawk-truststore123.jks, anchors=145
OS-native trust: source=none — using the JRE default truststore
```

If the merged trust store cannot be read back after it is built, HawkScan warns and falls back to its bundled certificate roots rather than scanning with no trust at all. Should a handshake still fail, `--outbound-proxy-ca-cert-path` names your proxy CA explicitly.

## Commands

The CLI is the top level command `hawk` which has several sub commands.

### `hawk`

The `hawk` root command doesn’t take any action on its own but does have options that can be set across multiple sub commands.

#### **Options**

- `--api-key=xxxxx` - StackHawk API Key can be supplied at runtime for any sub command’s usage.
- `--num-stored-sessions=4` - The number of sessions to persist in the .hawk/sessions directory. (default: 4)
- `--log-roll-size=100mb` - The roll size of the log file. (default: 100MB)
- `--no-color` - Do not use colors in the terminal output.

**Example**

```shell
hawk --no-color scan
```

### `hawk init`

`hawk init` will prompt you for a StackHawk API key which will be validated then stored in the file `$HOME/.hawk/hawk.properties`, which will be created if it does not exist. The property `api-key` from `$HOME/.hawk/hawk.properties` will be used whenever a `hawk` command is run instead of requiring the usage of the `--api-key=xxxx` option.

**Examples**

Basic usage — interactive prompt (choose browser login or manual key entry):

```shell
hawk init
```

Non-interactive browser login (skips all TTY prompts, always prints the auth URL — ideal for CI and agents):

```shell
hawk init --browser
```

Supply a key directly without interactive prompts:

```shell
hawk init --api-key=xxxx
```

Authenticate through an outbound proxy:

```shell
hawk init --api-key=xxxx --outbound-proxy-host proxy.corp:8080 --outbound-proxy-username $PROXY_USERNAME --outbound-proxy-password $PROXY_PASSWORD --outbound-proxy-auth-scheme basic
```

#### **Options**

- `--api-key=xxxx` - Skip the terminal prompt and set the `api-key` property in the `$HOME/.hawk/hawk.properties` file. Also settable via the `API_KEY` environment variable.
- `--browser` - Non-interactive device-flow login. Skips the existing-key confirmation and auth-method menu, opens the browser, and always prints the authentication URL to stdout. If running headless (no display), the browser launch is silently skipped but the URL is still printed — capture it from stdout to complete authentication.
- `--debug` - Print HTTP request/response details for troubleshooting authentication.
- `--outbound-proxy-host` - Host and port of an outbound proxy, e.g. `proxy.corp:8080`. A scheme is optional — `http://` is assumed when none is given. Env: `OUTBOUND_PROXY_HOST`.
- `--outbound-proxy-username` - Username for outbound proxy authentication. Env: `OUTBOUND_PROXY_USERNAME`.
- `--outbound-proxy-password` - Password for outbound proxy authentication. Env: `OUTBOUND_PROXY_PASSWORD`.
- `--outbound-proxy-auth-scheme` - Outbound proxy authentication scheme. Only `basic` is supported — `hawk init` does not support NTLM or digest proxy authentication. If your proxy performs TLS interception but does **not** require authentication to forward traffic, install its CA in your OS trust store and omit this flag; `hawk init` will connect through it. If your proxy **requires** NTLM or digest authentication to forward traffic, `hawk init` cannot connect through it — installing the CA does not help, because that addresses TLS trust, not proxy authentication. Run `hawk scan` instead, which uses the JVM scanner and supports NTLM and digest. Env: `OUTBOUND_PROXY_AUTH_SCHEME`.
- `--outbound-proxy-ca-cert-path` - Path to a root CA certificate (PEM) required to trust the outbound proxy. Env: `OUTBOUND_PROXY_CA_CERT_PATH`.

> **Note:** These `--outbound-proxy-*` options configure only the authentication requests `hawk init` itself makes. They support **basic auth with an optional PEM CA certificate only** — `NTLM` and JKS/PKCS12 truststores are not available here, and the settings are not written to `hawk.properties` or reused by later `hawk scan` runs. `hawk scan` has its own broader [outbound-proxy options](#outbound-proxy-config-options), which accept `NTLM` or `BASIC` and additional truststore formats.

### `hawk validate config`

Validate `stackhawk.yml` configuration files before running `hawk scan`. The `validate config` command can validate a single or multiple files merged together as supported by the `scan` command.

**Examples**

Validate `stackhawk.yml` or `stackhawk.yaml` file in the current working directory.

```shell
hawk validate config
```

Validate the `./stackhawk-dev.yml` yaml file.

```shell
hawk validate config ./stackhawk-dev.yml
```

Validate the configurations of `stackhawk.yml` and `prod/stackhawk.yml` files merged together.

```shell
hawk validate config stackhawk.yml prod/stackhawk.yml
```

**Exit codes**

`hawk validate config` exits `0` when your configuration is valid and non-zero when it is not, so it can be used directly as a CI gate:

```shell
hawk validate config stackhawk.yml && ./deploy.sh
```

A non-zero exit means a hard validation error, or a configuration file that could not be found. Warnings — such as unknown properties or [seed path lint](https://docs.stackhawk.com/hawkscan/scan-discovery/spider/) warnings — are printed but still exit `0`.

> **Note:** Before HawkScan 6.4.0, `hawk validate config` always exited `0`, even on a validation failure. If your pipeline relied on that behavior, it will now correctly fail on a broken configuration.

### `hawk validate api`

Validate the OpenAPI spec included in the `stackhawk.yml` configuration file.

**Examples**

Validate an OpenAPI spec included in a `stackhawk.yml` file.

```shell
hawk validate api
```

Validate an OpenAPI spec included in a specific configuration yml file.

```shell
hawk validate api ./stackhawk-dev.yml
```

### `hawk validate auth`

Validates authentication on your app based upon your `stackhawk.yml` configuration. Requires HawkScan to be running in daemon mode. Run hawk perch start `hawk perch start` to start the HawkScan daemon

#### **Options**

- `--watch` - Enters an interactive mode where HawkScan will monitor any changes to you `stackhawk.yml` config and any authentication scripts configured in the `stackhawk.yml`.

**Examples**

Validates authentication configured in a `stackhawk.yml` file.

```shell
hawk validate auth
```

Validates authentication configured in a specific configuration yml file.

```shell
hawk validate auth ./stackhawk-dev.yml
```

Watches for changes in a specific configuration yml and associated authentication scripts and retries authentication on saving of those files. Press `ctrl+c` to exit watch mode

```shell
hawk validate auth --watch ./stackhawk-dev.yml
```

### `hawk register plugin`

Registers a [Custom Test Script](https://docs.stackhawk.com/scripting/) by generating a Plugin Id based on the Application Id in the `stackhawk.yml` configuration file.

**Examples**

Registers a Custom Test Script by generating a Plugin Id based on the Application Id in the `stackhawk.yml` file.

```shell
hawk register plugin <plugin-name>
```

Registers a Custom Test Script by generating a Plugin Id based on an Application Id included in the referenced configuration YAML file that is not using the default `stackhawk.yml` name.

```shell
hawk register plugin <plugin-name> ./stackhawk-dev.yml
```

### `hawk list plugin`

Lists all the names and IDs of your [Custom Test Scripts](https://docs.stackhawk.com/scripting/). By default, the Custom Test Scripts or plugins will be listed based on the Application ID in the `stackhawk.yml` configuration file.

**Examples**

Lists names and IDs of plugins based on the Application ID in the `stackhawk.yml` file.

```shell
hawk list plugin
```

Lists names and IDs of plugins based on the Application ID included in the referenced configuration YAML file that is not using the default `stackhawk.yml` name.

```shell
hawk list plugin ./stackhawk-dev.yml
```

Lists names and IDs of plugins based on the given Organization ID.

```shell
hawk list plugin --organization-id <organization-id>
```

### `hawk scan`

Scan your running web application or API.

The `scan` command takes stackhawk.yml configuration files as arguments, each file being merged onto the last in the order they are supplied. By default, the `stackhawk.yml` file in the current working directory will be used if no arguments are supplied.

When the scanner starts up, it will choose or apply a [Scan Policy](https://docs.stackhawk.com/platform/policy-management/policy-management-defaults/), which encompass a collection of [Vulnerability Check Plugins](https://docs.stackhawk.com/vulnerabilities/).

Scan results are coordinated by the specified application ID and environment name.

#### **Options**

- `--repo-dir` - Directory containing your `stackhawk.yml` files. Config file arguments will be searched for in this directory.

- `-e, --env` - Set variables in the `stackhawk.yml` configuration as [described here](https://docs.stackhawk.com/hawkscan/configuration/extended-configuration/#environment-variable-runtime-overrides). This argument allows multiples and is of type key/value pair, ie: `--env MY_VAR1=value1 --env MY_VAR2=value2` or `-e MY_VAR1=value1 -e MY_VAR2=value2`.

- `--env-file` - Set variables in the `stackhawk.yml` configuration as [described here](https://docs.stackhawk.com/hawkscan/configuration/extended-configuration/#environment-variable-runtime-overrides). This argument `--env-file=my-env.txt` takes a path to a file of key/value pairs with each line containing a pair.

  `--env-file` example:

  ```shell
  $ cat my-env.txt
  MY_VAR1=value1
  MY_VAR2=value2
  ```

#### **Advanced Options**

See [Advanced Scan Options](#advanced-scan-options).

#### stackhawk.yml environment variables

The `--env/-e` and `--env-file` arguments can be used to supply variable values to the `stackhawk.yml` files. For example if your `stackhawk.yml` file had `host: ${APP_HOST:http://localhost:3000}` in it using `-e APP_HOST=http://dev.example.com` that would set the `host` to `http://dev.example.com`. In this way the `scan` command’s `-e` works similarly to the docker command’s `-e`. However the `hawk` command can also use the current environment for the variables as well.

For example, given the following `stackhawk.yml` configuration, all of the commands listed will resolve the configuration file the same way.

```yaml title="stackhawk.yml"
app:
  host: ${APP_HOST:http://dev.example.com}
  env: ${APP_ENV:Test}
```

Commands:

```shell
hawk scan -e APP_HOST=http://localhost:3000 -e APP_ENV=Dev
```

```shell
APP_HOST=http://localhost:3000 APP_ENV=Dev hawk scan
```

```shell
export APP_HOST=http://localhost:3000
export APP_ENV=Dev
hawk scan
```

This allows a great degree of flexibility from environment variables to environment files for managing the flexible and secret parts of the `stackhawk.yml` configuration file.

### `hawk perch start`

Perch manages running HawkScan in a background daemon process rather than running a scan. `hawk validate auth` and `hawk perch browser` are available to run in daemon mode.

#### **Options**

- `--with-chrome` - Launches a Chrome browser which will record any traffic of you browsing.
- `--with-proxy-info` - Outputs the proxy host and port to allow testing tools to proxy through HawkScan
- `--app-host` - When using `--with-chrome`, the Chrome browser will start on this web address.

**Examples**

Starts HawkScan in a background daemon process.

```shell
hawk perch start
```

Launches a Chrome browser at <https://localhost:9000> and records user browsing

```shell
hawk perch start --with-chrome --app-host=https://localhost:9000
```

### `hawk perch stop`

Stops the background HawkScan daemon process.

#### **Options**

- `--har-file` - When specified it will save all browsing history to a specified har file, that can be used for custom scan discovery.

**Examples**

Stops the HawkScan daemon process.

```shell
hawk perch stop
```

Stops the HawkScan daemon process and saves all browsing recording from launching `--with-chrome` or from `hawk perch browser` to a file titled `recording.har`

```shell
hawk perch stop --har-file=recording.har
```

### `hawk perch status`

Checks if `hawk perch` is currently running.

Returns status information about the running HawkScan daemon process

```shell
hawk perch status
```

### `hawk perch browser`

Starts a Chrome browser to record traffic through HawkScan to be saved to a file on stop. Requires `hawk perch start` to be called first.

#### **Options**

- `--app-host` - The Chrome browser will start on the supplied web address.

Launches a Chrome browser that starts at an empty web page.

```shell
hawk perch browser
```

Launches a Chrome browser at <https://localhost:9000> and records user browsing.

```shell
hawk perch browser --app-host=https://localhost:9000
```

### `hawk rescan`

Re-tests the findings from a previous scan of the Application Id in your `stackhawk.yml`. A rescan is narrowed in two ways: it runs only the plugins that alerted on the scan being re-tested, and it attacks only the requests that produced those findings.

Rather than crawling your application again, a rescan retrieves the exact requests behind the previous scan’s findings and replays them, then attacks those directly. Because of this, the discovery phase is skipped entirely — including the `base` and `ajax` spiders and any OpenAPI, SOAP, GraphQL, or HAR route imports. This makes a rescan considerably faster than a full scan and keeps it focused on the findings you are verifying.

Path-parameter routes such as `/widgets/{id}` are still attacked as parameterized endpoints, so injection findings on a path parameter reproduce as expected.

If the replay cannot run for any reason — for example the previous scan’s request data is unavailable — HawkScan falls back automatically to a normal scan with full discovery.

> **Note:** **NOTE:** Because a rescan does not crawl, it will not discover routes that were added to your application since the scan being re-tested. Run a full `hawk scan` to pick up new routes.

The `scan` command takes stackhawk.yml configuration files as arguments, each file being merged onto the last in the order they are supplied. By default, the `stackhawk.yml` file in the current working directory will be used if no arguments are supplied.

**Examples**

Runs the most recent scan for an Application based on your `stackhawk.yml` with only tests that threw alerts

```shell
hawk rescan
```

Runs a scan based on the specific scan id provided and configuration in your `stackhawk.yml`. Only tests that threw an alert will be rerun.

```shell
hawk rescan --scan-id XXxxXXXX-xXXX-xxXX-XXxX-xXXxxXXXXxXX
```

### `hawk create app`

Create StackHawk applications from the CLI.

```shell
hawk create app
```

`hawk create application` is also accepted as a valid form of the command.

Running the command without an application name as an argument will run the command in an interactive mode and will prompt the user for an application name and an environment name. If the user belongs to multiple organizations, they will be prompted for an organization ID.

#### **Options**

- `-n, --name` - Application name. Omitting this argument will cause the command to run in interactive mode.
- `-e, --env` - Environment name. `Development` by default.
- `-o, --org-id` - Organization ID. Needed if user is a member of multiple organizations.
- `-t, --team-id` - Team ID. Needed if user wants to assign an application to a team.
- `-y, --yaml` - Output a `stackhawk.yml` configuration stub to stdout after creating the application. All interactive prompts are routed to stderr so piped output contains only valid YAML.

To run the command as part of an automation script, provide the application name and other arguments. Examples:

```shell
hawk create app --name "Example App 1" --env Dev

hawk create application --name "Example App 2" --org-id XXxxXXXX-xXXX-xxXX-XXxX-xXXxxXXXXxX

hawk create app -n "Example App 3" -e Pre-Production -t XXxxXXXX-xXXX-xxXX-XXxX-xXXxxXXXXxX
```

The ID of the application will be returned as an output of the command:

```shell
$ hawk create app --name Example App 1 --env Dev
KaaKaww! Here is your new application ID:
XXxxXXXX-xXXX-xxXX-XXxX-xXXxxXXXXxX
```

Use `--yaml` to generate a starter configuration file:

```shell
$ hawk create app --name "My App" --yaml > stackhawk.yml
```

This outputs a ready-to-use `stackhawk.yml` stub with the new application ID, environment, and a placeholder host URL.

> **Note:** **NOTE:** Team IDs can be retrieved from the URL bar of a browser by navigating to the Team Details page in Settings > User Management > Teams and clicking on the name of the team. Example: `https://app.stackhawk.com/teams/team/XXxxXXXX-xXXX-xxXX-XXxX-xXXxxXXXXxX`

### `hawk download log`

Download and print HawkScan log files to the console. Pass the scan ID as an argument to get the log for any previously run scan. You can review the scan log in order to troubleshoot any issues encountered while scanning.

Example:

```shell
hawk download log XXxxXXXX-xXXX-xxXX-XXxX-xXXxxXXXXxXX
```

The ID of a scan can be found in the URL after clicking an individual scan found on the [Scans page](https://app.stackhawk.com/scans). The last portion of the URL is the scan ID. So for the URL <https://app.stackhawk.com/scans/XXxxXXXX-xXXX-xxXX-XXxX-xXXxxXXXXxXX>, the scan ID would be XXxxXXXX-xXXX-xxXX-XXxX-xXXxxXXXXxXX.

Running the command will output the scan log to the console/STDOUT. The scan log can be saved to a file by using the right angle bracket (`>`) with the command along with a destination file.

```shell
hawk download log XXxxXXXX-xXXX-xxXX-XXxX-xXXxxXXXXxXX > hawkscan.log
```

### `hawk upgrade`

Upgrade the HawkScan CLI to the latest version — or to a specific version — with one command. `hawk upgrade` detects how hawk was installed (Homebrew, standalone binary, MSI, PKG, or Docker) and either performs the upgrade directly or prints the exact command to run for your install method. Standalone binary and Homebrew installs are upgraded in place; MSI, PKG, and Docker installs get precise upgrade instructions.

#### **Options**

- `--check` - Report whether a newer version is available without changing anything.
- `--version=x.y.z` - Upgrade (or downgrade) to a specific version instead of the latest.
- `--yes` - Skip the confirmation prompt.
- `--force` - Reinstall even if you are already on the requested version.

**Examples**

Check for a newer version:

```shell
hawk upgrade --check
```

Upgrade to the latest version:

```shell
hawk upgrade
```

Pin to a specific version:

```shell
hawk upgrade --version 6.2.0
```

> **Note:** **NOTE:** `hawk upgrade` will not self-replace a standalone binary when it detects a CI environment — unattended auto-upgrade of a security tool in a pipeline is both a supply-chain risk and a reproducibility problem. In CI it prints pinning guidance and exits 0 rather than upgrading, so it will not fail your build. Homebrew installs are left to the package manager and are not gated this way. To control the version in a pipeline, [pin it at install time](#install-programmatically) instead.

### `hawk skills status`

Report which [StackHawk agent skills](https://docs.stackhawk.com/ai-security/agent-skills/) are installed for your AI coding tools — Claude Code, Codex, and GitHub Copilot — and whether they are up to date. The command fetches the latest published skill versions live, so the report is accurate on the very first run.

**Example**

```shell
hawk skills status
```

### `hawk version`

Print the version of the CLI.

Sample output:

```shell
$ hawk version
v5.1.0
```