npm package: @ivybiosciences/ivybloom-cli
Description: CLI/TUI for computational biology and drug discovery on the .bloom* platform
Author: Ivy Biosciences
Latest version: 0.8.55

<p align="center">
  <img src="https://ivybiosciences.com/logo.svg" alt="IvyBloom" width="100" />
</p>

<h1 align="center">@ivybiosciences/ivybloom-cli</h1>

<p align="center">
  <strong>Terminal-native computational biology and drug discovery</strong><br/>
  <sub>Protein folding, molecular docking, ADMET prediction, and AI-guided research workflows</sub>
</p>

<p align="center">
  <a href="https://ivybiosciences.com/docs">Docs</a> &bull;
  <a href="https://ivybiosciences.com/docs/api">API</a> &bull;
  <a href="https://github.com/ivybiosciences/ivybloom-cli">GitHub</a> &bull;
  <a href="https://ivybiosciences.com/docs/cli/tools">Tools Reference</a>
</p>

---

## Install

```bash
npm install -g @ivybiosciences/ivybloom-cli    # npm
npx @ivybiosciences/ivybloom-cli [command]     # run without install
brew install ivybiosciences/ivybloom/ivybloom  # macOS/Linux
```

**Verify:** `ivybloom --version`

## Quick Start

```bash
ivybloom auth login     # authenticate (opens browser)
ivybloom tui            # launch interactive TUI
ivybloom tools list     # list available tools
```

## Tools

| Tool | Description | Input |
|------|-------------|-------|
| **ESMFold** | Fast protein structure prediction (single sequence) | FASTA/sequence |
| **AlphaFold** | High-accuracy structure prediction (MSA-based) | FASTA |
| **DiffDock** | Molecular docking with diffusion models | PDB + SMILES/SDF |
| **REINVENT** | De novo drug molecule generation | SMILES scaffold |
| **ADMET** | Absorption, distribution, metabolism, excretion, toxicity | SMILES |
| **MolMIM** | Molecular property prediction | SMILES |
| **ProteinMPNN** | Inverse folding / sequence design | PDB |
| **RFdiffusion** | Protein structure generation | Constraints |

Run tools via CLI or TUI with real-time progress streaming.

## CLI Reference

```bash
# Authentication
ivybloom auth login [--browser|--token]
ivybloom auth logout
ivybloom auth status

# Tools
ivybloom tools list [--format json|table]
ivybloom tools info <tool>
ivybloom tools run <tool> [--input FILE] [--param KEY=VAL...]

# Jobs
ivybloom jobs list [--status pending|running|completed|failed] [--limit N]
ivybloom jobs status <job-id>
ivybloom jobs logs <job-id> [--follow]
ivybloom jobs cancel <job-id>
ivybloom jobs download <job-id> [--output DIR]

# Projects
ivybloom projects list
ivybloom projects create <name>
ivybloom projects link <project-id>
ivybloom projects unlink

# Sessions (agent harness)
ivybloom sessions list
ivybloom sessions resume <session-id>
ivybloom checkpoints list <session-id>
ivybloom checkpoints rollback <session-id> <checkpoint-id>

# Utilities
ivybloom config [get|set|list]
ivybloom version [--verbose]
ivybloom doctor                    # diagnose environment issues
```

## TUI

Launch: `ivybloom tui`

### Keyboard Shortcuts

| Key | Action |
|-----|--------|
| `@` | Attach file (FASTA, PDB, SDF, SMILES) |
| `!` | Browse & run tools |
| `/` | Command palette |
| `y`/`n` | Approve/deny tool execution |
| `Tab` | Toggle context panel |
| `Ctrl+J` | Submit message |
| `Ctrl+C` | Cancel/exit |
| `?` | Help |

### Features

- **AI Chat**: Conversational interface for research guidance and tool selection
- **Tool Approval**: Review parameters before execution (Cursor-style flow)
- **Live Progress**: Real-time job status with phase indicators
- **File Attachments**: Drag-drop or `@`-mention to attach sequences/structures
- **Session Persistence**: Resume conversations with full context

## Automation & CI/CD

Enable machine-readable JSON output for scripting:

```bash
ivybloom jobs list --machine                    # JSON envelope output
IVYBLOOM_MACHINE_MODE=1 ivybloom tools run ...  # via env var
ivybloom jobs status <id> --machine --trace-id "run-001"
```

**Output format:**
```json
{"success": true, "data": {...}, "meta": {"trace_id": "...", "duration_ms": 42}}
```

## Environment Variables

| Variable | Description |
|----------|-------------|
| `IVYBLOOM_API_KEY` | API key (for CI/CD, skips interactive login) |
| `IVYBLOOM_API_URL` | Override API endpoint |
| `IVYBLOOM_MACHINE_MODE=1` | JSON output, no colors/prompts |
| `IVYBLOOM_DEBUG=1` | Verbose debug output |
| `IVYBLOOM_DISABLE_KEYRING=1` | Store tokens in file instead of OS keychain |
| `DO_NOT_TRACK=1` | Disable install telemetry |
| `IVYBLOOM_NO_TELEMETRY=1` | Disable install telemetry (alias) |

## Telemetry

The installer sends anonymous telemetry to help us understand usage patterns. Data collected: platform, architecture, version, CI detection, success/failure. No PII is collected. Disable with `DO_NOT_TRACK=1` or `IVYBLOOM_NO_TELEMETRY=1`.

## Platform Support

| OS | Architectures |
|----|---------------|
| macOS | x64, arm64 (Apple Silicon) |
| Linux | x64, arm64 |
| Windows | x64 |

## Troubleshooting

| Issue | Solution |
|-------|----------|
| `401 Unauthorized` | Run `ivybloom auth login --browser` |
| Token errors | Set `IVYBLOOM_DISABLE_KEYRING=1` |
| Connection timeout | Check `IVYBLOOM_API_URL` or network |
| TUI rendering issues | Ensure terminal supports 256 colors |

Run `ivybloom doctor` for automated diagnostics.

---

<p align="center">
  <a href="https://ivybiosciences.com">ivybiosciences.com</a> &bull;
  <a href="mailto:support@ivybiosciences.com">support@ivybiosciences.com</a>
</p>