CLI Configuration

The Chroma CLI stores configuration in your home directory under ~/.chroma/. This includes authentication credentials, profiles, and user preferences.

Configuration Directory

All CLI configuration is stored in:

~/.chroma/
├── credentials     # Profile credentials (API keys and tenant IDs)
└── config.json     # CLI configuration and preferences

Profiles

Profiles allow you to manage multiple Chroma Cloud accounts or teams from a single CLI installation.

Profile Structure

Profiles are stored in ~/.chroma/credentials as JSON:

credentials

{
  "default": {
    "api_key": "your-api-key",
    "tenant_id": "your-tenant-id"
  },
  "my-team": {
    "api_key": "team-api-key",
    "tenant_id": "team-tenant-id"
  }
}

Managing Profiles

chroma profile list

chroma profile use my-team

chroma profile show

chroma profile delete old-profile

chroma profile rename old-name new-name

Profile Naming Rules

Profile names must contain only alphanumeric characters, underscores, or hyphens
Names cannot be empty
Names are case-sensitive

CLI Configuration File

The ~/.chroma/config.json file stores CLI preferences:

config.json

{
  "current_profile": "default",
  "theme": "Dark",
  "show_updates": true,
  "sample_apps": {
    "installed": {
      "basic-rag": "1.0.0",
      "multimodal-search": "1.2.0"
    }
  }
}

Configuration Fields

string

The name of the currently active profile. Used for all Chroma Cloud commands.

enum

default:"Dark"

UI theme for the collection browser. Options: Dark, Light

boolean

default:"true"

Whether to show update notifications when a new CLI version is available

object

Tracks installed sample applications and their versions

Environment Variables

The CLI and Chroma clients support several environment variables:

Chroma Cloud Connection

.env

CHROMA_API_KEY=your-api-key
CHROMA_TENANT=your-tenant-id
CHROMA_DATABASE=your-database-name

These variables can be generated using:

chroma db connect my-database --env-vars

Or written to a .env file:

chroma db connect my-database --env-file

Local Development

CHROMA_HOST=http://localhost:8000
CHROMA_TENANT=default_tenant
CHROMA_DATABASE=default_database

Backend Development (Go)

For developing Chroma’s Go backend:

POSTGRES_HOST=localhost
POSTGRES_PORT=5432

Server Configuration

When running a local Chroma server with chroma run, you can use a YAML configuration file:

Configuration File Format

chroma-config.yaml

# Server settings
listen_address: "localhost"
port: 8000

# Data persistence
persist_path: "./chroma-data"

# Frontend configuration
frontend:
  # SQLite database settings
  sqlitedb:
    url: "./chroma-data/chroma.sqlite3"
  
  # CORS settings
  cors:
    allow_origins: ["*"]
    allow_credentials: true
    allow_methods: ["GET", "POST", "PUT", "DELETE"]
    allow_headers: ["*"]

Running with Config File

chroma run /path/to/chroma-config.yaml

When using a config file, the --path, --host, and --port flags are not available.

Authentication Flow

The default login method opens your browser:

chroma login

Steps:

CLI generates a temporary token
Opens browser to Chroma Cloud
You authenticate with your account
Select team (if applicable)
Credentials saved to ~/.chroma/credentials
Profile set as active

For CI/CD or automated workflows:

chroma login --api-key YOUR_API_KEY --profile ci-profile

Never commit API keys to version control. Use environment variables or secrets management.

Connection Priority

When connecting to Chroma, credentials are resolved in this order:

Command-line flags (--db, --host, etc.)
Environment variables (CHROMA_API_KEY, CHROMA_DATABASE)
Active profile from ~/.chroma/credentials
Interactive prompts (if needed)

Sample App Configuration

Installed sample apps include a config.json file:

sample_app/config.json

{
  "required_env_variables": [
    {
      "name": "OPENAI_API_KEY",
      "secret": true
    }
  ],
  "optional_env_variables": [
    {
      "name": "LOG_LEVEL",
      "secret": false
    }
  ],
  "startup_commands": {
    "Python": "python app.py",
    "Install dependencies": "pip install -r requirements.txt"
  }
}

The installer creates a .env file with:

sample_app/.env

CHROMA_API_KEY=your-api-key
CHROMA_DATABASE=your-database
CHROMA_TENANT=your-tenant-id
OPENAI_API_KEY=  # Set by user during installation

Security Best Practices

Protect Credentials File

The ~/.chroma/credentials file contains sensitive API keys. Ensure it has restricted permissions:

chmod 600 ~/.chroma/credentials

Use Separate Profiles

Create separate profiles for development, staging, and production:

chroma login --profile development
chroma login --profile production

Environment Variables in CI/CD

For automated deployments, use environment variables instead of profiles:

export CHROMA_API_KEY=${{ secrets.CHROMA_API_KEY }}
export CHROMA_TENANT=${{ secrets.CHROMA_TENANT }}
export CHROMA_DATABASE=production-db

Rotate API Keys

Regularly rotate your API keys and update profiles:

# Log in with new credentials
chroma login --profile my-team

# Or update via Chroma Cloud dashboard

Troubleshooting

Reset Configuration

To reset CLI configuration:

rm -rf ~/.chroma
chroma login  # Reconfigure

View Configuration

# Show current profile
chroma profile show

# List all profiles
chroma profile list

# View config file
cat ~/.chroma/config.json

Profile Not Found

If you see “No current profile found”:

# Login to create a profile
chroma login

# Or set an existing profile
chroma profile use my-team

Connection Issues

Verify your credentials:

# Test connection by listing databases
chroma db list

# Verify environment variables
echo $CHROMA_API_KEY

Configuration Examples

Multi-Environment Setup

# Development profile
chroma login --profile dev
chroma profile use dev

# Production profile
chroma login --profile prod
chroma profile use prod

# Switch between environments
chroma profile use dev    # Work on dev
chroma profile use prod   # Deploy to prod

Team Collaboration

# Each team member logs in
chroma login --profile company-team

# Share database names (not credentials)
chroma db list
chroma db connect shared-db --env-file

Local Development

# Run local server
chroma run --path ./dev-data

# In another terminal, browse collections
chroma browse my_collection --local

# Copy to cloud when ready
chroma copy --from-local --to-cloud --all --db staging

Login

Authenticate with Chroma Cloud

Profile Management

Manage multiple profiles

Database Commands

Create and manage databases

CLI Commands

Full command reference

Python Client

JavaScript Client

Go Client

CLI

CLI Configuration

Configuration Directory

Profiles

Profile Structure

Managing Profiles

Profile Naming Rules

CLI Configuration File

Configuration Fields

Environment Variables

Chroma Cloud Connection

Local Development

Backend Development (Go)

Server Configuration

Configuration File Format

Running with Config File

Authentication Flow

Connection Priority

Sample App Configuration

Security Best Practices

Troubleshooting

Reset Configuration

View Configuration

Profile Not Found

Connection Issues

Configuration Examples

Multi-Environment Setup

Team Collaboration

Local Development

Login

Profile Management

Database Commands

CLI Commands

​Configuration Directory

​Profiles

​Profile Structure

​Managing Profiles

​Profile Naming Rules

​CLI Configuration File

​Configuration Fields

​Environment Variables

​Chroma Cloud Connection

​Local Development

​Backend Development (Go)

​Server Configuration

​Configuration File Format

​Running with Config File

​Authentication Flow

​Interactive Browser Login

​Headless Login

​Connection Priority

​Sample App Configuration

​Security Best Practices

​Troubleshooting

​Reset Configuration

​View Configuration

​Profile Not Found

​Connection Issues

​Configuration Examples

​Multi-Environment Setup

​Team Collaboration

​Local Development

​Related Commands

Login

Profile Management

Database Commands

CLI Commands

Configuration Directory

Profiles

Profile Structure

Managing Profiles

Profile Naming Rules

CLI Configuration File

Configuration Fields

Environment Variables

Chroma Cloud Connection

Local Development

Backend Development (Go)

Server Configuration

Configuration File Format

Running with Config File

Authentication Flow

Interactive Browser Login

Headless Login

Connection Priority

Sample App Configuration

Security Best Practices

Troubleshooting

Reset Configuration

View Configuration

Profile Not Found

Connection Issues

Configuration Examples

Multi-Environment Setup

Team Collaboration

Local Development

Related Commands