CLI reference

Every command, flag, default and allowed value of the atune binary.

This page is generated from the command line itself: cargo dev generate-all walks atune_cli::Cli through clap's CommandFactory — the same type the binary parses your arguments with. A new subcommand or flag appears here because clap knows about it, so the page cannot drift from atune --help, and CI fails if it has.

Two things are left out, both because --help leaves them out too: the atune help <command> spelling that clap synthesises for every program it builds, and anything marked hidden.

Generated file. Do not edit between the pragmas below — run cargo dev generate-all --mode write instead. Everything outside them is hand-written and is never touched.

atune

Command-line interface for the atune hyperparameter optimization framework

Usage: atune <COMMAND>

Commands

• atune run — Tune a program: run N subprocess trials, substituting sampled parameters
• atune ask — Sample one parameter and print its value (the scripted-handshake half)
• atune tell — Record the objective for the current trial (ATUNE_TRIAL or a prior ask)
• atune best — Print the best trial of a study
• atune trials — List a study's trials
• atune export — Export a study to an Optuna journal file (for optuna-dashboard)
• atune import — Import an Optuna journal file into an atune storage
• atune top — Watch a study live in the terminal (a read-only viewer, no server)
• atune report — Write a study as a self-contained static HTML report
• atune importance — Rank a study's parameters by PED-ANOVA importance
• atune serve — Serve a study over TCP so remote workers can share it (RemoteStorage)
• atune doctor — Read a study and report findings that likely cost you budget

Options

• -h, --help — Print help
• -V, --version — Print version

atune run

Tune a program: run N subprocess trials, substituting sampled parameters

Usage: atune run [OPTIONS] --study <PATH> --trials <N> -- <PROGRAM [ARG]...>...

Arguments

• <PROGRAM [ARG]...>... — The program and its argument templates, given after --.

  The first element is the program; the rest are its arguments, in which {param} is replaced by that parameter's sampled value.

  atune run executes the program directly; it is not a sandbox. Treat an untrusted objective/program as untrusted code and provide an OS/container sandbox with least privilege; atune does not enforce this.

  Required.

Options

• --study <PATH> — The journal file the study lives in (created if it does not exist).

  Journal files are plaintext. Require restrictive file permissions, an encrypted volume, and protected backups (encrypted when transferred).

  Required. - --trials <N> — How many trials to run in total (counts the trials already in the study)

  Required. - --parallel <K> — How many child processes to run at once

  Default: 1. - --param <NAME=SPEC> — A parameter to tune, written name=<dsl-spec> (repeatable) - --seed <SEED> — The study seed — only used when the study is first created

  Default: 0. - --maximize — Maximize the objective instead of minimizing it (first-create only) - --sampler <SAMPLER> — Which sampler chooses the parameters

  Default: tpe.

  One of:

  • random — Uniform independent draws, deterministic per trial number
  • tpe — Tree-structured Parzen estimator — the headline sampler
  • qmc — Low-discrepancy Sobol coverage
  • grid — Every point of a finite space, once each (needs a declared space)
  • --retry <N> — Re-run a failed configuration up to this many extra times

  Default: 0. - --seeds <K> — Evaluate each trial under this many tune seeds (a multi-seed fan).

  1 (the default) is single-seed: no fan, one evaluation per trial. >=2 turns a trial into K replicates of the same configuration, aggregated (see --aggregate) into the objective the sampler ranks.

  The seed protocol — --seeds, --test-seeds, --aggregate, --pairing and --std-lambda — is fixed when the study is created and persisted with it. On resume it is read back from the study: pass none of these flags to reuse the stored protocol, and note that passing one that disagrees with the stored protocol is a usage error (the study would otherwise mix aggregate and raw objectives). Start a new study to change the protocol. - --test-seeds <M> — After tuning, re-evaluate the top configurations on this many disjoint held-out test seeds and report the tune-vs-test gap.

  0 (the default) disables the final re-evaluation stage. Part of the persisted seed protocol — see --seeds for the create-vs-resume rules. - --test-top-k <N> — How many top configurations the --test-seeds stage re-evaluates

  Default: 3. - --aggregate <AGGREGATE> — How the per-seed values of a fan collapse into the sampler's objective.

  Defaults to iqm. Part of the persisted seed protocol — see --seeds for the create-vs-resume rules.

  One of:

  • mean — The arithmetic mean
  • median — The median
  • iqm — The interquartile mean (robust to a lucky or unlucky seed)
  • mean-minus-std — mean - lambda * std (risk-averse); lambda is --std-lambda
  • --pairing <PAIRING> — How a replicate's seed depends on the trial (paired = common random numbers).

  Defaults to paired. Part of the persisted seed protocol — see --seeds for the create-vs-resume rules.

  One of:

  • paired — Common random numbers: replicate j shares its seed across all trials
  • independent — The trial number is folded in, so every replicate is a fresh draw
  • --std-lambda <LAMBDA> — The dispersion weight for --aggregate mean-minus-std (ignored otherwise).

  Defaults to 1.0. Part of the persisted seed protocol — see --seeds for the create-vs-resume rules. - --timeout <SECONDS> — Kill and fail a child that runs longer than this many seconds - --prune-exit-code <CODE> — The child exit code that means "prune this trial" (1..=255; default 42) - --export-params — Also export each sampled parameter to the child as ATUNE_PARAM_<name> - --name <NAME> — A name for the study — only used when the study is first created - -h, --help — Print help (see a summary with '-h')

atune ask

Sample one parameter and print its value (the scripted-handshake half)

Usage: atune ask [OPTIONS] <NAME> <SPEC>

Arguments

• <NAME> — The parameter name

  Required. - <SPEC> — The distribution, as a DSL spec — e.g. loguniform(1e-4,1e-1)

  Required.

Options

• --study <PATH> — The journal file (defaults to $ATUNE_JOURNAL).

  Journal files are plaintext. Require restrictive file permissions, an encrypted volume, and protected backups (encrypted when transferred). - --seed <SEED> — The study seed — only used when the study is first created

  Default: 0. - --maximize — Maximize (first-create only; matters for best, not for sampling) - --sampler <SAMPLER> — Which sampler chooses the value

  Default: random.

  One of:

  • random — Uniform independent draws, deterministic per trial number
  • tpe — Tree-structured Parzen estimator — the headline sampler
  • qmc — Low-discrepancy Sobol coverage
  • grid — Every point of a finite space, once each (needs a declared space)
  • --study-name <NAME> — A name for the study — only used when the study is first created
  • -h, --help — Print help (see a summary with '-h')

atune tell

Record the objective for the current trial (ATUNE_TRIAL or a prior ask)

Usage: atune tell [OPTIONS] <VALUE>...

Arguments

• <VALUE>... — The objective value(s) — one per study direction

  Required.

Options

• --study <PATH> — The journal file (defaults to $ATUNE_JOURNAL).

  Journal files are plaintext. Require restrictive file permissions, an encrypted volume, and protected backups (encrypted when transferred). - -h, --help — Print help (see a summary with '-h')

atune best

Print the best trial of a study

Usage: atune best [OPTIONS] --study <PATH>

Options

• --study <PATH> — The local study file (*.atj, *.db, *.sqlite, *.sqlite3) or atune://host:port remote observer endpoint to read.

  Remote observer traffic is plaintext TCP: atune provides no authentication and no TLS. Use loopback, or a private VPN with host firewall and cloud/network ACLs; use an mTLS proxy where client identity is required. A private LAN alone is not an identity boundary.

  Local Journal (*.atj) and SQLite (*.db, *.sqlite, *.sqlite3) data are plaintext. Require restrictive file permissions, an encrypted volume, and protected backups.

  Required. - --format <FORMAT> — How to render the output

  Default: text.

  One of:

  • text — A compact human-readable table
  • json — Machine-readable JSON
  • -h, --help — Print help (see a summary with '-h')

atune trials

List a study's trials

Usage: atune trials [OPTIONS] --study <PATH>

Options

• --study <PATH> — The local study file (*.atj, *.db, *.sqlite, *.sqlite3) or atune://host:port remote observer endpoint to read.

  Remote observer traffic is plaintext TCP: atune provides no authentication and no TLS. Use loopback, or a private VPN with host firewall and cloud/network ACLs; use an mTLS proxy where client identity is required. A private LAN alone is not an identity boundary.

  Local Journal (*.atj) and SQLite (*.db, *.sqlite, *.sqlite3) data are plaintext. Require restrictive file permissions, an encrypted volume, and protected backups.

  Required. - --format <FORMAT> — How to render the output

  Default: text.

  One of:

  • text — A compact human-readable table
  • json — Machine-readable JSON
  • -h, --help — Print help (see a summary with '-h')

atune export

Export a study to an Optuna journal file (for optuna-dashboard)

Usage: atune export [OPTIONS] --study <PATH>

Options

• --study <PATH> — The local study file (*.atj, *.db, *.sqlite, *.sqlite3) or atune://host:port remote observer endpoint to read.

  Remote observer traffic is plaintext TCP: atune provides no authentication and no TLS. Use loopback, or a private VPN with host firewall and cloud/network ACLs; use an mTLS proxy where client identity is required. A private LAN alone is not an identity boundary.

  Local Journal (*.atj) and SQLite (*.db, *.sqlite, *.sqlite3) data are plaintext. Require restrictive file permissions, an encrypted volume, and protected backups.

  Required. - --optuna <PATH> — Write the Optuna journal to this path (omit, or -, for stdout).

  --optuna PATH selects Optuna's journal-file format and names the output. With neither --optuna nor --optuna-rdb, the journal goes to stdout; if only --optuna-rdb is given, nothing goes to stdout.

  Export output is plaintext study data. Require restrictive file permissions, an encrypted volume, and protected backups. - --optuna-rdb <PATH> — Also write an Optuna RDB-sqlite database to this path.

  Optuna's relational on-disk form: optuna-dashboard sqlite:///<PATH> or optuna.load_study(storage="sqlite:///<PATH>") opens it. An existing file at PATH is replaced. May be combined with --optuna (each names its own output). Unlike --optuna, it has no stdout form — a database needs a path. The SQLite output is plaintext study data; require restrictive file permissions, an encrypted volume, and protected backups. - -h, --help — Print help (see a summary with '-h')

atune import

Import an Optuna journal file into an atune storage

Usage: atune import --storage <SPEC> <INPUT>

Arguments

• <INPUT> — The Optuna journal file to read

  Required.

Options

• --storage <SPEC> — The destination storage, as a spec: :memory:, a *.atj journal, or a *.db/*.sqlite/*.sqlite3 database.

  Local Journal (*.atj) and SQLite (*.db, *.sqlite, *.sqlite3) files are plaintext. Require restrictive file permissions, an encrypted volume, and protected backups (encrypted when transferred).

  Required. - -h, --help — Print help (see a summary with '-h')

atune top

Watch a study live in the terminal (a read-only viewer, no server)

Usage: atune top [OPTIONS] --study <PATH>

Options

• --study <PATH> — The local study file (*.atj, *.db, *.sqlite, *.sqlite3) or atune://host:port remote observer endpoint to read.

  Remote observer traffic is plaintext TCP: atune provides no authentication and no TLS. Use loopback, or a private VPN with host firewall and cloud/network ACLs; use an mTLS proxy where client identity is required. A private LAN alone is not an identity boundary.

  Local Journal (*.atj) and SQLite (*.db, *.sqlite, *.sqlite3) data are plaintext. Require restrictive file permissions, an encrypted volume, and protected backups.

  Required. - --interval <MS> — How often to re-read the study, in milliseconds (floored at 100)

  Default: 1000. - -h, --help — Print help (see a summary with '-h')

atune report

Write a study as a self-contained static HTML report

Usage: atune report [OPTIONS] --study <PATH>

Options

• --study <PATH> — The local study file (*.atj, *.db, *.sqlite, *.sqlite3) or atune://host:port remote observer endpoint to read.

  Remote observer traffic is plaintext TCP: atune provides no authentication and no TLS. Use loopback, or a private VPN with host firewall and cloud/network ACLs; use an mTLS proxy where client identity is required. A private LAN alone is not an identity boundary.

  Local Journal (*.atj) and SQLite (*.db, *.sqlite, *.sqlite3) data are plaintext. Require restrictive file permissions, an encrypted volume, and protected backups.

  Required. - --out <PATH> — Write the HTML report to this path (omit for standard output).

  Report output is plaintext study data. Require restrictive file permissions, an encrypted volume, and protected backups. - -h, --help — Print help (see a summary with '-h')

atune importance

Rank a study's parameters by PED-ANOVA importance

Usage: atune importance [OPTIONS] --study <PATH>

Options

• --study <PATH> — The local study file (*.atj, *.db, *.sqlite, *.sqlite3) or atune://host:port remote observer endpoint to read.

  Remote observer traffic is plaintext TCP: atune provides no authentication and no TLS. Use loopback, or a private VPN with host firewall and cloud/network ACLs; use an mTLS proxy where client identity is required. A private LAN alone is not an identity boundary.

  Local Journal (*.atj) and SQLite (*.db, *.sqlite, *.sqlite3) data are plaintext. Require restrictive file permissions, an encrypted volume, and protected backups.

  Required. - --objective <OBJECTIVE> — Which objective to assess, for a multi-objective study (0 = the first)

  Default: 0. - --raw — Print the raw (un-normalized) PED-ANOVA values instead of the sum-to-one normalized importances - -h, --help — Print help (see a summary with '-h')

atune serve

Serve a study over TCP so remote workers can share it (RemoteStorage)

Usage: atune serve [OPTIONS] --storage <SPEC>

Options

• --storage <SPEC> — The backing storage to serve, as a spec: :memory:, a *.atj journal, or a *.db/*.sqlite/*.sqlite3 database. Created if it does not exist.

  Local Journal (*.atj) and SQLite (*.db, *.sqlite, *.sqlite3) files are plaintext. Require restrictive file permissions, an encrypted volume, and protected backups (encrypted when transferred).

  Required. - --bind <ADDR> — The address to bind. Defaults to 127.0.0.1:7878 (loopback only).

  A non-loopback address (0.0.0.0:PORT, a VPN IP) exposes the store with no authentication and no TLS: anyone who can reach the address can read and modify every study in it. Use loopback, or a private VPN with host firewall and cloud/network ACL controls; put an mTLS proxy in front when client identity is required. A private LAN alone is not an identity boundary. See resuming and scaling a study. - --max-connections <N> — How many workers may be connected at the same time.

  Each connection costs one thread on the server, so this is the bound on what a crowd of workers — or a stuck one that never disconnects — can make the process hold. A worker that arrives when the limit is already reached is refused immediately with an error naming the limit, rather than queued or left waiting, and may retry once another disconnects.

  Default: 128. - -h, --help — Print help (see a summary with '-h')

atune doctor

Read a study and report findings that likely cost you budget

Usage: atune doctor [OPTIONS] --study <PATH>

Options

• --study <PATH> — The local study file (*.atj, *.db, *.sqlite, *.sqlite3) or atune://host:port remote observer endpoint to read.

  Remote observer traffic is plaintext TCP: atune provides no authentication and no TLS. Use loopback, or a private VPN with host firewall and cloud/network ACLs; use an mTLS proxy where client identity is required. A private LAN alone is not an identity boundary.

  Local Journal (*.atj) and SQLite (*.db, *.sqlite, *.sqlite3) data are plaintext. Require restrictive file permissions, an encrypted volume, and protected backups.

  Required. - --format <FORMAT> — How to render the output

  Default: text.

  One of:

  • text — A compact human-readable table
  • json — Machine-readable JSON
  • --sampler <SAMPLER> — The sampler the study is actually configured with, if known.

  A study's journal never records which sampler produced it — a sampler is a runtime object a caller injects, not study-recorded data — so this cannot be inferred from --study alone. Passing it enables the two findings that compare against it (a sampler that no longer fits the study, and too few trials for the configured sampler's model); without it — or for a study created with a sampler this flag cannot name (Dehb, Carbs, or a third-party one) — those two findings are silently skipped rather than guessed.

  One of:

  • random — Uniform independent draws
  • tpe — Tree-structured Parzen estimator
  • qmc — Low-discrepancy Sobol coverage
  • grid — Every point of a finite space, once each
  • nsga2 — Multi-objective NSGA-II
  • -h, --help — Print help (see a summary with '-h')