CLI commands for training

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.

akka is a command group of the akka CLI. To install the akka CLI, see Install the Akka CLI.

Connect to a trainer

The AKKA_OPTIMIZE_URL environment variable specifies the address of your Akka project’s route. akka uses this address to reach the trainer, the artifact registry, and the other services. Set it once for a deployed project. akka route get <route> shows the route’s hostname.

Set the address and confirm that the trainer responds:

export AKKA_OPTIMIZE_URL=https://optimize.example.akka.services
akka status

To reach one service at another address, set that service’s own variable, such as TRAINER_URL or REGISTRY_URL. A service’s own variable takes precedence over AKKA_OPTIMIZE_URL for that service only. The --trainer-url flag on any command takes precedence over both for the trainer. To use the route for every service, unset them:

unset TRAINER_URL REGISTRY_URL

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 and the registry. A service your project’s route does not map appears with an error at the route’s address. training info reports the trainer’s backend. It exits with a non-zero status when the service does not respond or has not finished starting, 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.

The artifact registry holds datasets and scoring bundles. akka reaches the registry at AKKA_OPTIMIZE_URL too, or at REGISTRY_URL where you set it.

Authenticate

akka uses the login of 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 do not 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 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 wide adds detail where a command has more to show, such as the settings in training runs get, and is the same as text elsewhere. -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 is not 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 a run, a pipeline or an evaluation returns when the trainer accepts the work. --wait follows it to a terminal phase, and --exit-status makes the exit code reflect the outcome. endpoints create --wait returns when the endpoint answers. adapters import follows the import until it is registered or refused. 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, except training info, which exits with a non-zero status while the trainer has not finished starting. 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. Training projects also accept their assigned names. Datasets and scoring bundles take a registry reference, such as triage/train, triage/train:v3, or triage/train:candidate.

Command groups

The following table lists the command groups:

Group Manages

Group	Manages
`registry datasets`	Training and evaluation datasets in the artifact registry: register, list, inspect versions, read objects, and move aliases. See Datasets.
`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 projects`	Training projects, their evaluation settings, and history. See Training projects.
`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 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.
`registry models`	Models in the artifact registry: the versions that training produced, base models, and the aliases that mark a candidate or a champion. See Evaluation.
`registry bundles`	Scoring bundles in the artifact registry. See Scoring bundles.
`registry images`	Images that dataset examples reference, uploaded on their own. `registry datasets register` uploads the images an example references, so you need this group only to upload images ahead of time.

registry datasets

Training and evaluation datasets in the artifact registry: register, list, inspect versions, read objects, and move aliases. See Datasets.

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 projects

Training projects, their evaluation settings, and history. See Training projects.

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 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.

registry models

Models in the artifact registry: the versions that training produced, base models, and the aliases that mark a candidate or a champion. See Evaluation.

registry bundles

Scoring bundles in the artifact registry. See Scoring bundles.

registry images

Images that dataset examples reference, uploaded on their own. registry datasets register uploads the images an example references, so you need this group only to upload images ahead of time.

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

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