ivybloom 0.8.0

Command-line interface for computational biology and drug discovery

🌿 IvyBloom CLI

Command-line interface for Ivy Biosciences' computational biology and drug discovery platform

Accelerate your computational biology research with powerful command-line tools for protein structure prediction, drug discovery, ADMET analysis, and workflow automation.

---

📑 Table of Contents

• Quick Start
• Key Features
• Terminal User Interface (TUI)
• Command Reference
• Research Use Cases
• Configuration
• Development
• Documentation
• Contributing
• Support

---

🚀 Quick Start

Installation

# Install from PyPI
pip install ivybloom

# Or with pipx for isolated environment
pipx install ivybloom

Authentication

# Browser-based login (recommended)
ivybloom auth login --browser

# Or use API key authentication
ivybloom auth login --api-key YOUR_API_KEY

Your First Job

# Predict protein structure with ESMFold
ivybloom run esmfold protein_sequence=MKLLVLGLVGFGVGFGVGFGVGFGVGFGVGFG

# Monitor progress in real-time
ivybloom jobs status JOB_ID --follow

# List recent jobs
ivybloom jobs list --limit 10

---

✨ Key Features

🧬 Computational Biology Tools

Tool	Description
ESMFold	State-of-the-art protein structure prediction
AlphaFold	Deep learning protein folding integration
REINVENT	Generative drug design and molecular optimization
ADMETLab3	Comprehensive ADMET property prediction
ProTox3	Toxicity assessment and safety profiling
AiZynthFinder	Retrosynthesis and synthesis planning
DeepSol	Protein solubility prediction
Fragment Libraries	Fragment-based drug discovery screening

🔗 Advanced Workflows

• Job Chaining: Link multiple analyses with automatic parameter passing
• Parallel Execution: Run multiple optimizations simultaneously
• YAML Workflows: Define complex multi-step pipelines declaratively
• Dry-Run Mode: Validate workflows before execution
• Progress Tracking: Real-time status updates and result reporting

🎨 Professional Interface

• Earth-Tone Design: Biology-inspired, eye-friendly color scheme
• Rich Formatting: Progress bars, tables, spinners, and status indicators
• Multiple Formats: Output as JSON, YAML, CSV, or formatted tables
• Interactive Prompts: Guided input with validation and suggestions
• Shell Completion: Tab completion for commands and arguments

🔐 Enterprise Authentication

• Browser OAuth: Seamless "click here to login" experience with PKCE
• Device Flow: Perfect for SSH sessions and headless environments
• API Keys: Traditional authentication for CI/CD and automation
• Secure Storage: System keyring with encrypted file fallback

---

🖥 Terminal User Interface (TUI)

Launch the full-featured terminal UI for an interactive experience:

ivybloom tui

TUI Features

• Three-Panel Layout: Jobs list, details view, and artifact preview
• Real-Time Updates: Live job status with adaptive refresh
• Protein Visualization: ASCII/braille protein structure rendering
• Molecule Viewer: SMILES depiction and molecular preview
• Command Palette: Fuzzy search for all commands (Ctrl+K)
• Artifact Browser: Preview JSON, CSV, PDB, and more inline
• Project Switcher: Quickly switch between projects

TUI Keybindings

Key	Action
Ctrl+K	Open command palette
j / k	Navigate jobs list
l	Follow selected job
a	View artifacts
o	Open primary artifact
?	Show help overlay
q	Quit TUI

---

📋 Command Reference

Core Commands

# Authentication
ivybloom auth login --browser      # Browser OAuth login
ivybloom auth status               # Check authentication status
ivybloom auth logout               # Clear credentials

# Jobs
ivybloom jobs list                 # List all jobs
ivybloom jobs status JOB_ID        # Get job details
ivybloom jobs status JOB_ID --follow  # Stream live updates
ivybloom jobs results JOB_ID       # Get job results
ivybloom jobs cancel JOB_ID        # Cancel a running job

# Tools
ivybloom tools list                # List available tools
ivybloom tools info TOOL_NAME      # Get tool details and parameters
ivybloom tools schema TOOL_NAME    # Get JSON schema for tool

# Running Jobs
ivybloom run TOOL_NAME param=value # Run a tool with parameters
ivybloom run esmfold --help        # Get help for specific tool

# Projects
ivybloom projects list             # List your projects
ivybloom projects info PROJECT_ID  # Get project details

# Workflows
ivybloom workflows run FILE.yaml   # Execute a workflow file
ivybloom workflows validate FILE   # Validate workflow syntax

# Account
ivybloom account info              # View account details
ivybloom account usage             # Check usage and limits

# Configuration
ivybloom config get KEY            # Get config value
ivybloom config set KEY VALUE      # Set config value
ivybloom config list               # List all settings
ivybloom config edit               # Interactive config editor

Output Formats

All listing commands support multiple output formats:

ivybloom jobs list --format json   # JSON output
ivybloom jobs list --format yaml   # YAML output
ivybloom jobs list --format csv    # CSV output
ivybloom jobs list --format table  # Rich table (default)

---

🔬 Research Use Cases

Protein Structure Prediction

# Single protein prediction
ivybloom run esmfold protein_sequence=MKFLILLFNILCLFPVLAADNHGVGPQGAS

# With project assignment
ivybloom run esmfold protein_sequence=MKFLILLFNILCLFPVLAADNHGVGPQGAS \
    --project-id my-project

Drug Discovery Pipeline

# drug_pipeline.yaml
name: protein_to_drug_pipeline
description: End-to-end drug discovery workflow

steps:
  - name: predict_structure
    tool: esmfold
    parameters:
      protein_sequence: ${input.sequence}

  - name: generate_candidates
    tool: reinvent
    depends_on: predict_structure
    parameters:
      target_structure: ${predict_structure.output.pdb_file}
      num_molecules: 100

  - name: filter_admet
    tool: admetlab3
    depends_on: generate_candidates
    parameters:
      molecules: ${generate_candidates.output.molecules}

# Run the pipeline
ivybloom workflows run drug_pipeline.yaml \
    --input sequence=MKLLVLGLVGFGVGFGVGFGVGFGVGFGVGFG \
    --project-id drug-discovery

High-Throughput Screening

# Batch processing with parallel execution
ivybloom batch run admetlab3 \
    --input-file compounds.csv \
    --parallel 10 \
    --project-id screening-2025

Fragment-Based Design

ivybloom workflows run fragment_discovery.yaml \
    --input target_protein=structure.pdb \
    --input fragment_library=fragments.sdf \
    --parallel

---

⚙️ Configuration

Configuration is stored in ~/.config/ivybloom/config.json.

Key Settings

# Set default project
ivybloom config set default_project_id my-project

# Enable debug mode
ivybloom config set debug true

# Configure API timeout
ivybloom config set timeout 60

# Set default output format
ivybloom config set default_format table

# View all settings
ivybloom config list

# View configuration schema
ivybloom config schema

Environment Variables

# API authentication
export IVYBLOOM_API_KEY=ivy_sk_...

# Alternative key name
export IVY_API_KEY=ivy_sk_...

# Disable keyring storage
export IVYBLOOM_DISABLE_KEYRING=1

# Enable debug output
export IVYBLOOM_DEBUG=1

---

🛠 Development

Local Installation

# Clone the repository
git clone https://github.com/ivybiosciences/ivybloom-cli.git
cd ivybloom-cli

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install in development mode
pip install -e ".[dev]"

# Verify installation
ivybloom --version

Running Tests

# Run all tests
pytest

# Run with coverage
pytest --cov=ivybloom_cli

# Run specific test file
pytest tests/test_run_parsing.py

# Run only unit tests
pytest -m unit

Code Quality

# Format code with Black
black ivybloom_cli tests

# Lint with Flake8
flake8 ivybloom_cli

# Type check with Mypy
mypy ivybloom_cli

---

📚 Documentation

Resource	Description
CLI Guide	Complete feature documentation
User Guide	Getting started and tutorials
Authentication	Auth setup and security
Commands Reference	Full command documentation
Workflow Examples	Real-world pipeline examples
TUI Design	Terminal UI architecture
API Reference	Backend API documentation

---

🤝 Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

# Quick contribution workflow
git checkout -b feature/your-feature
# Make changes...
pytest                    # Run tests
black ivybloom_cli tests  # Format code
git commit -m "feat: your feature description"
git push origin feature/your-feature
# Open a Pull Request

---

📄 License

This project is licensed under the MIT License - see LICENSE for details.

---

🆘 Support

• Documentation: docs.ivybiosciences.com/cli
• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Email: [e-mail]

---

🌿 Computational Biology & Drug Discovery at Your Fingertips
_{Built with ❤️ by Ivy Biosciences}