Akka Optimize CLI

akka is the command-line interface for Akka Optimize. Use akka commands to operate the trainer. The trainer pages use these commands to explain each operation.

Install the CLI

akka signs in with the login of the akka CLI. Install the akka CLI first, and log in with akka auth login. For more information, see the Akka CLI documentation. In a later release, the akka commands move to the akka optimize command group of the akka CLI.

akka runs on macOS and Linux on x86-64 and ARM. To install the akka binary for release 0.7.1 in ~/.local/bin, use the install script:

curl -fsSL https://doc.akka.io/preview/optimize/0.7.1/cli/install.sh | sh

The script detects your platform, downloads its archive and the release’s SHA256SUMS file, verifies the archive, installs the binary, and prints the installed version. If the directory it installs in isn’t on your PATH, the script tells you. To install the binary in another directory, set AKKA_OPTIMIZE_INSTALL_DIR:

curl -fsSL https://doc.akka.io/preview/optimize/0.7.1/cli/install.sh | AKKA_OPTIMIZE_INSTALL_DIR=/usr/local/bin sh

Download the archive yourself

Each archive contains the akka binary for one platform:

macOS on Apple silicon: akka-optimize-darwin-arm64.tar.gz
macOS on Intel: akka-optimize-darwin-amd64.tar.gz
Linux on x86-64: akka-optimize-linux-amd64.tar.gz
Linux on ARM: akka-optimize-linux-arm64.tar.gz

Download the archive for your platform and the SHA256SUMS checksum file to the same directory. Verify the archive against SHA256SUMS, extract the binary, and move it to a directory on your PATH. For example, on macOS with Apple silicon:

shasum -a 256 --check --ignore-missing SHA256SUMS
tar -xzf akka-optimize-darwin-arm64.tar.gz
mv akka-optimize ~/.local/bin/

On Linux, verify the archive with sha256sum --check --ignore-missing SHA256SUMS.

The binary is unsigned. On macOS, if you download it with a web browser, remove its quarantine attribute:

xattr -d com.apple.quarantine ~/.local/bin/akka-optimize

curl doesn’t add the quarantine attribute, so you don’t need this step when you use the install script.

Confirm the installation

Confirm that akka runs and reports the installed version:

akka-optimize --version

Connect to a trainer

The TRAINER_URL environment variable specifies the address of the trainer deployed in your Akka project. The project’s route publishes this address. The --trainer-url flag on any command overrides the environment variable.

Set the address and confirm that the trainer responds:

export TRAINER_URL=https://optimize.example.akka.services
akka-optimize status

status lists each service that the CLI contacts, whether the service responds, and the address that the CLI used. This section requires only the trainer. Other services can appear as unreachable at their default addresses. training info reports the trainer’s backend. It exits with a non-zero status when the service doesn’t respond, so a script can use it to wait for the trainer.

A 503 response from the trainer’s address can mean that the service is restarting after a deployment. Retry the request after a minute.

Authenticate

akka uses the same authentication as the akka CLI. After you run akka auth login, akka gets the refresh token from the current akka context. On the first request that requires authentication, it exchanges the refresh token for an access token. You don’t need any other workstation configuration.

To use the login of a different akka context, name that context with the --context flag or the AKKA_CONTEXT environment variable. The flag takes precedence over the variable. akka exchanges the token at the API host that the named context specifies, so one shell can reach a service on a different platform from the current context. If the configuration file has no context with that name, or the named context holds no login, akka refuses the command and lists the contexts that the file contains.

export AKKA_CONTEXT=staging
akka-optimize training runs list

For a job that must use different credentials from the user who is signed in, set one of the following environment variables. akka uses the first variable that is set:

Variable Description

Variable	Description
`AKKA_ACCESS_TOKEN`	An access token, used as it is.
`AKKA_TOKEN`	A refresh token. `akka` exchanges it for an access token and caches the result until shortly before it expires.
`AKKA_OAUTH_TOKEN`	An OAuth token. Requires `AKKA_OAUTH_TOKEN_AUDIENCE`.
`AKKA_OAUTH_TOKEN_FILE`	A file that holds an OAuth token.

AKKA_ACCESS_TOKEN

An access token, used as it is.

AKKA_TOKEN

A refresh token. akka exchanges it for an access token and caches the result until shortly before it expires.

AKKA_OAUTH_TOKEN

An OAuth token. Requires AKKA_OAUTH_TOKEN_AUDIENCE.

AKKA_OAUTH_TOKEN_FILE

A file that holds an OAuth token.

A denied request returns 403. The response identifies the refused action, such as optimize.training.runs.create.

Conventions

Output: -o text is the default and displays a table or a block of fields. -o json and -o json-compact return a document that a script can read. Results go to stdout, and notes go to stderr, so -o json > FILE writes only the document. --jq EXPRESSION filters JSON output, and --json FIELDS selects fields. --json= lists the fields that a command offers.
Writes: A write prints one sentence that says what happened and where to look. The full object is available with -o json.
Confirmation: A command that provisions compute or discards work prompts for confirmation. --force skips the prompt. When stdin isn’t a terminal, the command refuses to continue without confirmation. Pass --force in a script. --disable-prompt, or AKKA_DISABLE_PROMPTS=true, accepts every prompt.
Waiting: A command that starts durable work returns when the trainer accepts the work. --wait follows it to a terminal phase, and --exit-status makes the exit code reflect the outcome. Interrupting a wait stops the status updates, but the work continues. A later wait reconnects to it.
Exit codes: A read exits with 0, whatever its content reports. A refusal, a failure under --exit-status, and a declined confirmation exit with 1.
Identifiers: A command that takes an ID accepts an unambiguous prefix unless its help says that the full ID is required. Datasets, workloads, and scoring bundles also accept their assigned names.

Command groups

The following table lists the command groups:

Group Manages

Group	Manages
`datasets`	Training and evaluation datasets: register, name, list, and inspect.
`training base-models`	Base models allowed by the deployment: list, inspect, select, and deselect. See Base models.
`training endpoints`	Model inference endpoints: create and delete endpoints; list, inspect, or detach their models; send an input; and forward a local address. See Endpoints.
`training workloads`	Workloads, their evaluation settings, model references, and history.
`training runs`	Training runs: start, wait, pause, resume, cancel, and branch. Also metrics, hyperparameters, snapshots, TensorBoard, and the Grafana dashboard.
`training snapshots`	One committed snapshot, and its registration as a candidate model.
`training bundles`	Scoring bundles: push a directory or a zip file.
`training evaluations`	Evaluations of a model against a dataset: start, wait, report, and predictions.
`training comparisons`	A source snapshot evaluated with its branches under one pinned contract.
`training pipelines`	Ordered train and evaluate stages in one submission.
`trained-models`	The models that training produced, and base models registered as baselines.

datasets

Training and evaluation datasets: register, name, list, and inspect.

training base-models

Base models allowed by the deployment: list, inspect, select, and deselect. See Base models.

training endpoints

Model inference endpoints: create and delete endpoints; list, inspect, or detach their models; send an input; and forward a local address. See Endpoints.

training workloads

Workloads, their evaluation settings, model references, and history.

training runs

Training runs: start, wait, pause, resume, cancel, and branch. Also metrics, hyperparameters, snapshots, TensorBoard, and the Grafana dashboard.

training snapshots

One committed snapshot, and its registration as a candidate model.

training bundles

Scoring bundles: push a directory or a zip file.

training evaluations

Evaluations of a model against a dataset: start, wait, report, and predictions.

training comparisons

A source snapshot evaluated with its branches under one pinned contract.

training pipelines

Ordered train and evaluate stages in one submission.

trained-models

The models that training produced, and base models registered as baselines.

The CLI has other command groups. models, budget, pricing-catalog, routing-policies, rulesets, use-cases, eval, registry, and the remaining groups operate other Akka Optimize services. This guide doesn’t cover them.

Every command answers --help with its flags and examples.