Adagio CLI

adagio-cli is the Python command-line interface for Adagio pipeline execution.

For user-facing documentation and product guides, please reference the docs:

• Adagio Docs

The adagio frontend is used to build pipelines that can be run with this package on the command line It can be found here:

• Adagio

Development

Set up the project and run the test suite with:

uv sync --group dev
uv run pytest

Runtime environments

Every plugin action requires an explicit execution environment. A runtime config passed with --config can define one default and override it per plugin or task; the CLI never guesses an image from a plugin name.

Conda environments are supported with kind = "conda":

version = 1

[defaults]
kind = "conda"
prefix = "/opt/conda/envs/qiime2-2026.1"

[plugins]
dada2 = { kind = "conda", prefix = "/opt/conda/envs/q2-dada2" }

The environment must already exist and contain QIIME 2 plus the plugins needed by the pipeline. Adagio enters it with conda run; it does not create or manage the environment.

Plugin submission defaults

QAPI submissions can persist the environment that Adagio should use for the submitted plugins:

adagio qapi build --plugin my-plugin \
  --default-conda-prefix /opt/conda/envs/my-plugin

adagio qapi build --plugin my-plugin \
  --default-docker-image registry.example.org/my-plugin:2026.1

These options are explicit and mutually exclusive. Omitting both leaves the plugin without a default; the Adagio app will flag that plugin until an environment is selected for a run.

Catalog pipelines

Run a pipeline from the Adagio pipeline catalog:

adagio pipeline show @adagio/microbial-diversity
adagio run @adagio/microbial-diversity --cache-dir /path/to/cache --arguments run-arguments.json

@adagio/<slug> first resolves against a nearby local adagio-pipelines checkout when one is available. If no local catalog is found, Adagio fetches pipeline.adg from cymis/adagio-pipelines on GitHub, checking official before community.

During adagio run, remote catalog pipelines are downloaded under the selected --cache-dir and reused by source name and slug on later runs. adagio pipeline show uses a temporary download when it fetches from GitHub because it does not take a cache directory.

Private GitHub access is explicit: set GITHUB_TOKEN or GH_TOKEN to a token that can read cymis/adagio-pipelines; with a token, the CLI fetches through the GitHub contents API. The CLI does not read browser, git, or gh credentials automatically.