---
title: CLI Installation
description: >-
  Complete installation guide for the ivybloom CLI with troubleshooting and
  advanced options.
tags:
  - installation
  - setup
  - macos
  - linux
  - windows
---

This page gets the ivybloom CLI installed on macOS, Linux, or Windows so you can run drug discovery jobs from your terminal, scripts, and CI/CD. Reach for it as your first step — before authenticating and submitting jobs — or when you need manual installs, version pinning, or CI/CD setup. Once installed, the CLI shares one backend and job history with the web platform, so your terminal work stays in sync. For the full CLI surface, see the [CLI overview](/docs/cli).

  beginner

## ivybloom CLI Installation Guide

Complete installation guide with troubleshooting, advanced options, and setup details.

## Quick Install

### macOS & Linux (Recommended)

```bash
curl -fsSL https://www.ivybiosciences.com/install | bash
```

### Windows (PowerShell)

```powershell
irm https://www.ivybiosciences.com/install.ps1 | iex
```

### All Platforms (npm)

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

---

## Verify Installation

```bash
ivybloom version
```

---

## System Requirements

### Minimum Requirements

| OS | Version | Notes |
|---|---|---|
| macOS | 10.13+ | Intel or Apple Silicon (M1/M2/M3) |
| Linux | Kernel 5.0+ | Ubuntu 18.04+, CentOS 7+, Fedora 28+, Arch, Alpine |
| Windows | 10+ | PowerShell 5.0+ required |

### Disk Space

- **~50 MB** for the CLI binary
- **Internet connection** required for initial download

### Optional Dependencies

- **Gum** - Enhanced interactive features (fuzzy search, multi-select)
- **jq** - JSON processing for scripting
- **Git** - Version control (optional)

---

## Installation Methods

### Method 1: Install Script (Recommended)

The easiest way to install the CLI.

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

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

**All Platforms (npm):**
```bash
npm install -g @ivybiosciences/ivybloom-cli
```

### Method 2: npm Package

Works on all platforms with Node.js:

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

### Method 3: Direct Binary Download

Pre-built binaries are published to `releases.ivybiosciences.com`. Read the current version from `latest.txt`, then download the archive for your platform:

```bash
VERSION=$(curl -fsSL https://releases.ivybiosciences.com/releases/latest.txt | tr -d 'v[:space:]')
```

**macOS (Apple Silicon):**
```bash
curl -fsSL "https://releases.ivybiosciences.com/releases/${VERSION}/ivybloom_${VERSION}_darwin_arm64.tar.gz" | tar xz
sudo mv ivybloom /usr/local/bin/
```

**macOS (Intel):**
```bash
curl -fsSL "https://releases.ivybiosciences.com/releases/${VERSION}/ivybloom_${VERSION}_darwin_amd64.tar.gz" | tar xz
sudo mv ivybloom /usr/local/bin/
```

**Linux (amd64 or arm64):**
```bash
curl -fsSL "https://releases.ivybiosciences.com/releases/${VERSION}/ivybloom_${VERSION}_linux_amd64.tar.gz" | tar xz
sudo mv ivybloom /usr/local/bin/
```

**Windows:** download `ivybloom_<version>_windows_amd64.zip` from the same folder, unzip it, and add the folder holding `ivybloom.exe` to your `PATH`.

### Method 4: Linux Package Managers

The same release folder carries `.deb` and `.rpm` packages:

**Debian/Ubuntu (.deb):**
```bash
curl -fsSLO "https://releases.ivybiosciences.com/releases/${VERSION}/ivybloom_${VERSION}_linux_amd64.deb"
sudo dpkg -i "ivybloom_${VERSION}_linux_amd64.deb"
```

**RHEL/Fedora (.rpm):**
```bash
curl -fsSLO "https://releases.ivybiosciences.com/releases/${VERSION}/ivybloom_${VERSION}_linux_amd64.rpm"
sudo rpm -i "ivybloom_${VERSION}_linux_amd64.rpm"
```

---

## After Installation

### Guided First-Time Setup

```bash
# Launch the app; the first run walks you through onboarding and sign-in
ivybloom

# Verify installation health
ivybloom health
```

### Authenticate

```bash
# Browser-based authentication (recommended)
ivybloom auth login --browser

# Or use API key
ivybloom auth login --api-key ivy_yourKeyId_yourSecret

# Verify authentication
ivybloom auth status
```

### Shell Completion

```bash
# Bash
ivybloom completion bash > ~/.bash_completion.d/ivybloom

# Zsh
ivybloom completion zsh > "${fpath[1]}/_ivybloom"

# Fish
ivybloom completion fish > ~/.config/fish/completions/ivybloom.fish

# PowerShell
ivybloom completion powershell > ivybloom.ps1
```

### Explore Available Tools

```bash
ivybloom tools list
```

### Run Your First Job

```bash
ivybloom run esmfold protein_sequence=MKLVFFAEDVGSNKGAIIGLMVGGVVIA
```

---

## Enhanced Interactive Mode (Optional)

For enhanced interactive features like fuzzy search and multi-select, optionally install [gum](https://github.com/charmbracelet/gum):

**macOS:**
```bash
brew install gum
```

**Linux (Ubuntu/Debian):**
```bash
sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://repo.charm.sh/apt/gpg.key | sudo gpg --dearmor -o /etc/apt/keyrings/charm.gpg
echo "deb [signed-by=/etc/apt/keyrings/charm.gpg] https://repo.charm.sh/apt/ * *" | \
  sudo tee /etc/apt/sources.list.d/charm.list
sudo apt update && sudo apt install gum
```

**Windows (Scoop):**
```powershell
scoop install gum
```

### What Gum Adds

- **Fuzzy search** - Find jobs/projects by typing
- **Multi-select** - Select multiple items for batch operations
- **Interactive file picker** - Browse and select files visually
- **Enhanced confirmations** - Beautiful yes/no prompts

ivybloom works perfectly without gum - it gracefully falls back to standard input methods.

---

## CI/CD Integration

### GitHub Actions

```yaml
name: Run Analysis

on: push

jobs:
  analyze:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install ivybloom CLI
        run: |
          curl -fsSL https://www.ivybiosciences.com/install | bash

      - name: Submit Job
        env:
          IVYBLOOM_API_KEY: ${{ secrets.IVYBLOOM_API_KEY }}
        run: |
          # Agent mode: structured JSON envelope for parsing
          JOB_ID=$(ivybloom run esmfold protein_sequence=MKLVFF --agent --wait | jq -r '.data.job_id')

          # Script mode: non-interactive, no spinners
          ivybloom jobs list --script --format json
```

> See [Agent Mode](/docs/cli/agent-mode) for the full JSON envelope schema and automation patterns.

### GitLab CI

```yaml
analyze:
  image: ubuntu:latest
  script:
    - apt-get update && apt-get install -y curl
    - curl -fsSL https://www.ivybiosciences.com/install | bash
    - ivybloom run esmfold protein_sequence=MKLVFFAEDV...
  variables:
    IVYBLOOM_API_KEY: $IVYBLOOM_API_KEY
```

### Docker

```dockerfile
FROM ubuntu:22.04
RUN apt-get update && apt-get install -y curl && \
    curl -fsSL https://www.ivybiosciences.com/install | bash
ENV PATH="$PATH:/usr/local/bin"
```

---

## Troubleshooting

### Command Not Found

The binary isn't in your PATH:

```bash
# Find where it was installed
which ivybloom

# Add to PATH (macOS/Linux)
export PATH=$PATH:/usr/local/bin

# Make permanent - add to ~/.zshrc or ~/.bashrc
echo 'export PATH=$PATH:/usr/local/bin' >> ~/.zshrc
source ~/.zshrc
```

### Permission Denied

Try user-level installation:

```bash
# npm (use a Node version manager so -g installs to your home directory)
npm install -g @ivybiosciences/ivybloom-cli

# Or download 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
```

### Script Execution Policy (Windows)

**Error: "execution of scripts is disabled on this system"**

```powershell
# Allow script execution temporarily
Set-ExecutionPolicy -ExecutionPolicy Bypass -Scope Process

```

### SSL/Certificate Errors

```bash
# Update CA certificates
sudo apt-get update && sudo apt-get install ca-certificates

# Try installation again
curl -fsSL https://www.ivybiosciences.com/install | bash
```

### Authentication Errors

```bash
# Check status
ivybloom auth status

# Re-authenticate
ivybloom auth logout
ivybloom auth login --browser

# Verify configuration
ivybloom config validate --all
```

---

## Configuration

### Configuration File Location

Settings are stored securely:

| Path | Purpose |
|------|---------|
| `~/.config/ivybloom/default.json` | Config for the default profile; each profile is `<profile>.json` |
| `~/.config/ivybloom/ui_settings.json` | TUI settings |
| `~/.config/ivybloom/diagnostics.json` | Last diagnostics report |
| `.ivybloom/` | Project-local config (in project root) |

Set `IVYBLOOM_CONFIG_DIR` to move the config directory.

### View Configuration Path

```bash
ivybloom config path
```

### Environment Variables

Override settings via environment:

```bash
# API Key (for automation)
export IVYBLOOM_API_KEY=ivy_yourKeyId_yourSecret

# Custom API URL (default: https://www.ivybiosciences.com/api/cli)
export IVYBLOOM_API_URL=https://your-domain.com/api/cli

# Debug mode
export IVYBLOOM_DEBUG=1
```

---

## Updating

### Reinstall via Script (Recommended)

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

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

### npm

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

### Check Installed Version

```bash
ivybloom version
```

---

## Installing Specific Versions

### Via npm

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

### Via Direct Download

Replace `${VERSION}` in the [direct download](#method-3-direct-binary-download) URLs with the version you want, for example `0.8.55`.

---

## Uninstallation

### npm

```bash
npm uninstall -g @ivybiosciences/ivybloom-cli
```

### Manual Removal

```bash
# macOS/Linux
rm $(which ivybloom)

# Windows (PowerShell)
Remove-Item "$env:LOCALAPPDATA\IvyBloom" -Recurse -Force

# Remove configuration (optional)
rm -rf ~/.config/ivybloom
```

---

## Security Considerations

### Installation Security

- **HTTPS Only**: Installation scripts are served over HTTPS

### API Key Security

- **Never commit keys** to version control
- **Use `.gitignore`** to exclude credentials
- **Rotate regularly**: Generate new keys, revoke old ones
- **Minimal Scopes**: Only grant permissions needed
- **Environment Variables**: Store in `IVYBLOOM_API_KEY`, not in code

```bash
# Secure storage (example with environment variables)
export IVYBLOOM_API_KEY="ivy_yourKeyId_yourSecret"
ivybloom auth status
```

---

## Getting Help

### Commands

```bash
# General help
ivybloom --help

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

# Version information
ivybloom version
```

### Resources

- **CLI Documentation**: [ivybiosciences.com/docs/cli](/docs/cli)
- **Support**: [ivybiosciences.com/support](https://www.ivybiosciences.com/support)
- **Email Support**: admin@ivybiosciences.com

### Debug Information

When reporting issues, include:

```bash
# System and version information
ivybloom version
uname -a

# Debug output
IVYBLOOM_DEBUG=1 ivybloom auth status
```

---

## FAQ

**Q: Do I need Go installed?**
A: No. Pre-built binaries are available for all platforms.

**Q: Will this overwrite existing installations?**
A: Package managers handle this automatically. Manual installs overwrite previous versions.

**Q: Can I install multiple versions?**
A: Install a specific npm version: `npm install -g @ivybiosciences/ivybloom-cli@0.8.55`

**Q: Is there a GUI version?**
A: The CLI includes an interactive TUI dashboard — run `ivybloom` with no arguments.

**Q: Can I build from source?**
A: Not from a public repository today: the source repository is not public.

---

## Read next

After installation:

1. **Authenticate**: `ivybloom auth login --browser`
2. **Explore Tools**: `ivybloom tools list`
3. **Run Your First Analysis**: `ivybloom run esmfold protein_sequence=MKLVFFAEDV...`
4. **Check Results**: `ivybloom jobs list`
5. **Try the Dashboard**: `ivybloom`
6. **Read the Docs**: [CLI Documentation](/docs/cli)