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 vector stores with version management, metadata support, and unique ID referencing.

Upload Files

Command

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

Options

--strategy fast|high_quality - Processing strategy (default: fast)
--contextualization - Enable context preservation (default: false)
--metadata <json> - JSON metadata for uploaded files
--dry-run - Preview what would be uploaded without uploading
--parallel <n> - Number of concurrent uploads (default: 5, range: 1 - 20)
--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,
    "metadata": {
      "project": "my-project"
    }
  },
  "files": [
    {
      "path": "docs/**/*.md",
      "metadata": {
        "category": "documentation"
      }
    },
    {
      "path": "README.md",
      "strategy": "high_quality",
      "contextualization": true,
      "metadata": {
        "importance": "high"
      }
    }
  ]
}

YAML format:

version: "1.0"

defaults:
  strategy: fast
  contextualization: false
  metadata:
    project: my-project

files:
  - path: "docs/**/*.md"
    metadata:
      category: documentation
  - path: README.md
    strategy: high_quality
    contextualization: true
    metadata:
      importance: high

Manifest properties:

version - Manifest format version (currently "1.0")
defaults - Default settings applied to all files
- strategy - Default processing strategy
- contextualization - Default context preservation setting
- 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 - Specific contextualization for this pattern
- metadata - Additional metadata for this pattern (merged with defaults)

Examples

# Upload markdown files
mxbai vs upload "My Documents" "*.md"

# Upload multiple file types
mxbai vs upload "My Documents" "*.md" "docs/**/*.pdf"

# Upload with high quality processing
mxbai vs upload "My Documents" "*.pdf" --strategy high_quality

# Upload with contextualization
mxbai vs upload "My Documents" "*.md" --contextualization

# Upload with metadata
mxbai vs upload "My Documents" "*.md" --metadata '{"category": "docs"}'

# Dry run to preview upload
mxbai vs upload "My Documents" "*.md" --dry-run

# Upload with manifest file (JSON or YAML)
mxbai vs upload "My Documents" --manifest upload-manifest.json
mxbai vs upload "My Documents" --manifest upload-manifest.yaml

Upload Summary Information

The upload command displays strategy and contextualization information in different formats:

Normal Uploads

Show configuration in the summary after completion:

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

Manifest Uploads

Show configuration beside each file as it's processed:

✓ docs/api.md (15.2 KB) [fast, no-context]
✓ README.md (8.5 KB) [high_quality, contextualized]
✓ guide.md (1.6 KB) [fast, no-context]

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

List Files

Command

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

Alias: mxbai vs 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 vector store
mxbai vs files list "My Documents"

# List using alias
mxbai vs files ls "My Documents"

# List only completed files
mxbai vs files list "My Documents" --status completed

# List with limit
mxbai vs files list "My Documents" --limit 50

# List failed files for troubleshooting
mxbai vs files list "My Documents" --status failed

Get File Details

Command

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

Options

None

Examples

# Get details of a specific file
mxbai vs files get "My Documents" "file_abc123"

# Get file details using vector store ID
mxbai vs files get vs_abc123 "file_def456"

Delete File

Command

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

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

Options

--force - Skip confirmation prompt

Examples

# Delete file with confirmation
mxbai vs files delete "My Documents" "file_abc123"

# Delete file without confirmation
mxbai vs files delete "My Documents" "file_abc123" --force

# Delete using alias
mxbai vs files rm "My Documents" "file_abc123" --force

# Delete from vector store by ID
mxbai vs files delete vs_abc123 "file_def456" --force

Vector Store Management

Create, list, get, update, and delete vector stores.

Search through vector store content using natural language queries.

Last updated: July 5, 2025

File Management

On this page