Complete installation guide for the ivybloom CLI with troubleshooting and advanced options.

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.

Difficulty

beginner

ivybloom CLI Installation Guide

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

Quick Install

macOS & Linux (Recommended)

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

Windows (PowerShell)

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

All Platforms (npm)

npm install -g @ivybiosciences/ivybloom-cli

Verify Installation

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:

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

Windows (PowerShell):

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

All Platforms (npm):

npm install -g @ivybiosciences/ivybloom-cli

Method 2: npm Package

Works on all platforms with Node.js:

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:

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

macOS (Apple Silicon):

curl -fsSL "https://releases.ivybiosciences.com/releases/${VERSION}/ivybloom_${VERSION}_darwin_arm64.tar.gz" | tar xz
sudo mv ivybloom /usr/local/bin/

macOS (Intel):

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):

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):

curl -fsSLO "https://releases.ivybiosciences.com/releases/${VERSION}/ivybloom_${VERSION}_linux_amd64.deb"
sudo dpkg -i "ivybloom_${VERSION}_linux_amd64.deb"

RHEL/Fedora (.rpm):

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

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

# Verify installation health
ivybloom health

Authenticate

# 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
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

ivybloom tools list

Run Your First Job

ivybloom run esmfold protein_sequence=MKLVFFAEDVGSNKGAIIGLMVGGVVIA

Enhanced Interactive Mode (Optional)

For enhanced interactive features like fuzzy search and multi-select, optionally install gum:

macOS:

brew install gum

Linux (Ubuntu/Debian):

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):

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

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 for the full JSON envelope schema and automation patterns.

GitLab CI

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

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:

# 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:

# 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"

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

SSL/Certificate Errors

# 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

# 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

ivybloom config path

Environment Variables

Override settings via environment:

# 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)

# 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

Check Installed Version

ivybloom version

Installing Specific Versions

Via npm

npm install -g @ivybiosciences/[email protected]

Via Direct Download

Replace ${VERSION} in the direct download URLs with the version you want, for example 0.8.55.

Uninstallation

npm

npm uninstall -g @ivybiosciences/ivybloom-cli

Manual Removal

# 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

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

Getting Help

Commands

# 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
Support: ivybiosciences.com/support
Email Support: [email protected]

Debug Information

When reporting issues, include:

# 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/[email protected]

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.

CLI Installation

Difficulty

On this page