--- title: Compound Collections description: >- Create, search, import, and export molecular compound libraries from the command line. tags: - compounds - molecules - smiles - screening --- beginner The ivybloom CLI is the scriptable surface for the platform, and compound collections are how you create, search, import, and export molecular libraries from the command line. Reach for them when a scripted pipeline needs a managed set of molecules — a screening library to feed batch ADMET or docking, a hit list, a lead series, or a reference set. They give your automation a durable, reusable input surface; for the full command surface, see the [CLI overview](/docs/cli). ## Compound Collections _(since v0.8.10)_ Create, search, import, and export molecular compound libraries from the command line. --- ## Overview Compound collections are sets of molecules stored together for analysis. Common use cases: - **Screening libraries** — Import compound sets for batch ADMET or docking - **Hit lists** — Collect compounds that pass screening criteria - **Lead series** — Track optimized compounds through the pipeline - **Reference sets** — Maintain known drug or fragment libraries > Commands marked with **MCP** are available via `ivybloom mcp serve` for AI agent integration. They do not have dedicated CLI subcommands. --- ## Creating Collections ```bash ivybloom compounds create "ADMET Hits" --description "Filtered drug candidates" --project proj_abc123 ``` - `NAME` (string) — Collection name (first positional argument). - `--description` (string) — Optional description of the collection. - `--project` (string) — Project ID to associate the collection with. --- ## Importing Compounds Submit a file to import compounds from CSV, SDF, or SMILES formats: ```bash ivybloom compounds import COLLECTION_ID compounds.csv ivybloom compounds import COLLECTION_ID library.sdf --tag "round1" ivybloom compounds import COLLECTION_ID compounds.csv --skip-duplicates --wait=false ``` ### Supported Formats | Format | Extension | Description | |--------|-----------|-------------| | CSV | `.csv` | Comma-separated with SMILES column (required) | | SDF | `.sdf` | Structure-Data File (3D coordinates) | | SMILES | `.smi` | One SMILES string per line | ### Import Parameters - `COLLECTION_ID` (string) — Collection to import into (first positional argument). - `FILE` (string) — File to import (second positional argument). - `--skip-duplicates` (bool) — Check against existing compounds in the collection (not yet implemented; reserved for future use). - `--tag` (string) — Attach a label to imported compounds for later filtering (not yet implemented; reserved for future use). - `--wait` (bool) — Wait for import to complete. Set to `false` to submit and return an import ID for polling. ### Status The import endpoint accepts requests and returns `status: "pending"` with a note, but compounds are not imported yet. The feature is under development. Contact support for ETA. --- ## Searching Search compounds using four search types: `substructure`, `similarity`, `text` and `property`. The query goes in a flag, not a positional argument. ### Substructure Search Find all molecules containing a specific substructure (e.g., benzene ring): ```bash ivybloom compounds search COLL_ID --type substructure --smarts "c1ccccc1" ``` ### Similarity Search Find molecules similar to a query (Tanimoto coefficient): ```bash ivybloom compounds search COLL_ID --type similarity --smiles "CC(=O)Oc1ccccc1C(=O)O" --threshold 0.8 ``` ### Text Search Search by compound name or metadata: ```bash ivybloom compounds search COLL_ID --query "aspirin" --limit 20 ``` ### Property Filter Filter by computed properties: ```bash ivybloom compounds search COLL_ID --type property --filter "mw<500" --filter "logp<5" ``` - `COLLECTION_ID` (string) — Collection to search in (first positional argument). - `--type` (string) — Search type: `substructure`, `similarity`, `text`, or `property`. - `--smarts` (string) — Query SMARTS for `substructure` search. - `--smiles` (string) — Query SMILES for `similarity` search. - `--query` (string) — Text query for `text` search. - `--filter` (string) — Property filter such as `mw<500`. Repeat the flag to combine filters. - `--threshold` (float) — Similarity threshold (0-1). Only applies to `similarity` search. - `--limit` (int) — Maximum number of results to return. ### Output Examples **Table (default)** ``` NAME SMILES SCORE aspirin CC(=O)Oc1ccccc1C(=O)O 1.000 salicylic OC(=O)c1ccccc1O 0.823 diflunisal OC(=O)c1cc(F)c(-c2ccc(F)cc2O)cc1 0.714 ``` **JSON** ``` [ {"name": "aspirin", "smiles": "CC(=O)Oc1ccccc1C(=O)O", "score": 1.0}, {"name": "salicylic", "smiles": "OC(=O)c1ccccc1O", "score": 0.823}, {"name": "diflunisal", "smiles": "OC(=O)c1cc(F)c(-c2ccc(F)cc2O)cc1", "score": 0.714} ] ``` **CSV** ``` name,smiles,score aspirin,CC(=O)Oc1ccccc1C(=O)O,1.000 salicylic,OC(=O)c1ccccc1O,0.823 diflunisal,"OC(=O)c1cc(F)c(-c2ccc(F)cc2O)cc1",0.714 ``` --- ## Exporting Export a collection to a file: ```bash ivybloom compounds export COLL_ID --format sdf --output library.sdf ``` - `COLLECTION_ID` (string) — Collection to export (first positional argument). - `--format` (string) — Output format: `json`, `sdf`, `smiles`, or `csv`. - `--output` (string) — Output file path (`-o` shorthand). Defaults to stdout. --- ## Listing and Deleting ### List Collections ```bash ivybloom compounds list ivybloom compounds list --project proj_abc123 --limit 10 --json ``` - `--project` (string) — Filter by project ID. - `--limit` (int) — Maximum collections to return. - `--json` (bool) — Output as JSON. ### Delete a Collection ```bash ivybloom compounds delete COLLECTION_ID ``` > Deleting a collection permanently removes all compounds in it. This cannot be undone. --- ## Workflow Integration ### Pipe to Batch ADMET Screening Export a collection, then screen through ADMET: ```bash # Export as CSV ivybloom compounds export COLL_ID --format csv --output library.csv # Create batch file from the library and submit ivybloom batch submit admet-screen.yaml --wait ivybloom batch collect BATCH_ID --format csv --output admet-results.csv ``` ### Docking Library Preparation Combine with protein preparation for a complete docking workflow: ```bash # Prepare the protein ivybloom proteinprep run receptor.pdb --detect-sites --wait # Export compounds for docking ivybloom compounds export COLL_ID --format sdf --output ligands.sdf ``` --- ## Read next - [Batch Processing](/docs/cli/batch) — Screen compound libraries at scale - [Protein Preparation](/docs/cli/proteinprep) — Prepare targets for docking - [Job Management](/docs/cli/jobs) — Monitor individual analysis jobs - [Recipes](/docs/cli/recipes) — End-to-end drug discovery workflows