Installation & Setup

Prerequisites

Before installing the mxbai CLI, ensure you have:

• Node.js version 20.0 or higher
• A package manager
• A Mixedbread API key (get one here)

Installation Methods

Global Installation (Recommended)

Install the CLI globally to use it from any directory:

npm install -g @mixedbread/cli

Local Installation

For project-specific installations:

npm install --save-dev @mixedbread/cli

When installed locally, use npx mxbai or add scripts to your package.json:

{
  "scripts": {
    "mxbai": "mxbai"
  }
}

Verify Installation

After installation, verify the CLI is working:

mxbai --version

Upgrading the CLI

Global Upgrade

To upgrade a globally installed CLI to the latest version:

npm install -g @mixedbread/cli@latest

Local Upgrade

For project-specific installations:

npm install --save-dev @mixedbread/cli@latest

Authentication

To use the CLI, you need a Mixedbread API key. The CLI checks for authentication in this order:

1. Command line flag: --api-key mxb_xxxxx
2. Environment variable: export MXBAI_API_KEY=mxb_xxxxx
3. Configuration file: mxbai config set api_key mxb_xxxxx

Quick Setup

The easiest way to get started is with an environment variable:

export MXBAI_API_KEY=mxb_xxxxx

For persistent configuration across sessions, use the config file:

mxbai config set api_key mxb_xxxxx

Learn more about configuration options in the Configuration Guide.

Shell Completion

The CLI supports intelligent tab completion for commands, subcommands, and store names.

Installation

# Install completion (auto-detects your shell)
mxbai completion install

# Install completion for a specific shell
mxbai completion install --shell bash
mxbai completion install --shell zsh
mxbai completion install --shell fish
mxbai completion install --shell pwsh

Supported shells: bash, zsh, fish, pwsh (PowerShell)

After installation, restart your shell or reload your shell configuration:

• bash: source ~/.bashrc or restart terminal
• zsh: source ~/.zshrc or restart terminal
• fish: Completion is ready to use (fish auto-loads completions)
• pwsh: . $PROFILE or restart terminal

Dynamic Store Name Completion

The CLI provides intelligent tab completion for store names in commands:

# Tab completion shows your store names
mxbai store get [TAB]           # Shows: store1 store2 my-docs ...
mxbai store delete [TAB]        # Shows: store1 store2 my-docs ...
mxbai store sync [TAB]          # Shows: store1 store2 my-docs ...
mxbai store upload [TAB]        # Shows: store1 store2 my-docs ...

# Also works with files subcommands
mxbai store files list [TAB]    # Shows: store1 store2 my-docs ...

How it works:

• Store names are cached locally for instant completion (no API latency)
• Cache updates automatically when you create, update, delete, or list stores
• Supports multiple API keys - completions show stores for your current default key
• Manual refresh available: mxbai completion refresh

Cache management:

• Caches up to 50 most recent store names per API key
• Cache location follows your config directory:
  • Linux/Unix: ~/.config/mixedbread/completion-cache.json
  • macOS: ~/Library/Application Support/mixedbread/completion-cache.json
  • Windows: %APPDATA%\mixedbread\completion-cache.json

Managing Completion

# Remove completion
mxbai completion uninstall

# Refresh store name cache
mxbai completion refresh