Launch with the CLI

The hpo CLI builds, publishes, launches, and monitors experiments from a local hpo.toml. The command hyperoptimizer is an alias for the same program. Your trial container does not need either command installed.

Install the CLI

This guide uses a source build from the HyperOptimizer repository. You need repository access and Go 1.24 or later. From the repository root:

cd services/cli
go build -o dist/hpo ./cmd/hpo
sh install.sh dist/hpo "$HOME/.local/bin"

Add $HOME/.local/bin to your PATH, then check the installation with hpo version. The installer creates both command names and refuses to overwrite an existing command. On Windows, build hpo.exe from ./cmd/hpo and add its directory to PATH.

If you do not have a source checkout, use the dashboard workflow. Local builds and releases must be compatible with the deployed API.

Log in and select a project

hpo login
hpo init

Login prints a connection URL and code, then asks whether to open the browser. Choosing No leaves the displayed URL available for manual login. In the browser, match the terminal code, choose your organization, and approve access.

hpo init lets you select a project and creates hpo.toml. It does not overwrite an existing file. To choose explicitly, use hpo init --project <project-id>; to create a project, use hpo init --create-project <name>.

Use hpo login --no-browser on SSH. Use --accessible for text prompts. For API keys and unattended runs, see CLI authentication and CI.

Configure and validate

Edit the generated hpo.toml for your image, parameters, objectives, machine, and limits. The quickstart includes a complete working example; experiment TOML explains the fields and versions.

hpo fmt
hpo validate

hpo fmt formats the file while retaining comments. hpo fmt --check reports whether formatting is needed without changing the file.
hpo validate --offline checks the configuration structure without logging in.
hpo validate also checks semantics, project access, and plan limits online. It does not launch work or reserve capacity. Launch validates again.

Set the workload environment variables listed in requiredEnv before launching. Only those named values are forwarded. Keep secrets out of TOML and add .hpo/ to your repository’s .gitignore.

Launch an experiment

hpo optimize

With [build], the CLI uses local Docker Buildx, obtains temporary registry credentials, builds and pushes the image, and launches by digest. Without [build], it uses the existing [dockerImage] reference. Image availability is checked during launch.

Use --config path/to/hpo.toml for another file. --project <project-id> overrides the target project in the file.

Watch, detach, and stop

Command	Behavior
`hpo optimize`	Launch and show a live table in a terminal; plain output when redirected.
`hpo optimize --detach`	Return the experiment ID and URL after launch.
`hpo watch <id> --project <project-id>`	Monitor an existing experiment from its current state.
`hpo stop <id> --project <project-id>`	Request a stop of cloud execution.

Ctrl+C detaches; the cloud experiment continues. Reconnect with hpo watch, or use the dashboard to pause or stop. Monitoring starts with the current state, not a complete replay of earlier events.

Multiple objectives keep their names and directions. The CLI does not invent an overall winner. A failed trial alone does not mean that the whole experiment has failed.

Recover an interrupted launch

If the launch response is interrupted, the CLI saves recovery state in .hpo/launch.json. Rerun the same optimize command with unchanged configuration and required environment values to recover the original request.

Check the dashboard before deleting pending state. After a successful launch, another hpo optimize intentionally creates a new experiment; use watch to reconnect instead.

Output for scripts

hpo optimize --output plain
hpo optimize --output jsonl --detach

Plain mode prints status and metric updates. JSONL writes structured events to stdout, while diagnostics and prompts go to stderr. Use a CI secret as HPO_API_KEY; see authentication and CI.

Exit codes

Code	Meaning
0	Successful command or detached launch.
1	Failed or cancelled experiment.
2	Usage, configuration, or rejected request.
3	Missing, invalid, expired, or revoked credentials.
4	Permission or organization-access restriction.
5	Service or transport error.
130	User interruption.

For more options, use hpo --help, hpo completion <shell>, and hpo version.