--- title: "HawkOp CLI" description: "HawkOp is the StackHawk companion CLI for exploring scan results, automating reporting, and integrating the StackHawk platform into your terminal and scripts." url: https://docs.stackhawk.com/hawkop/ --- # HawkOp CLI `hawkop` is the **StackHawk companion CLI** — a single binary for exploring your organization’s scan results, findings, audit logs, and configuration from the terminal, and for taking targeted actions on them: triaging findings, tuning per-application tech flags, and linking apps to the repositories they came from. Where the [StackHawk CLI](https://docs.stackhawk.com/stackhawk-cli/) (`hawk`) **runs** scans, `hawkop` **operates on** the results of those scans and everything else available through the StackHawk platform. It wraps the [StackHawk API](https://docs.stackhawk.com/apidocs/) with human-readable tables, JSON output for scripts, response caching, and shell completions. > **Note:** `hawkop` uses your StackHawk API key to call the same [public API](https://apidocs.stackhawk.com) available to every integration. Your organization must belong to a plan with **API Access** enabled. Reach out to to enable it. > > **HawkScan 6.0.0+:** `hawk op` is now built directly into the `hawk` binary — no separate `hawkop` install needed to run platform operations commands. The standalone `hawkop` binary remains the recommended tool for the rich query and reporting workflows described on this page. ## When to use HawkOp | Task | Tool | | - | - | | Run a DAST scan against a running application | [`hawk scan`](https://docs.stackhawk.com/stackhawk-cli/#hawk-scan) | | List recent scans, apps, teams, or policies | `hawkop` | | Inspect findings from a completed scan | `hawkop scan get` | | Triage findings (false positive, risk accepted, comment) | `hawkop scan triage` | | Tune per-app tech flags to speed up scans | `hawkop app tech-flags` | | Link a StackHawk app to a code repository | `hawkop repo link` | | Automate reporting or CI/CD gates from scan data | `hawkop --format json` | | Query the audit log or triage history | `hawkop audit list` | | Write a custom integration against the REST API | [StackHawk API](https://docs.stackhawk.com/apidocs/) | `hawkop` is the fastest way to explore your StackHawk data and the most script-friendly alternative to writing raw REST calls. ## Features - **Full platform access** — organizations, applications, scans, findings, users, teams, policies, repositories, audit log, scan configurations, OpenAPI specs, user secrets, and environments - **Rich filtering** — filter scans by status, environment, or application; audit logs by date, activity type, or user - **Flexible output** — `--format pretty` for interactive use, `--format table` for grep-friendly lists, `--format json` for automation - **Scan drill-down** — `hawkop scan get` walks the scan → alerts → findings chain in a single command, with optional HTTP request/response evidence - **Triage write surface** — mark findings as `FALSE_POSITIVE` / `RISK_ACCEPTED` or attach comments via `hawkop scan triage`, single-action or bulk from a JSON/YAML file - **Tech-flag tuning** — read and write per-application tech flags (`hawkop app tech-flags`) to speed up scans and reduce false positives - **Repo ↔ app mapping** — link applications to their upstream code repositories with `hawkop repo link` for attack-surface coverage - **Response caching** — SQLite-backed cache in `~/.hawkop/cache/` makes repeated queries snappy; bypass with `--no-cache` - **Parallel pagination** — large datasets fetch in parallel after the first page - **Reactive rate limiting** — only engages after the API returns `429`, so small queries stay fast - **Profiles** — switch between orgs, users, or API keys with `hawkop profile` / `-P ` - **Shell completions** — static and dynamic completions for Bash, Zsh, Fish, and PowerShell - **Cross-platform** — native binaries for Linux, macOS, and Windows on x86_64 and ARM64 ## Installation All `hawkop` artifacts are published to [`download.stackhawk.com`](https://download.stackhawk.com). The current version is always available as plain text at [`/hawkop/latest-version.txt`](https://download.stackhawk.com/hawkop/latest-version.txt). > **Note:** For a streamlined installer experience (auto-detects your platform and picks the right artifact), see the [**HawkOp Downloads**](https://docs.stackhawk.com/downloads/hawkop/) page. ### Install with Homebrew (macOS / Linux) ```bash brew tap stackhawk/cli brew trust stackhawk/cli brew install hawkop ``` The Homebrew tap is hosted at [stackhawk/homebrew-cli](https://github.com/stackhawk/homebrew-cli) and is updated automatically on every `hawkop` release. `brew trust` tells Homebrew it may load formulae from this third-party tap — required when `HOMEBREW_REQUIRE_TAP_TRUST` is set, and mandatory for all non-official taps in Homebrew 6.0.0 (or 5.2.0). ### Install with PKG (macOS) Download and double-click the signed `.pkg` for the universal macOS build: ```bash VERSION=$(curl -s https://download.stackhawk.com/hawkop/latest-version.txt) curl -L "https://download.stackhawk.com/hawkop/pkg/hawkop-v${VERSION}-macos-universal.pkg" -o hawkop.pkg open hawkop.pkg ``` ### Install with MSI (Windows) Download the signed Windows installer: ```powershell $Version = (Invoke-WebRequest https://download.stackhawk.com/hawkop/latest-version.txt).Content.Trim() Invoke-WebRequest "https://download.stackhawk.com/hawkop/msi/hawkop-v$Version-windows-x64.msi" -OutFile hawkop.msi Start-Process msiexec.exe -ArgumentList "/i hawkop.msi /passive" -Wait ``` ### Install from a release archive Every release publishes signed per-target tarballs under `https://download.stackhawk.com/hawkop/cli/`: | Platform | Architecture | Artifact | | - | - | - | | macOS | Intel | `hawkop-v{VERSION}-x86_64-apple-darwin.tar.gz` | | macOS | Apple Silicon | `hawkop-v{VERSION}-aarch64-apple-darwin.tar.gz` | | Linux | x86_64 | `hawkop-v{VERSION}-x86_64-unknown-linux-gnu.tar.gz` | | Linux | ARM64 | `hawkop-v{VERSION}-aarch64-unknown-linux-gnu.tar.gz` | | Windows | x86_64 | `hawkop-v{VERSION}-x86_64-pc-windows-msvc.zip` | Each archive has a matching `.sha256` checksum file alongside it at the same path. Example (macOS Apple Silicon): ```bash VERSION=$(curl -s https://download.stackhawk.com/hawkop/latest-version.txt) TARGET=aarch64-apple-darwin ARCHIVE="hawkop-v${VERSION}-${TARGET}.tar.gz" BASE="https://download.stackhawk.com/hawkop/cli" curl -L "${BASE}/${ARCHIVE}" -o "${ARCHIVE}" curl -L "${BASE}/${ARCHIVE}.sha256" -o "${ARCHIVE}.sha256" # Verify shasum -a 256 -c "${ARCHIVE}.sha256" # Extract and install tar -xzf "${ARCHIVE}" sudo mv hawkop /usr/local/bin/ hawkop --version ``` ## QuickStart ### 1. Initialize ```bash hawkop init ``` This prompts for your [StackHawk API key](https://app.stackhawk.com/settings/apikeys), authenticates, captures your default organization, and writes `~/.hawkop/config.yaml`. > **Note:** `hawkop init` is interactive by default. For headless setup (CI/CD), set `HAWKOP_API_KEY` in the environment and skip `init` — `hawkop` will read the key directly. ### 2. Verify setup ```bash hawkop status ``` Reports the active profile, organization, API host, and whether the JWT is currently valid. ### 3. Explore your data ```bash hawkop org list # Organizations you belong to hawkop app list # Applications in the active org hawkop scan list # Most recent scans across all apps hawkop scan get # Latest scan with alerts breakdown hawkop scan get # Specific scan with findings ``` ## Usage ### Global options These flags apply to every command: | Flag | Env var | Description | | - | - | - | | `--format ` | `HAWKOP_FORMAT` | Output format. `pretty` for humans, `table` for one row per entry, `json` for scripts. Defaults to `pretty`. | | `--org ` | `HAWKOP_ORG_ID` | Override the default organization. | | `--config ` | `HAWKOP_CONFIG` | Override config file location. | | `-P, --profile ` | `HAWKOP_PROFILE` | Switch to a named profile (different org, user, or API key). | | `--debug` | `HAWKOP_DEBUG` | Enable debug logging to stderr. | | `--no-cache` | `HAWKOP_NO_CACHE` | Bypass the local cache and fetch fresh data. | **Precedence:** command-line flags > environment variables > config file > defaults. ### Exit codes and output streams - Data goes to **stdout**; progress, prompts, and errors go to **stderr** — pipes and redirects stay clean. - `hawkop` respects `NO_COLOR`, `TERM=dumb`, and `--no-color` for plain output. - Non-zero exit codes indicate failure; scripts can branch on exit status without parsing text. ## Commands The full command surface. Use `hawkop --help` for detailed flags and examples on any subcommand. ### `hawkop init` Interactive setup. Prompts for API key, authenticates, and writes `~/.hawkop/config.yaml`. ### `hawkop status` Show the active profile, API host, organization, JWT validity, cache size, and the commands a user would run next. ### `hawkop version` Print the `hawkop` version. ### `hawkop org` Work with organizations your user belongs to. ``` hawkop org list # List organizations hawkop org set # Set the default organization hawkop org get # Show the current default organization ``` ### `hawkop app` ``` hawkop app list # List applications in the active org hawkop app list --type cloud # Filter by application type (cloud, standard) hawkop app list -n 50 --sort-by name hawkop app create --name --env # Create an application hawkop app get # Application detail hawkop app update --name # Rename hawkop app delete # Delete (requires confirmation) ``` #### `hawkop app tech-flags` Tech flags are per-application toggles that control which technology-specific vulnerability checks StackHawk runs (e.g., `Language.Java.Spring`, `Db.PostgreSQL`, `OS.Linux`). Disabling unused technologies speeds up scans and reduces false positives. Defaults are all enabled. ``` hawkop app tech-flags get --app hawkop app tech-flags set --app KEY=VALUE [KEY=VALUE ...] [--dry-run] hawkop app tech-flags enable-all --app [--yes] [--dry-run] hawkop app tech-flags disable-all --app [--yes] [--dry-run] ``` `KEY=VALUE` accepts case-insensitive `true|1|on|yes` or `false|0|off|no`. `enable-all` and `disable-all` prompt for confirmation; pass `--yes` to skip the prompt or `--dry-run` to preview the change without writing. ```bash # See current flags grouped by namespace hawkop app tech-flags get --app my-api # Disable two flags hawkop app tech-flags set --app my-api Db.MySQL=false Language.Python=false # Wipe everything and selectively re-enable a few hawkop app tech-flags disable-all --app my-api --yes hawkop app tech-flags set --app my-api Language.Java=true OS.Linux=true ``` ### `hawkop scan` ``` hawkop scan list # Recent scans, paginated hawkop scan list --status complete --env production hawkop scan list --app # Scans for a single application hawkop scan get # Latest scan: overview + alerts hawkop scan get # A specific scan hawkop scan get --app myapp # Latest scan for an app by name or UUID hawkop scan get --plugin-id 40012 # Alert detail hawkop scan get --uri-id --message # Finding + HTTP request/response hawkop scan get --detail full --format json # All findings, remediation, evidence ``` `hawkop scan get` walks the scan → alerts → findings chain in a single invocation so you don’t have to stitch three API calls together yourself. `--detail full` returns every finding with HTTP messages and remediation advice — ideal for feeding an AI agent. #### `hawkop scan triage` Mark scan findings as `FALSE_POSITIVE` or `RISK_ACCEPTED`, or attach a comment via `ADD_COMMENT`, in batches of up to 100 per call. Triage rules apply to future scans automatically. Each environment has its own finding hashes — triage is per-environment. ``` hawkop scan triage [--dry-run] Selectors (mutually exclusive): --scan agent shortcut: derives app+env | --app --env explicit form Input modes (mutually exclusive): --hash --status STATUS [--note "..."] single action | --from-file JSON or YAML array | --from-file - read from stdin ``` `STATUS` is case-insensitive: `FALSE_POSITIVE | RISK_ACCEPTED | ADD_COMMENT` (kebab and snake variants accepted). `ADD_COMMENT` requires `--note`. Each `--from-file` entry needs `findingHash` (also accepted as `finding_hash` or `hash`) and `status`, and can include `note`. `status` takes the same values as `--status`. An entry with any other key, or a status it doesn’t recognize, is rejected. Earlier versions ignored such entries, or reset the finding to New, without warning. The API returns 200 even on partial failures — `hawkop` renders per-action `✓`/`✗`, prints a summary, and exits non-zero if anything failed so scripts can detect partial success. ```bash # Triage one finding from a known scan (typical agent path) hawkop scan triage --scan abc123 --hash --status false-positive --note "XSS test fixture" # Comment-only when an agent can't auto-fix hawkop scan triage --scan abc123 --hash --status add-comment --note "Tracked in JIRA-456" # Bulk from a YAML file hawkop scan triage --app my-api --env Production --from-file triage.yaml # Bulk from stdin echo '[{"findingHash":"abc","status":"FALSE_POSITIVE","note":"..."}]' \ | hawkop scan triage --scan abc123 --from-file - # Preview without writing hawkop scan triage --scan abc123 --hash --status false-positive --dry-run ``` The file format is a flat array (no top-level wrapper): ```yaml - findingHash: a1b2c3... status: FALSE_POSITIVE note: "Test fixture, not real injection" - findingHash: d4e5f6... status: ADD_COMMENT note: "Tracked in JIRA-456 — fix scheduled for v0.9" ``` Finding hashes are SHA-256 identifiers — copy them from `hawkop scan get --detail full --format json | jq '.findings[].findingHash'` or from the equivalent fields surfaced in alert/path output. #### `hawkop scan config` Retrieve the exact effective configuration a completed scan ran with. The command resolves the scan’s stored config hash and fetches the config the scanner actually used — including all merged files and applied overrides — so you can reproduce or audit any scan. ``` hawkop scan config # Effective config as YAML hawkop scan config --format json # Full envelope: scanId, applicationId, configHash, conf ``` Output is YAML by default. Scans that predate config storage report a clear error. #### `hawkop scan uris` List the attack surface a scan exercised. The command is config-aware: in addition to the URLs visited, it reads the scan’s effective configuration and includes GraphQL operations or JSON-RPC methods when the scan was configured for those API types — where a plain URL list would be nearly empty. ``` hawkop scan uris # URLs, plus GraphQL/JSON-RPC surface when configured hawkop scan uris --graphql # Force GraphQL operations hawkop scan uris --jsonrpc # Force JSON-RPC methods ``` ### `hawkop run` Start, stop, and check the status of **hosted** scans (scans executed by the StackHawk platform against `cloud` applications). ``` hawkop run start --env hawkop run status hawkop run stop ``` ### `hawkop user`, `hawkop team` ``` hawkop user list # Organization members hawkop team list # Teams in the organization ``` ### `hawkop policy` ``` hawkop policy list # Custom and system scan policies hawkop policy get --name # Full definition of a single policy ``` `hawkop policy get` resolves both StackHawk preset policies (such as `DEFAULT` and `DEFAULT_API`) and scan policies belonging to your organization, returning the policy’s full definition including its plugins and tech flags. Use `--format json` to capture it as a file you can edit and re-apply. ```bash hawkop policy get --name MY_API --format json > my-api-policy.json ``` > **Note:** Fetching an organization policy by name requires HawkScan 6.4.0 or later. Earlier versions resolved preset policies only and returned `Resource not found` for your own policies. ### `hawkop repo` ``` hawkop repo list # Repositories in the attack surface hawkop repo link # Link an app to a repo (additive, preserves existing mappings) hawkop repo set-apps # Replace all app mappings for a repo (destructive) ``` `hawkop repo link` is the everyday verb for tying a StackHawk application to its upstream code repository so attack-surface coverage and findings can be traced back to source. It is **additive** — existing mappings on the repo are preserved. ```bash # Link an existing application by ID hawkop repo link --repo-id --app-id # Create a new app and link it in one step hawkop repo link --repo-id --app-name "my-api" # Resolve the repo by name hawkop repo link --repo "kaakaww/my-api" --app-id ``` `hawkop repo set-apps` is the **destructive** counterpart — it replaces the repository’s entire set of app mappings with the list you provide. Use it when you intentionally want to clear what’s there. Prompts for confirmation by default; pass `--yes` to skip and `--dry-run` to preview. ```bash hawkop repo set-apps --repo-id --app-ids , --yes ``` ### `hawkop oas` ``` hawkop oas list # Hosted OpenAPI specifications ``` ### `hawkop config` List stored scan configurations (the `stackhawk.yml` uploaded to the platform per application/environment). ``` hawkop config list ``` ### `hawkop secret` List user secret names (values are never returned by the API). ``` hawkop secret list ``` ### `hawkop audit` Query the organization audit log with filters, date ranges, and relative dates. ``` hawkop audit list --since 7d hawkop audit list --type SCAN_STARTED,SCAN_COMPLETED --since 30d hawkop audit list --user "Jane Smith" --email jane@example.com hawkop audit list --since 2025-01-01 --until 2025-01-31 ``` ### `hawkop env` Manage application environments. ``` hawkop env list --app # Environments for an app hawkop env config --app --env prod # Default stackhawk.yml for an environment hawkop env create --app --env staging --host https://staging.example.com hawkop env delete --app --env old-env ``` ### `hawkop cache` Inspect and manage the SQLite response cache. ``` hawkop cache status # Stats: hit rate, size, entry count hawkop cache clear # Clear all cached responses hawkop cache path # Print the cache database path ``` ### `hawkop profile` Switch between orgs, users, or API keys without rewriting your config. ``` hawkop profile list hawkop profile add # Interactive profile creation hawkop profile set # Make it the active profile hawkop profile remove ``` Use a profile for a single command without switching: ``` hawkop --profile work scan list hawkop -P personal app list ``` ### `hawkop completion` Generate static shell completions. ``` hawkop completion bash # bash hawkop completion zsh # zsh hawkop completion fish # fish hawkop completion powershell # PowerShell ``` See [Shell completions](#shell-completions) for installation snippets. ## Common usage patterns ### Filter scans ```bash hawkop scan list --status complete # Only completed scans hawkop scan list --env production # Only production hawkop scan list --app -n 50 # Last 50 for one app hawkop scan list --env staging --status failed # Combine filters ``` ### Query the audit log ```bash hawkop audit list --since 7d hawkop audit list --type SCAN_STARTED,SCAN_COMPLETED --since 30d hawkop audit list --since 2025-01-01 --until 2025-02-01 ``` ### Pipe to `jq` for automation ```bash # App names only hawkop app list --format json | jq -r '.data[].name' # Scans for production with a high finding hawkop scan list --env production --format json \ | jq '.data[] | select(.highAlertCount > 0) | {id, applicationId, highAlertCount}' # Dump a scan and all findings for an AI agent hawkop scan get --detail full --format json > scan.json ``` ### Switch organizations temporarily ```bash hawkop --org scan list # One-shot override hawkop -P customer-a scan list # Named profile ``` ### Agent-driven triage A typical workflow for an AI agent reviewing findings during automated remediation: ```bash # 1. Fetch full findings for a scan (the agent already knows the scan ID) hawkop scan get --detail full --format json > findings.json # 2. The agent inspects each finding. For ones it has verified are # false positives, it triages with a note explaining why. hawkop scan triage \ --scan \ --hash \ --status false-positive \ --note "Test fixture endpoint; not exposed in production." # 3. For a finding the agent cannot auto-fix, it adds a comment so # a human reviewer has context. hawkop scan triage \ --scan \ --hash \ --status add-comment \ --note "Cannot auto-fix; tracked in JIRA-456." ``` The `--scan ` shortcut derives both the application and environment from the scan, so the agent doesn’t need to look those up separately. ## Configuration ### Config file `hawkop` stores configuration at `~/.hawkop/config.yaml`. Typical contents: ```yaml api_key: hawk.abc123... org_id: 00000000-0000-0000-0000-000000000000 jwt: token: eyJhbGci... expires_at: 2026-01-15T12:00:00Z preferences: page_size: 1000 profiles: work: api_key: hawk.def456... org_id: 11111111-1111-1111-1111-111111111111 ``` > **Warning:** **Do not commit this file.** It contains your API key and a valid JWT. On Unix, `hawkop` sets the file permissions to `0600`. ### `hawk op` — the version embedded in HawkScan The HawkScan CLI ships these same commands as `hawk op`, and as of HawkScan **6.3.0** the embedded version does not use a config file of its own. It reads your API key, API host, and default organization from exactly the same places `hawk` itself does: - the `HAWK_API_KEY` environment variable, and - `~/.hawk/hawk.properties`, written when you run `hawk init`. Authenticate once with `hawk` and `hawk op` follows — there is no separate `hawk op init` step and no `~/.hawkop/config.yaml` to keep in sync. If a `~/.hawkop/config.yaml` is present from an earlier version, the embedded CLI ignores it. > **Note:** **NOTE:** This applies only to `hawk op` inside the HawkScan binary. The standalone `hawkop` CLI documented above continues to use `~/.hawkop/config.yaml`, `hawkop init`, profiles, and the `HAWKOP_*` environment variables. ### Environment variables | Variable | Purpose | | - | - | | `HAWKOP_API_KEY` | API key — useful in CI/CD where no config file exists | | `HAWKOP_ORG_ID` | Default organization | | `HAWKOP_FORMAT` | Default output format (`pretty`, `table`, or `json`) | | `HAWKOP_CONFIG` | Alternate config file path | | `HAWKOP_PROFILE` | Active profile | | `HAWKOP_DEBUG` | Enable debug logging | | `HAWKOP_NO_CACHE` | Disable response caching | ### CI/CD setup ```bash export HAWKOP_API_KEY=hawk.xxxxxxxxxxxx export HAWKOP_ORG_ID=00000000-0000-0000-0000-000000000000 export HAWKOP_FORMAT=json hawkop scan list --env production \ | jq '.data[] | select(.highAlertCount > 0)' \ | tee high-findings.json ``` `HAWKOP_API_KEY` is read directly — no interactive `init` required. ## Caching `hawkop` caches API responses in a local SQLite database at `~/.hawkop/cache/hawkop_cache.db`. Cache TTLs are tuned per endpoint: - Short-lived data (scan lists, audit log) cached for seconds to a minute - Stable data (apps, teams, policies) cached for minutes - Immutable data (finding details for a completed scan) cached longer Bypass the cache per-command with `--no-cache`, or globally with `HAWKOP_NO_CACHE=1`. ```bash hawkop cache status # Stats hawkop cache clear # Clear everything hawkop cache path # Where the db lives ``` ## Shell completions ### Static completions Generate once and install into your shell’s completion directory: **Tab: Bash** ```bash hawkop completion bash > ~/.local/share/bash-completion/completions/hawkop ``` **Tab: Zsh** ```bash hawkop completion zsh > ~/.zfunc/_hawkop # Ensure ~/.zfunc is on fpath and `autoload -U compinit && compinit` runs in .zshrc ``` **Tab: Fish** ```bash hawkop completion fish > ~/.config/fish/completions/hawkop.fish ``` **Tab: PowerShell** ```powershell hawkop completion powershell >> $PROFILE ``` ### Dynamic completions `hawkop` also provides **API-backed dynamic completions** for values like organization IDs, application IDs, scan IDs, and environment names. These activate automatically once static completions are installed — start typing an `--org` value and press `TAB` to see live suggestions. ## Troubleshooting **`hawkop status` reports no API key** Run `hawkop init` (interactive) or export `HAWKOP_API_KEY`. Create an API key at [Settings → API Keys](https://app.stackhawk.com/settings/apikeys). **Commands return empty lists** Confirm the active org with `hawkop org get`. If it isn’t the one you expect, run `hawkop org set ` or pass `--org ` per command. **Stale data in tables** Response caching can return slightly old data. Pass `--no-cache` to force a fresh fetch, or run `hawkop cache clear`. **Rate limited (`429`) during large reports** `hawkop` automatically backs off and retries when the API returns `429`. If you’re consistently hitting it, break the query into smaller windows (e.g. with `--since` on the audit log). ## Resources - **Downloads**: [download.stackhawk.com/hawkop/](https://download.stackhawk.com/hawkop/latest-version.txt) - **Homebrew tap**: [stackhawk/homebrew-cli](https://github.com/stackhawk/homebrew-cli) - **API reference**: [apidocs.stackhawk.com](https://apidocs.stackhawk.com) - **Report a bug**: ## Need Help? If you encounter an issue you cannot solve with this documentation, reach out to [StackHawk Support](mailto:support@stackhawk.com).