Installation¶

Prerequisites¶

Python 3.13+
uv for Python package management
Node.js 22 and pnpm for frontend development
Graphviz for schema diagram rendering
Access to a Hawk deployment (API server URL + OAuth2 credentials)

Install the CLI¶

From GitHub:

uv pip install "hawk[cli] @ git+https://github.com/METR/hawk#subdirectory=hawk"

From source:

git clone https://github.com/METR/hawk.git
cd hawk/hawk
uv pip install -e ".[cli]"

Configuration¶

Set these environment variables before using the CLI, or put them in a .env file:

export HAWK_API_URL=https://hawk.example.com

Variable	Required	Description
`HAWK_API_URL`	Yes	URL of your Hawk API server
`HAWK_LOG_VIEWER_URL`	No	URL for the web log viewer
`HAWK_DATADOG_EVAL_SET_DASHBOARD_URL`	No	Datadog dashboard URL for eval sets
`HAWK_DATADOG_SCAN_DASHBOARD_URL`	No	Datadog dashboard URL for scans

OIDC configuration is discovered automatically from the API server — no OIDC env vars are needed for the CLI.

Authentication¶

hawk login

This authenticates via PKCE (browser-based) or Device Authorization flow. OIDC configuration is fetched from the API server and cached locally. Running hawk login also refreshes the cached OIDC configuration.

Run your first eval¶

hawk eval-set examples/simple.eval-set.yaml
hawk logs -f    # watch it run
hawk web        # open results in browser