Aim CLI#

Aim provides command-line interface for launching Aim UI and tracking servers, managing Aim repositories, logged data and Aim apps.

Below is a brief summary table of Aim CLI commands:

Command	Description
init	Initializes or re-initializes an Aim repository at a given directory.
server	Starts the Aim remote tracking server for real-time logging.
ui	Launches the Aim web-based UI for interactive data exploration.
packages	Command group for managing Aim packages/apps.
apps	Command group for managing Aim packages/apps. Alias for aim packages
containers	Command group for managing containers within an Aim repository.
migrate	Migrates the data format of a specified Aim repository.
version	Prints version of installed Aim and exists.

API Reference for Aim Command Line Interface#

The following section describes Aim CLI commands in detail.

aim#

The main entry point for Aim CLI: a toolset for tracking and managing machine learning experiments.

The Aim CLI provides a suite of commands to facilitate the tracking, visualization, and management of machine learning experiments. The toolset is designed to seamlessly integrate with various stages of the ML workflow, from initializing repositories and tracking experiments in real-time, to visualizing results through the UI and managing custom packages or apps.

aim [OPTIONS] COMMAND [ARGS]...

init#

Initializes or re-initializes an Aim repository at a given directory.

This command facilitates the creation of a new Aim repository at the specified directory. If a repository already exists in the given directory, users are prompted to either re-initialize or retain the existing repository. Re-initializing results in an empty Aim repository.

The command is designed to ensure smooth tracking and management of machine learning experiments using the Aim platform.

aim init [OPTIONS]

Options

--repo <repo>#

-y, --yes#: Automatically confirm prompt

server#

Starts the Aim remote tracking server for real-time logging.

The Aim tracking server facilitates real-time logging of experiments from remote locations. This command launches the server with specified configurations, including host, port, and associated repository.

Like the UI, the server can also run in production or development mode.

aim server [OPTIONS]

Options

-h, --host <host>#

-p, --port <port>#

--repo <repo>#

--ssl-keyfile <ssl_keyfile>#

--ssl-certfile <ssl_certfile>#

--base-path <base_path>#

--log-level <log_level>#

--dev#

-y, --yes#: Automatically confirm prompt

ui#

Launches the Aim web-based UI for interactive data exploration.

This command starts the Aim UI, allowing users to visually explore, compare, and understand their machine learning experiments. The UI is customizable with various options to determine the host, port, associated repository, and more.

The UI can operate in either production or development mode, with the latter offering features beneficial for Aim developers.

aim ui [OPTIONS]

Options

-h, --host <host>#

-p, --port <port>#

-w, --workers <workers>#

--uds <uds>#

--repo <repo>#

--package, --pkg <package>#

--dev#

--ssl-keyfile <ssl_keyfile>#

--ssl-certfile <ssl_certfile>#

--base-path <base_path>#

--profiler#

--log-level <log_level>#

-y, --yes#: Automatically confirm prompt

packages#

Command group for managing Aim packages and apps.

Provides functionalities to create, synchronize, add, remove, and list Aim packages. Each sub-command pertains to a specific operation related to package management. The system ensures smooth interaction between Aim repositories and the packages, allowing for seamless integration and utilization.

aim packages [OPTIONS] COMMAND [ARGS]...

add#

This command associates a specified package with an Aim repository. This means that the repository will recognize the package and be able to utilize its functionalities.

aim packages add [OPTIONS]

Options

-n, --name <name>#: Required

--repo <repo>#

create#

Initializes a new Aim package in the current working directory.

This command sets up the directory structure and necessary files for a new Aim package. If the –install option is provided, the package will also be installed in the current Python environment using pip.

aim packages create [OPTIONS]

Options

-n, --name <name>#: Required

-i, --install#

-v, --verbose#

ls#

Display all registered packages in an Aim repository.

This command lists all packages that are currently associated with a specified Aim repository. It provides a tabulated view of the package attributes.

aim packages ls [OPTIONS]

Options

--repo <repo>#

rm#

Deregister a package from an Aim repository.

This command removes the association between a specified package and an Aim repository. Post this operation, the repository will no longer recognize or be able to use the package.

aim packages rm [OPTIONS]

Options

-n, --name <name>#: Required

--repo <repo>#

sync#

Continuously sync package source code with an Aim repository.

This command monitors the source directory of a specified package for changes, and updates the corresponding Aim repository in real-time. It ensures the repository reflects the latest version of the package code.

aim packages sync [OPTIONS]

Options

-n, --name <name>#: Required

--repo <repo>#

containers#

Command group for managing containers within an Aim repository.

This command group provides functionalities to list, delete, copy, move, and close containers in an Aim repository. Each sub-command pertains to a specific operation on the containers.

By default, the command group targets the Aim repository at ‘aim://0.0.0.0:53800’. A different repository can be specified using the ‘–repo’ option.

aim containers [OPTIONS] COMMAND [ARGS]...

Options

--repo <repo>#

close#

Forcefully close specified failed or stalled containers.

This command attempts to close one or more containers that might have failed or stalled. This is a forceful operation, and you’ll be warned to ensure the containers are not actively running.

aim containers close [OPTIONS] [HASHES]...

Options

-y, --yes#: Automatically confirm prompt

Arguments

HASHES#: Optional argument(s)

cp#

Copy specified containers to another Aim repository.

This command copies one or more containers identified by their hashes from the current Aim repository to a destination repository.

aim containers cp [OPTIONS] [HASHES]...

Options

--destination <destination>#: Required

Arguments

HASHES#: Optional argument(s)

ls#

List all available containers within an Aim repository.

This command retrieves and displays containers from a specified Aim repository in a tabulated format. For each container, various properties, as determined by the Aim system, are shown. The default display format is ‘psql’, which structures the output in a PostgreSQL-like table style.

aim containers ls [OPTIONS]

mv#

Move specified containers to another Aim repository.

This command moves one or more containers identified by their hashes from the current Aim repository to a destination repository. After the move, the containers will no longer exist in the source repository.

aim containers mv [OPTIONS] [HASHES]...

Options

--destination <destination>#: Required

Arguments

HASHES#: Optional argument(s)

rm#

Delete specified containers from an Aim repository.

This command deletes one or more containers identified by their hashes from the Aim repository. You will be prompted for confirmation before the containers are deleted unless the –yes option is used.

aim containers rm [OPTIONS] [HASHES]...

Options

-y, --yes#: Automatically confirm prompt

Arguments

HASHES#: Optional argument(s)

migrate#

Migrates the data format of a specified Aim repository.

This command checks the version of the data format used by the provided Aim repository. If the repository is not up-to-date, the command will migrate its data to the latest format. During migration, the original data is backed up in a separate directory, ensuring data integrity and allowing for potential rollbacks if needed.

The migration process might be time-consuming, especially for large repositories. Users are prompted to confirm the migration operation unless the –yes flag is provided.

aim migrate [OPTIONS]

Options

--repo <repo>#: Required

--run <run>#

-y, --yes#: Automatically confirm prompt

version#

Prints version of installed Aim and exists.

aim version [OPTIONS]