Skip to main content

Installation

Prerequisites:​

Ensure you have uv installed on your system. You can download it from docs.astral.sh.

The CLI requires Python 3.13 or newer. uv fetches and manages a compatible interpreter automatically, so a system-wide Python 3.13 is not required.

  uv tool install aichor-cli --index https://aichor-python-packages.aichor.ai --compile-bytecode
Dependency resolution issues

If you run into dependency resolution issues (e.g. version conflicts), try using the --index-strategy unsafe-best-match option:

uv tool install aichor-cli --index https://aichor-python-packages.aichor.ai --index-strategy unsafe-best-match --compile-bytecode
command not found: aichor

uv tool install places the aichor executable in ~/.local/bin, which is not on the PATH unless uv was installed with its standalone installer. Homebrew, pip, and conda installs of uv leave it off.

uv tool update-shell

Then open a new terminal and run aichor again.

Option 2 — Install with pip 🐍 
pip install --extra-index-url https://aichor-python-packages.aichor.ai aichor-cli

Plotting support (optional)​

The aichor experiments metrics plot command renders an experiment's metrics as a chart. Its rendering libraries (plotly for the interactive HTML chart, matplotlib for static images) are large and are needed by no other command, so they are shipped as an optional plot extra rather than in the base install. Every other command works without it; only the plot command requires the extra.

To install the CLI with plotting support, add the [plot] suffix to the package name:

uv tool install "aichor-cli[plot]" --index https://aichor-python-packages.aichor.ai --compile-bytecode

The rendering libraries are the largest part of the install, so --compile-bytecode is worth more here than anywhere else.

Add plotting support with pip 🐍 
pip install --extra-index-url https://aichor-python-packages.aichor.ai "aichor-cli[plot]"

An existing installation can be upgraded to include the extra by re-running the install command above with the [plot] suffix. Running the plot command without the extra installed prints an error explaining how to add it.

Usage​

To use AIchor CLI, run the following command:

aichor

An output similar to the following should be displayed:

Usage: aichor [OPTIONS] COMMAND [ARGS]...

  AIchor CLI

Options:
  --version  Show the version and exit.
  --help     Show this message and exit.

Commands:
  auth         Authentication commands
  context      Manage the CLI context
  local-repo   Manage the local repo
  engines      Operations on engines
  experiments  Operations on experiments
  projects     Operations on projects
  storage      Operations on project storage

Upgrading​

To upgrade to the latest version, run:

uv tool upgrade aichor-cli

uv reuses the index recorded at install time, so the --index flag does not need to be passed again.

Still on an older version after upgrading?

uv tool upgrade only resolves versions compatible with the interpreter the tool was installed with. Because the CLI requires Python 3.13 or newer, a tool installed against an older interpreter (e.g. 3.11 or 3.12) will not upgrade past the last release that supported it. It stays put without raising an error.

The fix is to reinstall, pinning a compatible interpreter:

uv tool install aichor-cli --index https://aichor-python-packages.aichor.ai --python 3.13 --force

The interpreter a tool is bound to can be inspected with uv tool list.