Skip to main content

​
Prerequisites

  • Python 3.12
  • uv, for example brew install uv
  • Docker, for the local tracker stack

​
Install the CLI from source

This creates .venv and installs the dependencies declared in pyproject.toml. To run valkyrie without the uv run prefix, install it as a tool:
The tool install is editable, so code changes take effect immediately. Run uv tool update-shell if the executable is not on your PATH.

​
Point the CLI at a local tracker

Set this in .env or your shell before running CLI commands against a local tracker. The CLI still reads credentials from ~/.config/valkyrie/valkyrie.yaml, created by valkyrie config init. See Configure the CLI.

​
Run the tracker locally

The API is available at http://localhost:8000. Local Compose runs the tracker, PostgreSQL, and Redis only. It does not execute benchmarks. See Tracker service for the individual targets and test suites.

​
Run it with hosted-mode authentication

DESCOPE_MANAGEMENT_KEY is server-side tracker configuration. It lets the local tracker resolve the access key’s bound user email through Descope’s management API when you are testing hosted-mode run attribution. The tracker expects the access-key exchange response to expose the bound user id through custom claims:
Then run valkyrie config init and choose hosted mode. Without these variables the service runs in self-hosted mode with no auth and a default organization.

​
Check your changes

​
Preview the documentation

The published documentation is generated from docs/. Local preview needs Node.js 20.17 or newer and no Mintlify credentials:
Run npx mint login only to test account-backed features such as search and the assistant. docs/reference/ is generated from the CLI and SDK source. Run make docs-reference after changing a public CLI or SDK surface. CI runs make docs-reference-check and fails on stale output.

​
Versioning and releases

The prod branch uses semantic versioning through github-tag-action. Include the tag in the pull request title: Binaries are released when a commit is tagged: dev requires tagging a commit manually, prod is tagged and released automatically on push. valkyrie-sdk is versioned and published separately.