Skip to content

Installation Guide

YAICLI can be installed using several methods. Choose the one that best suits your needs.

Prerequisites

  • Python 3.10 or higher

Installation Methods

The simplest way to install YAICLI is using pip:

pip install yaicli

Using pipx (Isolated Environment)

If you prefer to install the tool in an isolated environment:

pipx install yaicli

Using uv (Faster Installation)

For faster installation with the uv package manager:

uv tool install yaicli

Installing with Optional Dependencies

YAICLI offers several optional dependency groups that you can install based on your needs:

All Dependencies

# Using pip
pip install 'yaicli[all]'

# Using uv
uv tool install 'yaicli[all]'

Specific Provider Support

# Using pip
pip install 'yaicli[ollama,cohere,doubao,huggingface,gemini,mistral]'

# Using uv
uv tool install 'yaicli[ollama,cohere,doubao,huggingface,gemini,mistral]'

Installing from Source

For the latest development version:

git clone https://github.com/belingud/yaicli.git
cd yaicli
pip install .

Verifying Installation

To verify that YAICLI was installed correctly:

ai --version            # fast path: prints the version, no config writes
ai --help               # full command reference
ai --list-functions     # should list 12 builtin tools (they work out of the box)
ai --list-providers     # should list the provider keys

python -m yaicli --version works as well if the ai script is not on your PATH.

First-Time Setup

After installation, run a real command once (for example ai "hi"); the default configuration file is created on first use:

ai "hi"

Then edit the configuration file to add your API key and customize settings. The config directory is resolved in this order: YAI_CONFIG_DIR → XDG_CONFIG_HOME/yaicli → %APPDATA%/yaicli (Windows) → ~/.config/yaicli. The file is created with mode 0600 because it may contain an API key; alternatively export the key and skip editing the file (plain ai with no prompt only prints help and does not create state):

export YAI_API_KEY="sk-..."

# Open the config with your preferred editor (default path on Linux/macOS)
nano ~/.config/yaicli/config.ini

Upgrading

Upgrade the package the same way you installed it:

pip install -U yaicli        # pip
pipx upgrade yaicli          # pipx
uv tool upgrade yaicli       # uv

Do I need --reinstall-functions?

Not for a normal upgrade. Since v0.19 the built-in tool definitions load directly from the installed package, so new versions take effect immediately.

You only need to refresh function files if you previously exported copies into the functions directory (ai --install-functions) or edited a built-in tool:

ai --reinstall-functions    # refresh exported built-in copies (custom files are kept)
ai --list-functions         # verify sources and stale-copy warnings

A user function file with the same tool name as a built-in wins over the built-in. If a stale copy is detected, YAICLI prints a one-line warning but keeps working.

See Upgrade Notes for the complete v0.19 change list (new config keys, environment filtering for shell tools, output truncation, permissions v2, headless flags, state paths) and rollback instructions.

Next Steps