Configuration
The mxbai CLI provides flexible configuration management to set defaults, store credentials, and create aliases for common operations. Configuration is stored in platform-specific locations and can be managed using the mxbai config
commands.
Configuration File Location
Custom location
Override the default location by setting the MXBAI_CONFIG_PATH
environment variable:
Configuration Precedence
When using the CLI, configuration values are resolved in the following order (highest to lowest priority):
- Command-line flags - Direct CLI options (e.g.,
--strategy high_quality
) - Manifest entry - File-specific settings in manifest files (only applies to manifest uploads)
- Manifest defaults - Default settings in manifest files (only applies to manifest uploads)
- Config file - User configuration file settings
- Built-in defaults - CLI default values
This allows flexible configuration while maintaining predictable behavior. For example:
- If you set
defaults.upload.strategy = "high_quality"
in your config file, but use--strategy fast
on the command line, the command-line flag takes precedence. - When using manifest files, individual file settings override the manifest defaults, which in turn override your config file settings.
Set Configuration Values
Command
Examples
Get Configuration Values
Command
Examples
Configuration Options
API Authentication
Store your API key securely in the config file:
- Required format: Must start with
mxb_
- Security: Stored locally in your user directory
Upload Defaults
Configure default options for file uploads:
Processing Strategy
Choose between fast processing for speed or high quality processing for better search results.
- Config key:
defaults.upload.strategy
- Default:
fast
- Valid values:
fast
,high_quality
Contextualization
Enable context preservation to maintain relationships between document sections for more accurate search results.
- Config key:
defaults.upload.contextualization
- Default:
false
- Valid values:
true
,false
Parallel Uploads
Control how many files are uploaded simultaneously to optimize for your network and system resources.
- Config key:
defaults.upload.parallel
- Default:
5
- Valid range:
1
to20
Search Defaults
Configure default search behavior:
Number of Results
Set how many search results to return by default when searching your vector stores.
- Config key:
defaults.search.top_k
- Default:
10
- Valid range:
1
to100
Result Reranking
Enable AI-powered reranking to reorder search results based on relevance, improving the quality of top results.
- Config key:
defaults.search.rerank
- Default:
false
- Valid values:
true
,false
Vector Store Aliases
Create shortcuts for frequently used vector stores:
Then use aliases in commands:
Default Configuration
When no configuration is set, the CLI uses these default values:
Configuration File Structure
After customization, your configuration file might look like:
Common Configuration Examples
Development Setup
Optimize for speed during development:
Production Setup
Optimize for quality and accuracy:
CI/CD Setup
Configure for automated environments:
Debugging
Enable debug output to troubleshoot issues:
Next Steps
Now that you have the CLI configured, explore these features:
Vector Store Management
Create and manage your vector stores.
File Operations
Upload and manage documents.
Last updated: July 5, 2025