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 - 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: 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,
    "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 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

# Upload with contextualization
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 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 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