Mixedbread

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 ()

Installation Methods

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 .

Shell Completion

The CLI supports intelligent tab completion for commands, subcommands, and vector 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 Vector Store Name Completion

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

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

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

How it works:

  • Vector store names are cached locally for instant completion (no API latency)
  • Cache updates automatically when you create, update, delete, or list vector 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 vector 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 vector store name cache
mxbai completion refresh
Introduction
The mxbai CLI provides a powerful command-line interface for managing Mixedbread vector stores and files directly from your terminal.
Configuration
Manage CLI settings, defaults, and aliases to customize your mxbai experience.

Last updated: August 27, 2025