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.

Where the 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 with human-readable tables, JSON output for scripts, response caching, and shell completions.

When to use HawkOp

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
• 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 <name>
• 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. The current version is always available as plain text at /hawkop/latest-version.txt.

Install with Homebrew (macOS / Linux)

brew tap stackhawk/hawkop
brew install hawkop

The Homebrew tap is hosted at stackhawk/homebrew-hawkop and is updated automatically on every hawkop release.

Install with PKG (macOS)

Download and double-click the signed .pkg for the universal macOS build:

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:

$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/:

Each archive has a matching .sha256 checksum file alongside it at the same path. Example (macOS Apple Silicon):

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

hawkop init

This prompts for your StackHawk API key, authenticates, captures your default organization, and writes ~/.hawkop/config.yaml.

2. Verify setup

hawkop status

Reports the active profile, organization, API host, and whether the JWT is currently valid.

3. Explore your data

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 <ID>      # Specific scan with findings

Usage

Global options

These flags apply to every command:

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 <command> --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 <ORG_ID>          # 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 scan

hawkop scan list                 # Recent scans, paginated
hawkop scan list --status complete --env production
hawkop scan list --app <APP_ID>  # Scans for a single application
hawkop scan get                  # Latest scan: overview + alerts
hawkop scan get <SCAN_ID>        # A specific scan
hawkop scan get --app myapp      # Latest scan for an app by name
hawkop scan get <SCAN_ID> --plugin-id 40012           # Alert detail
hawkop scan get <SCAN_ID> --uri-id <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 run

Start, stop, and check the status of hosted scans (scans executed by the StackHawk platform against cloud applications).

hawkop run start <APP_ID> --env <ENV>
hawkop run status <SCAN_ID>
hawkop run stop <SCAN_ID>

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 repo

hawkop repo list                 # Repositories in the attack surface

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 <APP_ID>                # Environments for an app
hawkop env config --app <APP_ID> --env prod   # Default stackhawk.yml for an environment
hawkop env create --app <APP_ID> --env staging --host https://staging.example.com
hawkop env delete --app <APP_ID> --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 <NAME>        # Interactive profile creation
hawkop profile set <NAME>        # Make it the active profile
hawkop profile remove <NAME>

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 for installation snippets.

Common usage patterns

Filter scans

hawkop scan list --status complete             # Only completed scans
hawkop scan list --env production              # Only production
hawkop scan list --app <APP_ID> -n 50          # Last 50 for one app
hawkop scan list --env staging --status failed # Combine filters

Query the audit log

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

# 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 <SCAN_ID> --detail full --format json > scan.json

Switch organizations temporarily

hawkop --org <OTHER_ORG_ID> scan list          # One-shot override
hawkop -P customer-a scan list                 # Named profile

Configuration

Config file

hawkop stores configuration at ~/.hawkop/config.yaml. Typical contents:

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

Environment variables

CI/CD setup

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.

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:

hawkop completion bash > ~/.local/share/bash-completion/completions/hawkop

hawkop completion zsh > ~/.zfunc/_hawkop
# Ensure ~/.zfunc is on fpath and `autoload -U compinit && compinit` runs in .zshrc

hawkop completion fish > ~/.config/fish/completions/hawkop.fish

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.

Commands return empty lists Confirm the active org with hawkop org get. If it isn’t the one you expect, run hawkop org set <ORG_ID> or pass --org <ORG_ID> 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/
• Homebrew tap: stackhawk/homebrew-hawkop
• API reference: apidocs.stackhawk.com
• Report a bug: support@stackhawk.com

Need Help?

If you encounter an issue you cannot solve with this documentation, reach out to StackHawk Support.