CLI authentication and CI

Use browser login for local work and an API key from your secret store for CI. Both authenticate the CLI to one organization. Credentials belong outside hpo.toml and container images.

Browser login

hpo login
hpo auth status

Login prints a connection URL and code, then asks whether to open the browser. The default is No; you can open the displayed URL yourself. Match the terminal code in the browser, choose your organization, and approve access. The code expires after ten minutes.

For SSH, use hpo login --no-browser and open the URL on another device. Use --accessible for text prompts. If browser opening fails, the manual URL remains available.

The CLI stores the credential in your operating system’s credential store. On Unix, you can explicitly select protected file storage with --credential-file <path>. Windows uses the credential store or HPO_API_KEY; the CLI does not silently fall back to plaintext storage.

Which credential is active?

hpo auth status reports the credential source and API URL without printing the key. The order is:

1. HPO_API_KEY, when the environment variable is present.
2. A file explicitly selected with --credential-file.
3. The operating system credential store.

An empty, whitespace-only, or rejected environment key does not fall back to a saved login. This prevents an unexpected switch to another account. If browser login succeeds but commands still fail, replace or unset HPO_API_KEY and check status again.

CI and manual API keys

Create an organization API key in the dashboard with the permissions your job needs:

Scope	Purpose
projects:read	Find and access the destination project.
experiments:read	Read experiment state.
experiments:write	Launch and control experiments.
trials:read	Read trial results.
registry:write	Required when the CLI builds and pushes images.

Supply the key through your CI secret store as HPO_API_KEY. With an existing hpo.toml and project:

hpo validate --project <project-id>
hpo optimize --project <project-id> --output jsonl --detach

The second command launches cloud work. Detached mode returns after launch rather than waiting for all trials to finish. Save the experiment ID and URL from its output if a later job needs to monitor it.

To save a manual key locally, pipe it from your secret source to hpo login --api-key-stdin. Never place the key in command arguments, TOML, or logs. With --output jsonl, structured events go to stdout and diagnostics go to stderr.

Sign out or revoke access

hpo logout

Logout removes only the selected local credential: the explicit credential file or the operating system entry. It leaves environment variables and the server-side key intact. If HPO_API_KEY is still set, it remains active and the CLI warns you.

To disable a key everywhere, revoke it in API Keys in the dashboard. If a key is revoked during monitoring, the CLI exits with code 3; the cloud experiment continues. Use another authorized credential or the dashboard to access or stop it.

If a real key is exposed, revoke it, create a replacement, and update local and CI secret stores.

API environments

The API address is selected in this order: --api-url, a nonempty HPO_API_URL, then https://api.hyperoptimizer.com. Saved logins are separated by API URL.

For a local API from the HyperOptimizer repository:

export HPO_API_URL=http://localhost:3002
hpo login

The repository’s local ingress http://api.127.0.0.1.nip.io is also supported. Remote API addresses require HTTPS. API overrides do not change your project TOML.

Errors and recovery

Error	Next action
API key required	Run hpo login or set the CI secret.
Invalid, expired, or revoked key	Check hpo auth status and replace the active credential source.
Missing scope	Create a key with the permission named in the error.
Organization access denied	Confirm the organization and your access in the dashboard.
API unavailable	Check the API URL and connectivity; do not assume the key is invalid.
Plan or compute restriction	Check Billing; this is separate from authentication.

Next: launch with the CLI or troubleshoot a launch.