cli.md

Aim CLI

Aim CLI offers a simple interface to easily organize and record your experiments. Paired with the Python Library, Aim is a powerful utility to record, search and compare AI experiments. Here are the set of commands supported:

Command	Description
init	Initialize the aim repository.
version	Displays the version of aim cli currently installed.
up	Runs Aim web UI for the given repo.
reindex	Process runs left in 'in progress' state and optimized finished runs.
server	Run aim remote tracking server accepting incoming RPC requests. Experimental feature.
runs	Manage run data for the given repo.
convert	Tool-set for converting 3rd party data into Aim readable format.
storage	Maintain/update Aim repository internal data formats.

init

This step is optional. Initialize the aim repo to record the experiments.

$ aim init

Creates .aim directory to save the recorded experiments to. Running aim init in an existing repository will prompt the user for re-initialization.

Args	Description
--repo <repo_path>	Path to parent directory of .aim repo. Current working directory by default.

Beware: Re-initialization of the repo clears .aim folder from previously saved data and initializes new repo. Note: This command is not necessary to be able to get started with Aim as aim is automatically initializes with the first aim function call.

version

Display the Aim version installed.

$ aim version

up

Start the Aim web UI locally.

$ aim up [ARGS]

Args	Description
-h | --host <host>	Specify host address.
-p | --port <port>	Specify port to listen to.
--repo <repo_path>	Path to parent directory of .aim repo. Current working directory by default.
--dev	Run UI in development mode.
--profiler	Enables API profiling which logs run trace inside .aim/profiler directory.
--log-level	Specifies log level for python logging package. WARNING by default, DEBUG when --dev option is provided.

reindex

Update index to include all runs in Aim repo which are left in progress.

$ aim reindex [ARGS]

Args	Description
--repo <repo_path>	Path to parent directory of .aim repo. Current working directory by default.
--finalize-only	Only finalize runs left in 'in progress' state. Do not attempt runs optimization.

server

Run a gRPC server to collect tracked data from remote clients.

$ aim server [ARGS]

Args	Description
--repo <repo_path>	Path to parent directory of .aim repo. Current working directory by default.
-h | --host <host>	Specify host address.
-p | --port <port>	Specify port to listen to. Default is 53800.
-w | --workers <N>	Specify number of gPRC workers. Default is 1 worker.
--ssl-keyfile	Specify path to keyfile for secure connection.
--ssl-certfile	Specify path to cert. file for secure connection.
--log-level	Specifies log level for python logging package. WARNING by default.

runs

Upgrade Aim repository runs data.

$ aim runs [ARGS] SUBCOMMAND

Args	Description
--repo <repo_path>	Path to parent directory of .aim repo. Current working directory by default.

runs subcommands

Sub-command	Description
ls	List runs in aim repository.
rm	Remove run data for given runs hashes. At least one run should be specified.
cp	Copy run data for given runs hashes. At least one run should be specified.
mv	Move run data for given runs hashes. At least one run should be specified.
upload	Create snapshot of .aim directory in cloud. Bucket name should be specified.

Global expression (*) support is available for run hashes. If hash contains *, it must be enclosed within quotes ('') as bash resolves the expression before passing it to aim runs command.

$ aim runs ls

$ aim runs rm [HASH] ...

$ aim runs cp [ARGS] [HASH] ...

Args	Description
--destination <dest_repo_path>	Path to destination repo. Required.

$ aim runs mv [ARGS] [HASH] ...

Args	Description
--destination <dest_repo_path>	Path to destination repo. Required.

$ aim runs upload [ARGS] ...

Args	Description
--bucket <bucket_name>	Name of cloud storage bucket. Required.

convert

Tool-set for converting 3rd party data into Aim readable format.

$ aim convert [ARGS] SUBCOMMAND

Args	Description
--repo <repo_path>	Path to parent directory of .aim repo. Current working directory by default.

convert subcommands

Sub-command	Description
tensorboard	Convert from Tensorboard logs.
mlflow	Convert from MLFlow logs.

Sub-command: tensorboard

Options	Description
--flat	Disregard context directory and treat them as distinct run directories. Inactive by default.
--no-cache	Ignore previously cached results and process the logs entirely. Disabled by default.

Sub-command: mlflow

Options	Description
--tracking_uri <logs_uri>	MLFlow logs URI. Can be either an HTTP/HTTPS URI for a remote server, a database connection string, or a local path.
-e | --experiment <exp_name>	MLFlow Experiment name. If specified, only runs for exp_name will be converted.

storage

Perform various maintenance operations on Aim repository.

$ aim storage [ARGS] SUBCOMMAND

Args	Description
--repo <repo_path>	Path to parent directory of .aim repo. Current working directory by default.

storage subcommands

Sub-command	Description
upgrade 2to3	Upgrades legacy Aim repository from 2.x to 3.0.
upgrade 3.11+	Update metric sequence data format for given runs. At least one run should be specified.
restore	Rollback Run to old metric format if run backup is available.

Sub-command: update 2to3

$ aim storage ugrade 2to3 [ARGS]

Args	Description
--skip-failed-runs	Use this flag to skip runs which are failed/have missing or incomplete data.
--skip-checks	Use this flag to skip new repository consistency checks.
--drop-existing	Use this flag to clear old .aim directory. By default old data is kept in .aim_legacy.

Sub-command: update 3.11+

$ aim storage upgrade 3.11+ [HASH] ...

Sub-command: restore

$ aim storage restore [HASH] ...