File Management

Files serve as the foundation for all content processing workflows in Mixedbread. They provide secure upload, storage, and retrieval of documents with support for various file types including PDFs, images, and structured data. Manage files within your stores with version management, metadata support, and unique ID referencing.

Upload Files

Command

mxbai store upload <name-or-id> <patterns...> [options]

Options

--strategy fast|high_quality - Processing strategy (default: fast)
--contextualization - Deprecated: Now configured at store level using mxbai store create --contextualization. This flag is ignored and will be removed in a future version.
--metadata <json> - JSON metadata for uploaded files
--dry-run - Preview what would be uploaded without uploading
--parallel <n> - Number of concurrent uploads (default: 100, range: 1 - 200)
--unique - Update existing files instead of creating duplicates
--manifest <file> - Upload using manifest file

Manifest File Format

The manifest file allows you to define complex upload configurations with different settings for different file patterns. Both JSON (.json) and YAML (.yaml or .yml) formats are supported.

JSON format:

{
  "version": "1.0",
  "defaults": {
    "strategy": "fast",
    // "contextualization": false, // Deprecated - now configured at store level
    "metadata": {
      "project": "my-project"
    }
  },
  "files": [
    {
      "path": "docs/**/*.md",
      "metadata": {
        "category": "documentation"
      }
    },
    {
      "path": "README.md",
      "strategy": "high_quality",
      // contextualization is deprecated - configure at store level instead
      "metadata": {
        "importance": "high"
      }
    }
  ]
}

YAML format:

version: "1.0"

defaults:
  strategy: fast
  # contextualization: false # Deprecated - now configured at store level
  metadata:
    project: my-project

files:
  - path: "docs/**/*.md"
    metadata:
      category: documentation
  - path: README.md
    strategy: high_quality
    # contextualization is deprecated - configure at store level instead
    metadata:
      importance: high

Manifest properties:

version - Manifest format version (currently "1.0")
defaults - Default settings applied to all files
- strategy - Default processing strategy
- contextualization - (Deprecated) Include metadata in chunk embeddings to improve search relevance - now configured at store level
- metadata - Default metadata for all files
files - Array of file upload configurations
- path - Glob pattern for files to upload
- strategy - Specific strategy for this pattern
- contextualization - (Deprecated) Contextualization for this pattern - now configured at store level
- metadata - Additional metadata for this pattern (merged with defaults)

Examples

# Upload markdown files
mxbai store upload "my-knowledge-base" "*.md"

# Upload multiple file types
mxbai store upload "my-knowledge-base" "*.md" "docs/**/*.pdf"

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

# Deprecated: contextualization is now configured at the store level
# mxbai store upload "my-knowledge-base" "*.md" --contextualization

# Upload with metadata
mxbai store upload "my-knowledge-base" "*.md" --metadata '{"category": "docs"}'

# Dry run to preview upload
mxbai store upload "my-knowledge-base" "*.md" --dry-run

# Upload with manifest file (JSON or YAML)
mxbai store upload "my-knowledge-base" --manifest upload-manifest.json
mxbai store upload "my-knowledge-base" --manifest upload-manifest.yaml

Upload Summary Information

The upload command displays strategy information in the summary after completion:

✓ 5 files uploaded successfully
Strategy: fast
Total size: 25.3 KB

For manifest uploads, configuration is shown beside each file:

✓ docs/api.md (15.2 KB) [fast]
✓ README.md (8.5 KB) [high_quality]
✓ guide.md (1.6 KB) [fast]

This allows you to see exactly which strategy was applied to each file, making it easy to verify that your manifest configuration is working as expected.

List Files

Command

mxbai store files list <name-or-id> [options]

Alias: mxbai store files ls <name-or-id>

Options

--status <status> - Filter by status: pending, in_progress, cancelled, completed, failed
--limit <n> - Limit number of results

Examples

# List all files in store
mxbai store files list "my-knowledge-base"

# List using alias
mxbai store files ls "my-knowledge-base"

# List only completed files
mxbai store files list "my-knowledge-base" --status completed

# List with limit
mxbai store files list "my-knowledge-base" --limit 50

# List failed files for troubleshooting
mxbai store files list "my-knowledge-base" --status failed

Get File Details

Command

mxbai store files get <name-or-id> <file-id>

Options

None

Examples

# Get details of a specific file
mxbai store files get "my-knowledge-base" "f47ac10b-58cc-4372-a567-0e02b2c3d479"

# Get file details using store ID
mxbai store files get "my-knowledge-base" "b2c3d4e5-f6a7-8901-bcde-f23456789012"

Delete File

Command

mxbai store files delete <name-or-id> <file-id> [options]

Alias: mxbai store files rm <name-or-id> <file-id>

Options

--yes, -y - Skip confirmation prompt

Examples

# Delete file with confirmation
mxbai store files delete "my-knowledge-base" "f47ac10b-58cc-4372-a567-0e02b2c3d479"

# Delete file without confirmation
mxbai store files delete "my-knowledge-base" "f47ac10b-58cc-4372-a567-0e02b2c3d479" --yes

# Delete using alias
mxbai store files rm "my-knowledge-base" "f47ac10b-58cc-4372-a567-0e02b2c3d479" --yes

# Delete from store by ID
mxbai store files delete "my-knowledge-base" "b2c3d4e5-f6a7-8901-bcde-f23456789012" --yes

File Management

On this page