bloomctl

Command-line tool for the Bloom Database (Salk Harnessing Plants Initiative) — log in, find cylinder experiments, download their images and metadata, and work with cylinder trait datasets.

Install

bloomctl is on PyPI as bloomctl. Current releases are pre-releases (0.1.0aN), so opt in:

uv tool install bloomctl --prerelease=allow    # isolated CLI tool (recommended)
uvx --prerelease=allow bloomctl --help         # one-off, no install
pip install --pre bloomctl                     # into the active environment

bloomctl --version

Quickstart for Cylinder Image Downloads

# 1. Log in once (prompts for your Bloom email + password; saves to ~/.bloom)
bloomctl login

# 2. Find an experiment — pick a species from a menu, grab its id
bloomctl cyl experiments list --species-menu

# 3. Download it — by id, or just by name
bloomctl cyl download ./out --experiment-id 42
bloomctl cyl download ./out --experiment-name "drought 2024"

That writes ./out/scans.csv (metadata) and the per-frame images.

Every command takes -p/--profile to target a different login (default prod), and

the list commands take --output csv|json for machine-readable output.

Commands

Find & download (any logged-in user):

Pipeline (stage-in / write-back):

Run bloomctl <command> --help for the full options of any command.

Run as a container

Prefer a container (e.g. a pipeline step) over a pip install? The same CLI is published to GHCR:

ghcr.io/salk-harnessing-plants-initiative/bloomctl

docker run --rm ghcr.io/salk-harnessing-plants-initiative/bloomctl:staging \
  cyl ingest-result path/to/scan.result.json

Tags: :staging (latest staging build) · :<version> (matches the PyPI release of the same name) · :sha-<git-sha> (immutable, one per commit). Image provenance and build details are in the repo docs.

Notes

• Species selector — --species NAME filters by species (typed, scriptable); --species-menu picks from a menu. Same on every command; the two are mutually exclusive.
• Interactive menus (--species-menu, --experiment) need a terminal; in a pipe/CI they abort rather than guess. For scripting, pass the typed value/id and use --output json.
• Read vs write — browsing/downloading works for any account; the write commands (ingest-result, datasets create) need an account with write access.

Documentation

Full docs — per-command detail, the container image, and access roles — are in the project repository.

Tutorials

Download an experiment, from login to files

A start-to-finish walkthrough for the common task — "get me the images + metadata for the soybean drought experiment."

# 1. Log in (once). Defaults to prod; use --server + -p for a named staging/local profile.
bloomctl login
#    → prompts for email + password; writes credentials to ~/.bloom

# 2. Find the experiment — browse by species from a menu (menu prints to stderr):
bloomctl cyl experiments list --species-menu
#    Select a species:
#      0) All species
#      1) Arabidopsis
#      2) Soybean
#    → prints the table; note the experiment_id you want, e.g. 42
#    (or skip this and let `download` resolve the name — see step 4)

# 3. (optional) Sanity-check the contents before pulling gigabytes of images:
bloomctl cyl accessions list --experiment-id 42       # which accessions are in it
bloomctl cyl accessions sample-counts --species-menu  # plant count per accession (pick a species)
bloomctl cyl datasets list --experiment-id 42         # any trait datasets already built

# 4. Download it — metadata only first to preview, then the full pull:
bloomctl cyl download ./soy-drought --experiment-id 42 --meta-only   # scans.csv only
bloomctl cyl download ./soy-drought --experiment-id 42               # scans.csv + all frames
#    …or without ever looking up the id:
bloomctl cyl download ./soy-drought --experiment-name "drought" --species Soybean

Result: ./soy-drought/scans.csv (one row per scan) plus ./soy-drought/images/Wave{n}/… (the frames). For scripting, swap the menus for explicit ids and add --output json.