---
title: CLI Configuration
description: 'Set api_url, timeout, format and debug per profile, override them with IVYBLOOM_* environment variables or flags, and register a BYOK provider key.'
tags:
  - configuration
  - settings
  - profiles
  - themes
---

This page shows how to customize the ivybloom CLI's behavior, output formats, profiles, themes, and default settings. Reach for it when you want per-environment profiles, machine-readable output for scripting, or your own AI keys via BYOK. Your configuration can sync with your platform profile, so the same settings follow you between the CLI and the web app. For the broader command set, see the [CLI overview](/docs/cli).

  beginner

## Configuration

Customize CLI behavior, output formats, and default settings.

---

## Configuration Commands

### View Current Settings

```bash
ivybloom config show
```

### List All Options

```bash
ivybloom config list
```

### Get a Specific Setting

```bash
ivybloom config get api_url
ivybloom config get timeout
```

### Set a Value

```bash
ivybloom config set format json
ivybloom config set timeout 60
ivybloom config set debug true
```

### Reset to Defaults

```bash
ivybloom config reset
```

### View JSON Schema

```bash
ivybloom config schema
```

Shows the JSON schema of all available configuration keys, types, and defaults.

### Validate Configuration

```bash
ivybloom config validate
ivybloom config validate --check-auth  # Verify credentials
ivybloom config validate --check-api   # Test API connectivity
ivybloom config validate --all         # Run all checks
```

---

## Configuration Options

### Core Settings

| Key | Default | Description |
|-----|---------|-------------|
| `api_url` | Production URL | API endpoint URL |
| `timeout` | `30` | Request timeout in seconds |
| `format` | `table` | Default output format (table, json, csv, yaml) |
| `debug` | `false` | Enable debug mode |

```bash
ivybloom config set format json
ivybloom config set timeout 60
```

### Profile Display

| Key | Default | Description |
|-----|---------|-------------|
| `profile_display.show_org_name` | `true` | Show organization name |
| `profile_display.show_tier_badge` | `true` | Show tier badge |

### Tier Settings

| Key | Default | Description |
|-----|---------|-------------|
| `tier_settings.show_tier_warnings` | `true` | Show tier-related warnings |

### Session Preferences

| Key | Default | Description |
|-----|---------|-------------|
| `session_preferences.session_timeout_minutes` | `60` | Session timeout |

---

## Sync with Backend

Synchronize your local CLI configuration with your profile settings:

```bash
# Sync from backend (pulls remote settings)
ivybloom config sync

# Force overwrite local with remote
ivybloom config sync --force

# Push local settings to backend
ivybloom config sync --push
```

---

## Export and Import

### Export Configuration

```bash
ivybloom config export config-backup.json
```

### Import Configuration

```bash
ivybloom config import config-backup.json
```

**Example exported file:**

```json
{
  "api_url": "https://www.ivybiosciences.com/api/cli",
  "timeout": 30,
  "format": "table",
  "debug": false,
  "profile_display": {
    "show_org_name": true,
    "show_tier_badge": true
  }
}
```

> Use export/import to share configuration across machines or back up before making changes.

---

## Configuration File Locations

| Path | Purpose |
|------|---------|
| `~/.config/ivybloom/default.json` | Config for the default profile; each profile is `<profile>.json` |
| `~/.config/ivybloom/cli_history.json` | Command history |
| `~/.config/ivybloom/diagnostics.json` | Last diagnostics report |
| `~/.config/ivybloom/ui_settings.json` | TUI settings |
| `~/.config/ivybloom/error.log` | Error log |
| `.ivybloom/project.json` | Project-local settings (in a linked project's root) |

Set `IVYBLOOM_CONFIG_DIR` to use a different directory.

**View file location:**
```bash
ivybloom config path
```

**Example config file:**

```json
{
  "api_url": "https://www.ivybiosciences.com/api/cli",
  "timeout": 30,
  "format": "table",
  "debug": false,
  "profile_display": {
    "show_org_name": true,
    "show_tier_badge": true
  },
  "tier_settings": {
    "show_tier_warnings": true
  },
  "session_preferences": {
    "session_timeout_minutes": 60
  }
}
```

---

## Environment Variables

Override configuration with environment variables:

| Variable | Config Key | Description |
|----------|------------|-------------|
| `IVYBLOOM_API_KEY` | - | API key for authentication |
| `IVYBLOOM_API_URL` | `api_url` | API endpoint URL |
| `IVYBLOOM_TOKEN` | - | Access token for authentication |
| `IVYBLOOM_DEBUG` | `debug` | Enable debug mode (`1` or `true`) |
| `IVYBLOOM_CONFIG_DIR` | - | Config directory (default `~/.config/ivybloom`) |
| `IVYBLOOM_SCRIPT_MODE` | - | Non-interactive output, no spinners (set to `1`) |
| `NO_COLOR` | - | Disable colors (set to `1`) |

**Example:**

```bash
# Use API key from environment
export IVYBLOOM_API_KEY="ivy_yourKeyId_yourSecret"
ivybloom jobs list

# One-time override
IVYBLOOM_DEBUG=true ivybloom jobs list
```

> **CI/CD Best Practice**

> Use environment variables for API keys in CI/CD pipelines rather than committing them to config files.

---

## Precedence Order

Configuration values are resolved in this order (highest to lowest):

1. Command-line flags (`--format json`)
2. Environment variables (`IVYBLOOM_API_URL`)
3. Project settings (`.ivybloom/project.json` in a linked project)
4. Profile config (`~/.config/ivybloom/<profile>.json`)
5. Default values

---

## Profiles

Use different profiles for different environments:

```bash
# Use a profile
ivybloom jobs list --profile staging
```

The profile comes from the `--profile` flag only; there is no profile environment variable.

---

## AI Models

### List Available Models

```bash
ivybloom config models list
ivybloom config models list --available
```

### Model Pricing

Model pricing is documented once, in [plans and tiers](/docs/plans-and-tiers#how-the-platform-meters-and-gates).

### Refresh Model List

```bash
ivybloom config models refresh
```

### Clear Model Cache

```bash
ivybloom config models clear-cache
```

---

## BYOK (Bring Your Own Key)

Register a provider key of your own. Model calls that run on it skip the platform markup; they are still metered in research credits, at the provider's cost.

### Check BYOK Status

```bash
ivybloom config byok status
```

### Add Your API Key

```bash
ivybloom config byok add openrouter sk-or-your-key
ivybloom config byok add openai sk-your-key
ivybloom config byok add anthropic sk-ant-your-key
```

### Remove BYOK Session

```bash
ivybloom config byok remove
```

---

## Themes

### List Available Themes

```bash
ivybloom config theme list
```

### Set Theme

```bash
ivybloom config theme set dark
ivybloom config theme set light
```

> `config theme set` currently saves the theme name into the `format` key, which changes your default output format. Until that is fixed, set the TUI theme with `/appearance`, and restore the output format with `ivybloom config set format table`.

### Preview Theme

```bash
ivybloom config theme preview dark
```

---

## Onboarding

### Check Onboarding Status

```bash
ivybloom config onboarding status
```

### Mark Onboarding Complete

```bash
ivybloom config onboarding complete
```

### Reset Onboarding

```bash
ivybloom config onboarding reset
```

---

## Read next

- [API Keys](/docs/cli/api-keys) - Set up authentication
- [Agent Mode](/docs/cli/agent-mode) - Output format configuration for CI/CD
- [Commands Reference](/docs/cli/commands) - Full command documentation
- [FAQ](/docs/cli/faq) - Common questions and answers