MosaicML CLI

0.8.3 · active · verified Fri Apr 17

The `mosaicml-cli` provides a command-line interface for interacting with Databricks Mosaic AI training. It allows users to authenticate, manage runs, models, and clusters directly from their terminal. The current version is 0.8.3, and new versions are released periodically to align with updates to the Mosaic AI platform.

Common errors

```
'mosaicml' is not recognized as an internal or external command, operable program or batch file.
```
cause The `mosaicml` command-line entry point is not in your system's PATH, or the installation failed.

fix Ensure `pip install mosaicml-cli` completed successfully. Verify that your Python's `Scripts` or `bin` directory (where CLI tools are installed) is included in your system's PATH environment variable.
```
Error: Not logged in. Please run 'mosaicml login'.
```
cause The CLI is not authenticated with the Mosaic AI platform.

fix Run `mosaicml login` and follow the browser-based authentication flow. Alternatively, set the `MOSAICML_API_KEY` and `MOSAICML_API_URL` environment variables manually.
```
The installed Python version is X.Y.Z, but mosaicml-cli requires Python >= 3.11.
```
cause Your active Python environment does not meet the minimum version requirement for `mosaicml-cli`.

fix Upgrade your Python installation to version 3.11 or newer. If you have multiple Python versions, switch to an environment with Python 3.11+ before installing/running `mosaicml-cli`.
```
Error: Could not find configuration file at 'path/to/my_config.yaml'
```
cause Commands like `mosaicml run` require a YAML configuration file to define the training job.

fix Provide the correct path to your configuration file (e.g., `mosaicml run ./my_config.yaml`) or ensure the file exists at the specified location. Consult the documentation for examples of `config.yaml`.

Warnings

gotcha Common confusion between `mosaicml-cli` and `mosaicml` library. `mosaicml-cli` is solely for command-line interaction. For programmatic Python usage (e.g., in a script or application), you should install and import the `mosaicml` library.
Fix: If you intend to write Python code, install `pip install mosaicml`. If you need the command-line tool, use `pip install mosaicml-cli`.
gotcha All commands interacting with the Mosaic AI platform require prior authentication. Failure to authenticate will result in 'Not logged in' errors.
Fix: Run `mosaicml login` to authenticate your session, or ensure `MOSAICML_API_KEY` and `MOSAICML_API_URL` environment variables are set.
breaking As a relatively new CLI, command names, arguments, and configuration schemas may evolve in minor or patch releases, especially as the underlying Mosaic AI platform updates.
Fix: Always refer to the official documentation or the `mosaicml <command> --help` output for the most up-to-date syntax. Keep your CLI updated with `pip install --upgrade mosaicml-cli`.
gotcha `mosaicml-cli` requires Python 3.11 or higher. Using an older Python version will lead to installation failures or runtime errors.
Fix: Ensure your Python environment is at least 3.11. Consider using `pyenv` or `conda` to manage multiple Python versions.

Install

pip install mosaicml-cli Install current stable version

Imports

app
```
from mosaicml_cli.main import app
```
This is the internal Typer application object for the CLI. End-users typically interact via the `mosaicml` command in the terminal, not by importing this library programmatically. For Python SDK functionality, install and use the `mosaicml` library (without '-cli').

Quickstart

The most crucial step is to log in using `mosaicml login`. This authenticates your CLI session with the Mosaic AI platform. After successful login, you can execute various commands, such as listing models or initiating training runs.

mosaicml login
# Follow the on-screen instructions to authenticate via a browser.

# List available models (requires authentication)
mosaicml list models

# Example of running a training job (requires a config.yaml file and an authenticated session)
# This command assumes you have a 'config.yaml' file in your current directory.
# For a real quickstart, replace 'path/to/my_config.yaml' with your actual path.
# If you don't have one, just run 'mosaicml list models' as a basic check.
# mosaicml run path/to/my_config.yaml

view raw JSON →