---
title: Introduction
description: The mxbai CLI provides a powerful command-line interface for managing Mixedbread stores and files directly from your terminal.
tag: cli
url: /cli
---

## Overview

The mxbai CLI is a comprehensive tool for managing stores, uploading documents, and performing AI-powered search and question-answering operations. Built on top of the Mixedbread SDK, it provides an efficient command-line interface for all core platform features.

>**Note**
> New to Mixedbread? Check out our [API documentation](https://mixedbread.com/api-reference) to understand the underlying services that power the CLI.

## Key Features

- **[Store Management](https://mixedbread.com/cli/stores)**: Create, list, update, and manage your stores with comprehensive control.
- **[File Upload & Processing](https://mixedbread.com/cli/files)**: Upload files with intelligent processing strategies, metadata, and batch operations.
- **[Semantic Search](https://mixedbread.com/cli/search)**: Search through your stores using natural language queries with advanced filtering.
- **[Question Answering](https://mixedbread.com/cli/qa)**: Ask questions and get AI-powered answers based on your store content.
- **[Intelligent Sync](https://mixedbread.com/cli/sync)**: Sync files with Git-based change detection and intelligent processing strategies.
- **[Shell Completion](https://mixedbread.com/cli/installation#shell-completion)**: Set up tab completion for commands and subcommands to improve your CLI experience.

## Quick Start

### 1. Install the CLI

**npm:**
```bash
npm install -g @mixedbread/cli
```

**yarn:**
```bash
yarn global add @mixedbread/cli
```

**pnpm:**
```bash
pnpm add -g @mixedbread/cli
```

**bun:**
```bash
bun add -g @mixedbread/cli
```

### 2. Set your API key

```bash
# Option 1: Environment variable
export MXBAI_API_KEY=mxb_xxxxx

# Option 2: Config file (persistent)
mxbai config keys add mxb_xxxxx
```

### 3. Install shell completion (optional but recommended)

```bash
mxbai completion install
```

### 4. Create a store

```bash
mxbai store create "my-knowledge-base"
```

### 5. Upload files

```bash
# Basic upload
mxbai store upload "my-knowledge-base" "*.md" "docs/**/*.pdf"

# Upload with high-quality processing
mxbai store upload "my-knowledge-base" "**/*.md" --strategy high_quality
```

### 6. Search your content

```bash
mxbai store search "my-knowledge-base" "how to get started"
```

## Command Structure

The mxbai CLI is organized around store operations using the `store` subcommand:

### Configuration Management
- `mxbai config set <key> <value>` - Set configuration values
- `mxbai config get [key]` - Get configuration values
- `mxbai config keys add <key> [name]` - Add a new API key
- `mxbai config keys list` - List all API keys
- `mxbai config keys remove <name>` - Remove an API key
- `mxbai config keys set-default <name>` - Set the default API key

### Shell Completion
- `mxbai completion install` - Install shell completion
- `mxbai completion uninstall` - Uninstall shell completion
- `mxbai completion refresh` - Refresh completion cache for store names

### Store Management
- `mxbai store list` - List all stores
- `mxbai store create <name>` - Create a new store
- `mxbai store get <name-or-id>` - Get store details
- `mxbai store update <name-or-id>` - Update store settings
- `mxbai store delete <name-or-id>` - Delete a store

### File Operations
- `mxbai store upload <name-or-id> <patterns...>` - Upload files
- `mxbai store files list <name-or-id>` - List files in store
- `mxbai store files get <name-or-id> <file-id>` - Get file details
- `mxbai store files delete <name-or-id> <file-id>` - Delete a file

### Search & Query
- `mxbai store search <name-or-id> <query>` - Search store
- `mxbai store qa <name-or-id> <question>` - Ask questions about content

### Intelligent Sync
- `mxbai store sync <name-or-id> <patterns...>` - Intelligent sync with change detection

## Global Options

All commands support these global options:

- `--api-key <key>` - Actual API key for authentication
- `--saved-key <name>` - Name of saved API key from config
- `--base-url <url>` - Custom API base URL
- `--format <format>` - Output format: `table`, `json`, or `csv` (default: `table`)
- `--debug` - Enable debug output (equivalent to `MXBAI_DEBUG=true`)
- `--help` - Show help information for commands

## Environment Variables

The CLI supports the following environment variables:

- `MXBAI_API_KEY` - API key for authentication (must start with `mxb_`)
- `MXBAI_BASE_URL` - Custom API base URL
- `MXBAI_DEBUG` - Enable debug output (set to `true` or `1`)
- `MXBAI_CONFIG_PATH` - Override default config file location

## Authentication

The CLI looks for your API key in this order:

1. `--api-key` or `--saved-key` command line flags
2. `MXBAI_API_KEY` environment variable
3. Default API key from config file (platform-specific location):
   - Linux/Unix: `~/.config/mixedbread/config.json` (or `$XDG_CONFIG_HOME/mixedbread/config.json`)
   - macOS: `~/Library/Application Support/mixedbread/config.json`
   - Windows: `%APPDATA%\mixedbread\config.json`
   - Custom: Set `MXBAI_CONFIG_PATH` environment variable to override

### Multi-Organization Support

The CLI supports multiple API keys for different organizations or environments:

```bash
# Add API keys with descriptive names
mxbai config keys add mxb_xxxxx work
mxbai config keys add mxb_xxxxx personal

# Use a specific saved API key for a command
mxbai store upload "My Docs" "*.md" --saved-key work
mxbai store search "Knowledge Base" "query" --saved-key personal

# Or use an actual API key directly
mxbai store upload "My Docs" "*.md" --api-key mxb_xxxxx

# The last added key becomes default automatically
# Or explicitly set a default
mxbai config keys set-default personal
```

## Getting Help

Use the `--help` flag to get detailed information about any command:

```bash
# General help
mxbai --help

# Help for store commands
mxbai store --help

# Help for specific commands
mxbai store create --help
mxbai store upload --help
mxbai store search --help
```