Skip to content

Define it in your repo.Run it from your terminal.

Keep your workload and its search settings together. The HPO CLI takes your hpo.toml from a local Docker build to managed trials, with results in the terminal and dashboard.

CLI installation guide Explore hpo.toml

From your working directory

One file. Three steps to a cloud experiment.

Start with a container that accepts --hpo-* arguments and prints hpo.metrics. values. You need a project, eligible compute, and Docker with Buildx for local builds. Choose your workload guide.

  1. Step 1

    Connect your project

    Sign in, select a project, and create hpo.toml in your workload repository. Init keeps any existing configuration file intact.

    TerminalStep 1
    hpo login
hpo init

  2. Step 2

    Define and validate the search

    Edit your build settings, parameter ranges, objectives, and run limits. Format the file and check it against your project and plan before launching.

    TerminalStep 2
    # Edit hpo.toml first
hpo fmt
hpo validate

  3. Step 3

    Launch and follow the trials

    With [build], the CLI builds and pushes your image, launches cloud trials, and shows progress in the terminal. Follow the experiment link to inspect results in the dashboard.

    TerminalStep 3
    hpo optimize

CLI preview: installation uses a source build. Published binaries and hosted CLI support are awaiting rollout verification; the installation guide documents the required API and dashboard support. Launching trials consumes your available compute.

Experiment configuration as code

Make the search part of the review.

A change to a parameter range or objective is a change to your experiment. Keep it in Git so you can review what changed alongside your workload.

What to vary
Define integer, numeric, and categorical parameters. Each slug maps to a flag your container receives, such as --hpo-stop-loss-pct.
What to measure
Choose a minimize or maximize direction for each objective. This example expects hpo.metrics.final_portfolio_value from your backtest.
How much to run
Set trial count, concurrency, machine size, and per-trial timeout. Execution stays subject to your plan and available compute.
What to build
Point [build] at your Dockerfile. To use a published image, omit [build] and supply [dockerImage] instead.
Download example hpo.tomlFull configuration guide

Adapt this example to your Dockerfile and measured metrics. Keep the [target] written by hpo init, or select a project with --project. The file defines a search; your code and data determine the results. Keep credentials and environment values outside the file.

hpo.tomlComplete v2 example
schemaVersion = 2
algorithm = "bayesian"
maxTrialCount = 120
parallelTrialCount = 10
maxFailedTrialCount = 3
maxRuntimeSecondsPerTrial = 300
machineSizeId = "small"
useCustomDockerImage = false
fixedArgs = []
requiredEnv = []

[build]
context = "."
dockerfile = "Dockerfile"
repository = "trading-strategy"
platform = "linux/amd64"

[[parameters]]
name = "stop_loss_pct"
slug = "stop-loss-pct"
type = "int"
min = 1
max = 10

[[parameters]]
name = "take_profit_pct"
slug = "take-profit-pct"
type = "int"
min = 2
max = 25

[[objectives]]
name = "final_portfolio_value"
type = "maximize"

Choose where you work

Terminal for launches. Dashboard for exploration.

Both use the same experiment settings. Export TOML from the dashboard, edit it in your repo, and launch with the CLI. Import a file back into the dashboard when you want to configure a run there.

Keep cloud trials running

Ctrl+C detaches your terminal while cloud execution continues. Reattach to follow progress, or explicitly stop the experiment.

TerminalUse your experiment and project IDs
hpo watch <experiment-id> --project <project-id>
hpo stop <experiment-id> --project <project-id>

Use the same file in automation

Supply HPO_API_KEY through your CI secret store. Check formatting, validate the configuration, then launch with structured output.

CI commandsWith credentials and target configured
hpo fmt --check
hpo validate
hpo optimize --output jsonl --detach
CLI authentication and CI guide →

The dashboard retains local build settings as metadata and needs a published image to launch. TOML carries configuration; results and credentials remain separate.