--- title: ivybloom CLI Commands — Complete Reference description: Reference for every ivybloom CLI command and its MCP equivalent, organized by category with flags and parameter formats. tags: - commands - reference - cli - api --- This reference lists every ivybloom CLI command — CLI subcommands plus their MCP tools — organized by category so you can build reproducible, scriptable pipelines. Reach for it when you need exact flags, parameter formats, or the MCP equivalents for a command while wiring up batch jobs or CI/CD. Because the CLI shares one backend and job history with the web platform, any command here operates on the same data as your web work. For a guided starting point, see the [CLI overview](/docs/cli). intermediate ## Commands Reference Complete reference for all ivybloom CLI commands organized by category. CLI subcommands plus MCP tools. > Commands marked with **MCP** are available via `ivybloom mcp serve` for AI agent integration and do not have dedicated CLI subcommands. See [MCP Integration](/docs/cli/mcp) for the full tool catalog. --- ## Authentication Manage authentication and account access. See [API Keys & Authentication](/docs/cli/api-keys) for detailed documentation. ### Details Authenticate with your Ivy Biosciences account using one of four methods. ```bash # Browser OAuth (recommended) ivybloom auth login --browser # API key authentication ivybloom auth login --api-key ivy_yourKeyId_yourSecret # Device flow (for headless/SSH environments) ivybloom auth login --device # CLI linking (auto-generates API key) ivybloom auth link ``` **Options:** - `--browser` — Open browser for OAuth authentication - `--api-key ` — Authenticate with an API key - `--device` — Use device flow for headless environments - `--force` — Force re-authentication (invalidates existing token) - `--no-verify` — Skip token verification after login - `--frontend-url ` — Custom frontend URL (with `--link`) ### Details Check your current authentication status. ```bash ivybloom auth status ivybloom auth status --check-connectivity ivybloom auth status --show-permissions ``` **Options:** - `--check-connectivity` — Verify API reachability - `--show-permissions` — Show permission scopes ### Details Display details about the currently authenticated user. ```bash ivybloom auth whoami ``` Shows: User ID, email, organization, and subscription plan. ### Details Remove all stored authentication data. ```bash ivybloom auth logout ivybloom auth logout --confirm # Skip confirmation ``` **Options:** - `--confirm` — Skip confirmation prompt ### Details Connect this CLI installation to your .bloom* account. ```bash ivybloom auth link ivybloom auth link --frontend-url https://custom.example.com ``` **Options:** - `--no-wait` — Generate link only, don't wait for completion - `--frontend-url ` — Override frontend URL ### Details Manage linked CLI devices. ```bash ivybloom auth devices list ivybloom auth devices list --format json ivybloom auth devices revoke DEVICE_ID ``` --- ## Job Submission Submit computational jobs using the `run` command. See [Job Management](/docs/cli/jobs) for monitoring and results. ### Details Submit a job to run a computational tool. ```bash ivybloom run esmfold protein_sequence=MKFLILLFNILCLFPVLAADNHGVGPQGAS ivybloom run diffdock receptor=protein.pdb ligand=molecule.sdf ivybloom run admet smiles='CCO' ``` **Options:** - `--project-id ` — Project to assign the job to - `--name ` — Human-readable name for the job - `--dry-run` — Validate parameters without submitting - `--dry-run-mode ` — Validation level: `syntax`, `quick`, or `full` - `--follow` — Follow job progress after submission - `--interactive` — Use interactive prompts for parameters - `--wait` — Block until job completion - `--timeout ` — Maximum wait time (default: `1h`) - `--poll-interval ` — Status polling interval (default: `5s`) - `--preflight` — Run health check before submission **Parameter Format:** Parameters use `key=value` format: ```bash ivybloom run esmfold protein_sequence=MKTAYIAKQRQISFVK num_recycles=3 ``` ### Details Predict protein structure from sequence using ESMFold. ```bash ivybloom run esmfold protein_sequence=MKLVFFAEDVGSNKGAIIGLMVGGVVIA ivybloom run esmfold protein_sequence=MKLVFFAEDV... --follow ``` **Parameters:** - `protein_sequence` — Amino acid sequence (required) - `num_recycles` — Number of recycle iterations ### Details Run molecular docking simulation with DiffDock. ```bash ivybloom run diffdock receptor=protein.pdb ligand=molecule.sdf ``` **Parameters:** - `receptor` — Protein structure file (PDB) - `ligand` — Ligand molecule file (SDF, MOL2) - `samples` — Number of docking poses to generate ### Details Predict ADMET properties for compounds. ```bash ivybloom run admet smiles='CCO' ivybloom run admet smiles='c1ccccc1' --follow ``` **Parameters:** - `smiles` — SMILES string (required) --- ## Job Management Monitor and manage computational jobs. See [Job Management](/docs/cli/jobs) for full documentation. ### Details List all jobs in your account. ```bash ivybloom jobs list ivybloom jobs list --status running ivybloom jobs list --limit 10 --format json ``` **Options:** - `--status ` — Filter: pending, running, completed, failed - `--limit ` — Maximum jobs to show - `--format ` — Output: table, json, csv, yaml - `--animate` — Enable animated output ### Details Get detailed status for a specific job. ```bash ivybloom jobs status JOB_ID ``` This prints one snapshot. To watch a job until it finishes, use `ivybloom jobs follow JOB_ID`. ### Details Follow a job's progress with live updates. ```bash ivybloom jobs follow JOB_ID ivybloom jobs follow JOB_ID --logs ivybloom jobs follow JOB_ID --timeout 600 ``` **Options:** - `--logs` — Show job logs - `--phase` — Show phase transitions - `--progress` — Show progress updates - `--timeout ` — Maximum follow time (default: 600) ### Details Download artifact files from completed jobs. ```bash ivybloom jobs download JOB_ID ivybloom jobs download JOB_ID --output ./results ivybloom jobs download JOB_ID --analyze ``` **Options:** - `--output`/`-o ` — Output directory - `--format text|json` — Format of the `--analyze` output - `--overwrite` — Replace existing files - `--analyze` — Include AI analysis of results ### Details View raw JSON results for a completed job (vs `download` which saves artifact files). ```bash ivybloom jobs results JOB_ID ivybloom jobs results JOB_ID --format json ``` **Options:** - `--format ` — Output: table, json, csv, yaml ### Details Stream real-time output from a running job via WebSocket. ```bash ivybloom jobs stream JOB_ID ``` ### Details Clone an existing job with optional parameter overrides. ```bash ivybloom jobs clone JOB_ID ``` ### Details There is no `jobs filter` command. Filter the list with `jobs list` flags, or pick jobs interactively with `jobs search`. ```bash ivybloom jobs list --status completed --limit 10 ivybloom jobs search --multi # interactive multi-select (requires gum) ``` **Options:** - `--tool ` — Filter by tool name - `--status ` — Filter by status - `--project-id ` — Filter by project - `--limit ` — Maximum results ### Details Mark a job as deprecated (or remove deprecation). Deprecation hides the job from default listings without deleting results. ```bash ivybloom jobs deprecate JOB_ID --reason "superseded by job_xyz" ivybloom jobs undeprecate JOB_ID ``` ### Details Cancel a running or queued job. ```bash ivybloom jobs cancel JOB_ID ``` ### Details Watch all active jobs in real-time. ```bash ivybloom jobs watch ivybloom jobs watch --interval 5 ivybloom jobs watch --include-pending ``` ### Details Search jobs by keyword across tool names, IDs, and parameters. ```bash ivybloom jobs search "esmfold" ivybloom jobs search "protein analysis" ``` --- ## Computational Tools Browse and inspect available tools. ### Details List all available computational tools. ```bash ivybloom tools list ivybloom tools list --format json ``` ### Details Get detailed information about a specific tool. ```bash ivybloom tools info esmfold ``` Shows: description, version, category, parameters, and usage. ### Details Get JSON schema for tool parameters. ```bash ivybloom tools schema esmfold ``` ### Details Show recommended default parameters for a tool. ```bash ivybloom tools defaults esmfold ``` ### Details Show an example invocation for a tool. ```bash ivybloom tools example esmfold ``` ### Details Validate parameters against a tool's schema without submitting. ```bash ivybloom tools validate esmfold '{"protein_sequence":"MKLVFF"}' ``` ### Details Estimate cost and resource requirements for a tool. ```bash ivybloom tools estimate esmfold ``` ### Details Generate a parameter skeleton file for a tool. ```bash ivybloom tools scaffold esmfold > params.json ``` --- ## Batch Processing Submit and manage parallel job collections. See [Batch Processing](/docs/cli/batch) for full documentation. > `batch` is a hidden command — accessible directly but not shown in default `--help`. ### Details Submit a batch job file. ```bash ivybloom batch submit screen.yaml ivybloom batch submit screen.yaml --parallel 8 --wait ivybloom batch submit screen.yaml --dry-run --var target_ph=8.0 ``` **Options:** - `--parallel`/`-P` — Max concurrent jobs (default: 3) - `--wait`/`-w` — Block until all jobs complete - `--dry-run`/`-d` — Validate without submitting - `--var`/`-v` — Override variable: `--var key=value` ### Details ```bash ivybloom batch list --format json --limit 20 ivybloom batch status BATCH_ID ivybloom batch monitor BATCH_ID --interval 5 --json ``` ### Details ```bash ivybloom batch pause BATCH_ID --cancel-pending ivybloom batch resume BATCH_ID --force-all --from-index 5 ivybloom batch cancel JOB_ID1 JOB_ID2 ``` ### Details ```bash ivybloom batch results JOB_ID --format json --output-dir ./out ivybloom batch collect BATCH_ID --format csv --completed-only --confidence 0.8 ``` --- ## Compounds Manage molecular compound collections. See [Compounds](/docs/cli/compounds) for full documentation. ### Details ```bash ivybloom compounds create "ADMET Hits" --description "Filtered compounds" --project proj_123 ivybloom compounds list --project proj_123 --json ivybloom compounds delete COLLECTION_ID ``` ### Details ```bash ivybloom compounds search COLL_ID --type substructure --smarts "c1ccccc1" ivybloom compounds search COLL_ID --type similarity --smiles "CC(=O)Oc1ccccc1C(=O)O" --threshold 0.8 ivybloom compounds search COLL_ID --query "aspirin" --limit 20 ivybloom compounds search COLL_ID --type property --filter "mw<500" ``` ### Details ```bash ivybloom compounds import COLLECTION_ID compounds.csv ivybloom compounds export COLLECTION_ID --format sdf --output library.sdf ``` --- ## Protein Preparation Prepare protein structures for docking. See [Protein Preparation](/docs/cli/proteinprep) for full documentation. ### Details ```bash ivybloom proteinprep run structure.pdb --output prepared.pdb --ph 7.4 --detect-sites --wait ``` **Options:** `--output`/`-o`, `--ph` (default: 7.4), `--detect-sites`, `--skip-quality`, `--wait`, `--json` ### Details ```bash ivybloom proteinprep quality structure.pdb --json ivybloom proteinprep sites structure.pdb --top 5 ivybloom proteinprep protonate structure.pdb --ph 7.4 --output protonated.pdb ``` --- ## Projects ### Details ```bash ivybloom projects list --format json ivybloom projects info PROJECT_ID ``` > Project creation, update, and deletion are **MCP-only**: `projects_create`, `projects_update`, `projects_delete`, `projects_jobs`, `projects_stats`. --- ## Sync Synchronize project data between local and remote. ### Details ```bash ivybloom sync status ivybloom sync push ivybloom sync pull ivybloom sync files ivybloom sync resolve ``` --- ## Orchestration Natural language job submission. See [Orchestration](/docs/cli/orchestration) for full documentation. ### Details ```bash ivybloom orchestrate "Predict the structure of insulin" ivybloom orchestrate "Dock caffeine against 1ABC" --tools diffdock ivybloom orchestrate "Explain BRCA1" --output json ``` **Options:** `--model`, `--tools` (comma-sep), `--output`/`-o` (text/json/yaml), `--preflight`, `--stateless` (no session persistence) --- ## MCP Server Model Context Protocol server for AI agents. See [MCP Integration](/docs/cli/mcp) for full documentation. ### Details ```bash ivybloom mcp serve # Start MCP server on stdio ivybloom mcp info # Show server capabilities ivybloom mcp tools # List all exposed tools ``` --- ## Sessions & Checkpoints Persistent conversations with time-travel. See [Sessions & Checkpoints](/docs/cli/sessions) for full documentation. ### Details ```bash ivybloom sessions list --limit 20 ivybloom sessions create ivybloom sessions get SESSION_ID ivybloom sessions append SESSION_ID --role user --content "Hello" ivybloom sessions sync SESSION_ID --mode merge ivybloom sessions delete SESSION_ID ivybloom sessions tool-call SESSION_ID --name esmfold --status running --progress 50 ``` ### Details ```bash ivybloom checkpoints list SESSION_ID ivybloom checkpoints create SESSION_ID ivybloom checkpoints rollback SESSION_ID CHECKPOINT_ID ivybloom checkpoints prune SESSION_ID ``` --- ## Chats ### Details ```bash ivybloom chats list --campaign CAMPAIGN_ID ivybloom chats history CHAT_ID --limit 50 ivybloom chats new --campaign CAMPAIGN_ID ivybloom chats resume CHAT_ID ivybloom chats export CHAT_ID --format json --output chat.json ivybloom chats archive CHAT_ID ivybloom chats delete CHAT_ID ``` --- ## Benchmarking ### Details ```bash ivybloom benchmark run esmfold ivybloom benchmark run esmfold --dataset casp15 ivybloom benchmark datasets esmfold ivybloom benchmark show BENCHMARK_ID ivybloom benchmark status BENCHMARK_ID ivybloom benchmark compare BENCH_ID1 BENCH_ID2 ``` --- ## AI Completions ### Details ```bash ivybloom ai complete "Explain EGFR inhibition" --model claude-sonnet-4-5 ivybloom ai models ``` --- ## Campaigns ### Details ```bash ivybloom campaigns list ivybloom campaigns info CAMPAIGN_ID ivybloom campaigns create "Hit-to-Lead" ivybloom campaigns use CAMPAIGN_ID # Set as active ivybloom campaigns archive CAMPAIGN_ID ivybloom campaigns unarchive CAMPAIGN_ID ivybloom campaigns delete CAMPAIGN_ID ivybloom campaigns duplicate CAMPAIGN_ID ivybloom campaigns move CAMPAIGN_ID TARGET_PROJECT_ID ``` See [Campaigns](/docs/cli/campaigns) for full documentation. --- ## Workflows & Templates ### Details ```bash ivybloom workflows list ivybloom workflows templates # list workflow templates ivybloom workflows create fold-dock.yaml # write a workflow file ivybloom workflows validate fold-dock.yaml ivybloom workflows run fold-dock.yaml --wait ivybloom templates list ivybloom templates show TEMPLATE_ID ivybloom templates create "My Template" --tools esmfold,diffdock ivybloom templates delete TEMPLATE_ID ``` See [Workflows](/docs/cli/workflows) for full documentation. --- ## Account & Profile ### Details ```bash ivybloom account info ivybloom account usage ``` ### Details ```bash ivybloom profile show ivybloom profile update --name "Jane Doe" --bio "Structural biology" ivybloom profile avatar upload https://example.com/photo.jpg ivybloom profile avatar delete ivybloom profile status --text "Running screens" --emoji "🧪" ``` ### Details ```bash ivybloom settings show ivybloom settings set --theme dark ivybloom settings newsletter show ivybloom settings newsletter set --subscribed true ivybloom settings ai-preferences set --analysis-level comprehensive ``` These are the account settings the web settings page has. Language, timezone, newsletter frequency and topics are not web settings, so the CLI refuses them. The terminal theme is set with `ivybloom config theme`. --- ## Billing & Credits See [Billing & Credits](/docs/cli/billing) for full documentation. ### Details ```bash ivybloom billing status ivybloom billing plans ivybloom billing invoices ivybloom billing upgrade --plan PLAN ivybloom billing buy-tokens ivybloom billing portal # Open billing portal in browser ivybloom billing cancel ``` ### Details ```bash ivybloom credits summary ivybloom credits stats ivybloom credits history ivybloom credits trends ivybloom credits export --format csv ivybloom credits alerts ivybloom credits alerts set --type balance_low --threshold 100 ``` The alert types are `balance_low` and `daily_spend`, as on the web usage page. --- ## Organizations See [Organizations](/docs/cli/organizations) for full documentation. ### Details ```bash ivybloom org list ivybloom org info ORG_ID ivybloom org create --name "My Lab" ivybloom org update ORG_ID --name "New Name" ivybloom org members ORG_ID ivybloom org set-role ORG_ID USER_ID --role admin ivybloom org remove-member ORG_ID USER_ID ivybloom org invite ORG_ID --email user@example.com --role member ivybloom org respond INVITE_ID --action accept ``` **Roles:** owner, admin, member, viewer --- ## API Keys ### Details ```bash ivybloom apikeys list ivybloom apikeys create --name "ci-key" --scope read_write ivybloom apikeys info KEY_ID ivybloom apikeys update KEY_ID --name "new-name" ivybloom apikeys revoke KEY_ID ``` See [API Keys & Authentication](/docs/cli/api-keys) for detailed documentation. --- ## Devices ### Details ```bash ivybloom devices list ivybloom devices trust DEVICE_ID ivybloom devices untrust DEVICE_ID ivybloom devices remove DEVICE_ID ``` --- ## Alerts & Notifications ### Details ```bash ivybloom alerts list ivybloom alerts set --event credits.low --enabled=false ivybloom alerts reset ``` Alerts are switched on or off, as in the web notification settings; `credits.low` is the one alert type the CLI sets. Channels and thresholds are not web settings; set the low-balance and daily limits with `ivybloom credits alerts set`. ### Details ```bash ivybloom notifications list ivybloom notifications mark-read NOTIFICATION_ID ivybloom notifications update-settings --device-id DEVICE_ID --job-completion --job-errors ``` --- ## Data Management ### Details ```bash ivybloom data list ivybloom data upload myfile.pdb --project-id PROJECT_ID ivybloom data download FILE_ID ivybloom data delete FILE_ID ivybloom data tag FILE_ID --tags "receptor,crystal-structure" ivybloom data sync --project-id PROJECT_ID ``` --- ## Exports & Reports ### Details ```bash ivybloom exports list ivybloom exports catalog ivybloom exports create JOB_ID --format csv --output results.csv ivybloom exports status EXPORT_ID ivybloom exports results EXPORT_ID ``` ### Details ```bash ivybloom reports list ivybloom reports generate JOB_ID --format pdf --output report.pdf ivybloom reports preview REPORT_ID ivybloom reports export REPORT_ID ``` --- ## Feature Flags ### Details ```bash ivybloom flags list ivybloom flags status FLAG_NAME ivybloom flags enable FLAG_NAME ivybloom flags disable FLAG_NAME ivybloom flags reset # Reset all to defaults ``` --- ## Interactive Modes ### Details Launch the interactive conversational interface. ```bash ivybloom # Default: starts TUI ivybloom ``` See [Interactive TUI Guide](/docs/cli/tui) for comprehensive documentation. ### Details Start an interactive shell (REPL). Aliases: `exec`, `!`. ```bash ivybloom shell ``` Type commands without the `ivybloom` prefix: ``` ivybloom> jobs list ivybloom> tools list ivybloom> run esmfold protein_sequence=MKTAYIAK... ``` **Supported commands in shell:** `cat`, `head`, `tail`, `less`, `grep`, `rg`, `awk`, `sed`, `cut`, `jq`, `yq`, `sort`, `uniq`, `wc`, `find`, `tree`, `curl`, `httpie`. Heredoc syntax supported. --- ## Utilities ### Details Check system health and API connectivity. ```bash ivybloom health ivybloom health --full ivybloom health --check api ivybloom health --check auth ivybloom health --timeout 10 ``` **Exit codes:** `0` = healthy, `1` = unhealthy. **Check components:** `api`, `auth`, `rate-limit`, `circuit-breaker`. ### Details Generate a diagnostics report. ```bash ivybloom diagnostics ivybloom diagnostics --view ``` Saves to `~/.config/ivybloom/diagnostics.json`. ### Details Run built-in example workflows. ```bash ivybloom examples list ivybloom examples show protein-fold ivybloom examples run protein-fold ``` **Built-in examples:** `protein-fold`, `docking`, `alignment`, `analysis`. ### Details ```bash ivybloom help cli # General CLI help ivybloom help tool esmfold # Help for a specific tool ivybloom help command jobs # Help for a command ivybloom help search docking # Search help ``` ### Details ```bash ivybloom version ``` ### Details Browse documentation from the CLI (hidden command). ```bash ivybloom docs list ivybloom docs read cli/batch ivybloom docs search "protein folding" ivybloom docs trending ``` ### Details Search and manage resources across the platform. ```bash ivybloom resources search "BRCA1" ivybloom resources tree --depth 2 ivybloom resources stats ivybloom resources recent --limit 10 ivybloom resources favorite TYPE RESOURCE_ID ``` --- ## Configuration Manage CLI settings. See [Configuration](/docs/cli/configuration) for full documentation. ### Details ```bash ivybloom config show ivybloom config list ivybloom config get KEY ivybloom config set KEY VALUE ivybloom config reset ivybloom config validate ivybloom config sync ivybloom config schema # View JSON schema of all config keys ivybloom config path # Show config file path ivybloom config export backup.json ivybloom config import backup.json ivybloom config theme list / set / preview ivybloom config onboarding * ivybloom config models list ivybloom config byok status / add / remove ``` --- ## Global Options These options work with any command: | Option | Short | Default | Description | |--------|-------|---------|-------------| | `--help` | `-h` | — | Show help for command | | `--version` | `-v` | — | Show CLI version | | `--profile ` | — | `"default"` | Use a specific configuration profile | | `--debug` | — | `false` | Enable debug output | | `--trace` | — | `false` | Enable trace-level logging | | `--trace-id ` | — | — | Set request correlation ID | | `--format ` | — | from config | Output format (table, json, csv, yaml) | | `--output-format ` | — | from config | Alias for `--format` | | `--json` | — | `false` | Shorthand for `--format json` | | `--no-color` | — | `false` | Disable colored output | | `--dry-run` | — | `false` | Validate without executing | | `--script` | — | `false` | Script mode: no TUI, no spinners | | `--agent` | — | `false` | Agent mode: structured JSON envelope | | `--campaign` | `-c` | — | Scope operations to a campaign | | `--message` | `-m` | — | Send a single headless message | | `--continue` | — | — | Continue a chat by ID or `"last"` | | `--resume` | `-r` | — | Alias for `--continue` | | `--force` | — | `false` | Apply changes without confirmation | | `--apply` | — | `false` | Apply file changes (safer than `--force`) | | `--follow` | — | `false` | Wait for job/batch completion | | `--stream-partial-output` | — | `false` | Stream text deltas | > For CI/CD automation, use `--agent` for structured JSON output or `--script` for non-interactive mode. See [Agent Mode](/docs/cli/agent-mode) for details. --- ## Environment Variables | Variable | Description | |----------|-------------| | `IVYBLOOM_API_KEY` | API key for authentication | | `IVYBLOOM_API_URL` | Override API base URL | | `IVYBLOOM_DEBUG=1` | Enable debug output | | `NO_COLOR=1` | Disable colored output | | `IVYBLOOM_AGENT_MODE=1` | Enable agent JSON output | | `IVYBLOOM_SCRIPT_MODE=1` | Enable script-friendly output | | `IVYBLOOM_TRACE_ID` | Request correlation ID | | `IVYBLOOM_TEST_MODE=1` | Enable test mode | | `IVYBLOOM_MOCK_MODE=1` | Enable mock responses | ```bash # Use API key from environment (CI/CD) export IVYBLOOM_API_KEY="ivy_yourKeyId_yourSecret" ivybloom jobs list --format json ```