---
title: CLI FAQ
description: Four ways to sign in, where settings and the error log live under ~/.config/ivybloom/, what one failed job does to a batch, and how to resume a session.
tags:
  - faq
  - troubleshooting
  - glossary
  - help
---

This FAQ answers common questions about installing, authenticating, and running the ivybloom CLI, plus a glossary of key terms. Reach for it when you hit a snag — a command that won't run, an auth error, or a batch that partially failed — and want a quick answer before digging into the full guides. Because the CLI shares one backend and job history with the web platform, many answers here apply whether you work from the terminal or the web app. For the complete command set, see the [CLI overview](/docs/cli).

  beginner

## CLI FAQ

Frequently asked questions about the ivybloom CLI.

---

## Installation

### Details

Run the installation script again:

```bash
# macOS & Linux
curl -fsSL https://www.ivybiosciences.com/install | bash

# Windows (PowerShell)
irm https://www.ivybiosciences.com/install.ps1 | iex

# npm
npm update -g @ivybiosciences/ivybloom-cli
```

### Details

Yes. Pin a version with npm:

```bash
npm install -g @ivybiosciences/ivybloom-cli@0.8.55
```

Or download that version's archive directly; see [Direct Binary Download](/docs/cli/install#method-3-direct-binary-download).

### Details

Yes! The CLI includes two interactive modes:

```bash
# Terminal dashboard with job monitoring
ivybloom

# Interactive shell session
ivybloom shell
```

For a full graphical interface, use the web application at [ivybiosciences.com](https://www.ivybiosciences.com).

### Details

- **macOS**: 10.13+ (Intel or Apple Silicon)
- **Linux**: Kernel 5.0+ (Ubuntu 18.04+, CentOS 7+, Fedora 28+)
- **Windows**: 10+ with PowerShell 5.0+
- **Disk Space**: ~50 MB for the CLI binary

---

## Authentication

### Details

The CLI supports four methods:

```bash
# 1. Browser OAuth (recommended for interactive use)
ivybloom auth login --browser

# 2. API Key (for automation)
ivybloom auth login --api-key ivy_yourKeyId_yourSecret

# 3. Device Flow (for SSH/headless)
ivybloom auth login --device

# 4. CLI Linking (auto-generates API key)
ivybloom auth link
```

### Details

Yes! Set the `IVYBLOOM_API_KEY` environment variable:

```bash
export IVYBLOOM_API_KEY="ivy_yourKeyId_yourSecret"
ivybloom run esmfold protein_sequence=MKLVFFAEDV...
```

See the [API Keys documentation](/docs/cli/api-keys) for detailed CI/CD examples.

### Details

Use device flow or API key authentication:

```bash
# Device flow (follow the on-screen link)
ivybloom auth login --device

# Or use API key
export IVYBLOOM_API_KEY="ivy_yourKeyId_yourSecret"
```

### Details

```bash
# Logout
ivybloom auth logout

# Login with a different account
ivybloom auth login --browser
```

---

## Jobs & Tools

### Details

Use the `run` command with `key=value` parameters:

```bash
ivybloom run esmfold protein_sequence=MKLVFFAEDVGSNKGAIIGLMVGGVVIA
ivybloom run admet smiles='CCO'
ivybloom run diffdock receptor=protein.pdb ligand=molecule.sdf
```

Add `--follow` to watch progress in real-time.

### Details

List all available tools with:

```bash
ivybloom tools list
```

Major categories include:
- **Protein Analysis**: ESMFold, BLAST, DeepSol, GraphSol
- **Molecular Docking**: DiffDock
- **Drug Design**: REINVENT4
- **ADMET**: ADMETLab3, ProTox3
- **Synthesis**: AiZynthFinder

### Details

```bash
# Check status
ivybloom jobs status JOB_ID

# Follow in real-time
ivybloom jobs follow JOB_ID

# Watch all running jobs
ivybloom jobs watch

# List all jobs
ivybloom jobs list --status running
```

### Details

```bash
ivybloom jobs download JOB_ID
ivybloom jobs download JOB_ID --output ./results
ivybloom jobs download JOB_ID --analyze  # With AI analysis
```

---

## Configuration

### Details

Configuration is stored in `~/.config/ivybloom/<profile>.json` (`default.json` for the default profile). View the path with:

```bash
ivybloom config path
```

### Details

Errors are logged to `~/.config/ivybloom/error.log`. Enable debug output:

```bash
IVYBLOOM_DEBUG=1 ivybloom jobs list
```

### Details

```bash
ivybloom config set api_url https://your-domain.com/api/cli
```

Or via environment variable:

```bash
export IVYBLOOM_API_URL="https://your-domain.com/api/cli"
```

### Details

```bash
ivybloom config reset
```

This resets to default values without affecting your credentials.

---

## AI Models & BYOK

### Details

A call costs credits in proportion to what the model provider charges for it. [Plans and tiers](/docs/plans-and-tiers#how-the-platform-meters-and-gates) states the billing rule.

View models with:
```bash
ivybloom config models list
```

### Details

BYOK (Bring Your Own Key) lets you use your own API keys for AI providers:

```bash
# Add your OpenRouter key
ivybloom config byok add openrouter sk-or-your-key

# Check status
ivybloom config byok status
```

Model calls that run on your BYOK key skip the platform markup. They are still metered in research credits, at the provider's cost. A key does not unlock model families outside your plan.

---

## Troubleshooting

### Details

The binary might not be in your PATH. Add Go's bin directory:

```bash
# Find installation location
which ivybloom

# Add to PATH (bash)
echo 'export PATH=$PATH:$(go env GOPATH)/bin' >> ~/.bashrc
source ~/.bashrc

# Add to PATH (zsh)
echo 'export PATH=$PATH:$(go env GOPATH)/bin' >> ~/.zshrc
source ~/.zshrc
```

### Details

Try user-level installation:

```bash
# npm (installs to user directory)
npm install -g @ivybiosciences/ivybloom-cli

# Or download the binary to your home directory
VERSION=$(curl -fsSL https://releases.ivybiosciences.com/releases/latest.txt | tr -d 'v[:space:]')
curl -fsSL "https://releases.ivybiosciences.com/releases/${VERSION}/ivybloom_${VERSION}_linux_amd64.tar.gz" | tar xz
mkdir -p ~/bin && mv ivybloom ~/bin/
export PATH=$PATH:~/bin
```

### Details

1. Check your credentials:
   ```bash
   ivybloom auth status
   ```

2. Re-authenticate:
   ```bash
   ivybloom auth logout
   ivybloom auth login --browser
   ```

3. Validate configuration:
   ```bash
   ivybloom config validate --all
   ```

### Details

1. Check job details:
   ```bash
   ivybloom jobs status JOB_ID
   ```

2. Follow with logs:
   ```bash
   ivybloom jobs follow JOB_ID --logs
   ```

3. Try with debug mode:
   ```bash
   IVYBLOOM_DEBUG=1 ivybloom run esmfold protein_sequence=...
   ```

### Details

```bash
# Quick health check
ivybloom health

# Full diagnostics (checks API, auth, rate limits, circuit breaker)
ivybloom health --full

# Detailed diagnostics report
ivybloom diagnostics
```

The health check returns exit code `0` (healthy) or `1` (unhealthy) for use in scripts.

### Details

```bash
ivybloom config schema
```

This shows all available configuration keys, types, and defaults as a JSON schema.

---

## Batch Processing

### Details

Create a YAML file defining your batch:

```yaml
name: "ADMET Screen"
tool: admet
jobs:
  - name: "aspirin"
    parameters: { smiles: "CC(=O)Oc1ccccc1C(=O)O" }
  - name: "ibuprofen"
    parameters: { smiles: "CC(C)Cc1ccc(cc1)C(C)C(=O)O" }
options:
  parallel: 4
```

Then submit:
```bash
ivybloom batch submit screen.yaml
```

See [Batch Processing](/docs/cli/batch) for the full YAML schema and options.

### Details

By default, the batch continues running remaining jobs. Configure behavior with:
- `stop_on_error: true` — Stop the batch on first failure
- `retry_failed: 2` — Automatically retry failed jobs (up to N times)

You can also pause and resume batches:
```bash
ivybloom batch pause BATCH_ID
ivybloom batch resume BATCH_ID            # re-runs the failed jobs
ivybloom batch resume BATCH_ID --force-all  # re-runs every job
```

### Details

```bash
# Aggregate all results
ivybloom batch collect BATCH_ID --output results.json

# Export as CSV
ivybloom batch collect BATCH_ID --format csv

# Only completed jobs
ivybloom batch collect BATCH_ID --completed-only
```

---

## MCP & Agent Integration

### Details

MCP (Model Context Protocol) is a standard for connecting AI agents to external tools. The ivybloom CLI exposes the platform tool catalog via MCP.

Start the server:
```bash
ivybloom mcp serve
```

Then configure your MCP client (Claude Desktop, Claude Code, etc.) to connect. See [MCP Integration](/docs/cli/mcp) for setup examples.

### Details

```bash
# Start on stdio (for agent integration)
ivybloom mcp serve

# View server capabilities
ivybloom mcp info

# List all exposed tools
ivybloom mcp tools
```

### Details

- **CLI commands** are run directly in your terminal (e.g., `ivybloom jobs list`)
- **MCP tools** are exposed via `ivybloom mcp serve` for AI agents to call programmatically

Most CLI commands have MCP equivalents. Some operations (like context management) are MCP-only. Pages mark MCP-only operations with a note.

---

## Sessions & Conversations

### Details

Sessions are automatically saved. Resume them with:

```bash
# Resume the most recent session
ivybloom -r last

# Resume a specific session
ivybloom --resume SESSION_ID

# List all sessions
ivybloom sessions list
```

See [Sessions & Checkpoints](/docs/cli/sessions) for full session management.

### Details

Checkpoints are snapshots of your session state. Use them to roll back after a bad tool execution:

```bash
# Create a checkpoint
ivybloom checkpoints create SESSION_ID

# List checkpoints
ivybloom checkpoints list SESSION_ID

# Roll back to a checkpoint
ivybloom checkpoints rollback SESSION_ID CHECKPOINT_ID
```

---

## Compounds & Science

### Details

```bash
# Substructure search (find all with benzene ring)
ivybloom compounds search COLL_ID --type substructure --smarts "c1ccccc1"

# Similarity search (Tanimoto, threshold 0-1)
ivybloom compounds search COLL_ID --type similarity --smiles "CC(=O)Oc1ccccc1C(=O)O" --threshold 0.8
```

See [Compounds](/docs/cli/compounds) for importing, exporting, and managing collections.

### Details

```bash
# Full preparation (add hydrogens, optimize, detect binding sites)
ivybloom proteinprep run structure.pdb --ph 7.4 --detect-sites

# Quality check only
ivybloom proteinprep quality structure.pdb

# Binding site detection
ivybloom proteinprep sites structure.pdb --top 5
```

See [Protein Preparation](/docs/cli/proteinprep) for the full pipeline.

---

## Organizations

### Details

```bash
ivybloom org invite ORG_ID --email colleague@example.com --role member
```

Available roles: owner, admin, member, viewer. See [Organizations](/docs/cli/organizations) for role permissions.

### Details

| Role | Description |
|------|-------------|
| **Owner** | Full control, billing, member management |
| **Admin** | Manage members and projects, no billing |
| **Member** | Submit jobs, view results, use tools |
| **Viewer** | Read-only access to projects and results |

Manage roles with:
```bash
ivybloom org set-role ORG_ID USER_ID --role admin
```

---

## Getting Help

### In the CLI

```bash
# General help
ivybloom --help

# Command-specific help
ivybloom auth --help
ivybloom jobs --help
ivybloom run --help
```

### Resources

- [Installation Guide](/docs/cli/install)
- [Commands Reference](/docs/cli/commands)
- [Support](https://www.ivybiosciences.com/support)
- [Email Support](mailto:admin@ivybiosciences.com)

---

## Glossary

| Term | Definition |
|------|-----------|
| **ADMET** | Absorption, Distribution, Metabolism, Excretion, Toxicity |
| **Batch** | Collection of jobs submitted and tracked as a unit |
| **BYOK** | Bring Your Own Key — use personal AI provider API keys |
| **Campaign** | Organizational unit grouping related chats and jobs |
| **Checkpoint** | Snapshot of session state for rollback/time-travel |
| **Collection** | Set of compounds stored together for analysis |
| **Docking** | Predicting how a small molecule binds to a protein |
| **ESMFold** | Meta's protein structure prediction model |
| **MCP** | Model Context Protocol — AI agent ↔ tool standard |
| **pLDDT** | Predicted Local Distance Difference Test (0-100, higher=better) |
| **SAFE** | Sequential Attachment-based Fragment Embedding |
| **SMILES** | Simplified Molecular Input Line Entry System |
| **TUI** | Terminal User Interface — the interactive dashboard |
| **Model family** | A model provider, such as Anthropic or OpenAI; your plan sets which ones you can use |

---

## Didn't find your answer?

[Contact Support](https://ivybiosciences.com/support) for personalized help with your CLI questions.

## FAQ

### How do I update the CLI to the latest version?

  Run the install script again or use your package manager to update.

### Can I use the CLI in CI/CD pipelines?

  Yes! Set the IVYBLOOM_API_KEY environment variable.

### Where are CLI logs stored?

  Errors are logged to ~/.config/ivybloom/error.log

### How do I submit multiple jobs at once?

  Use batch processing with a YAML file defining your job collection.

### What is MCP and how do I use it with AI agents?

  MCP (Model Context Protocol) exposes the platform tool catalog to AI agents via ivybloom mcp serve.

### How do I save and resume a chat session?

  Sessions auto-persist. Resume with ivybloom -r last or ivybloom --resume SESSION_ID.

### How do I search for compounds by structure?

  Use ivybloom compounds search with the substructure, similarity, text, or property search type.

### How do I invite team members?

  Use ivybloom org invite with the member's email address.