Galaxy automation from the shell

galaxy-cli

A Python Galaxy command-line client for automating Galaxy Project histories, datasets, collections, tools, workflows, and jobs via the Galaxy REST API.

Install Run your first job

$ galaxy-cli history create "qc run" | jq -r .id
bbd44e69cb8906b5...

$ galaxy-cli tool run "$MULTIQC_TOOL" \
  --history-id "$HID" \
  --inputs-json multiqc_inputs.json

{"jobs":[{"id":"...","state":"ok"}],
 "outputs":[{"name":"MultiQC report","state":"ok"}]}

Install

Install from PyPI

With uv

uv tool install galaxy-cli

With pip

pip install galaxy-cli

Quickstart

Connect, upload, run

Configure Galaxy access

export GALAXY_URL=https://usegalaxy.org
export GALAXY_API_KEY=your-api-key
galaxy-cli config test

Create a history and upload data

HID=$(galaxy-cli history create "analysis" | jq -r .id)
FASTQC_TOOL=$(galaxy-cli tool search fastqc | jq -r '.[0].id')
DS=$(galaxy-cli dataset upload reads.fastq.gz \
  --history-id "$HID" \
  --file-type fastqsanger.gz | jq -r .id)

Run a Galaxy tool

cat > tool_inputs.json <<EOF
{"input_file": "hda:$DS"}
EOF

galaxy-cli tool run "$FASTQC_TOOL" \
  --history-id "$HID" \
  --inputs-json tool_inputs.json

Input encoding

Mirror the tool schema

Use --inputs-json for repeats, conditionals, collections, and tools like MultiQC. Check your instance with galaxy-cli tool show TOOL_ID, then write JSON that follows those input names. galaxy-cli flattens the payload to Galaxy's native form before submission.

Current IUC MultiQC FastQC inputs use results -> software_cond -> output. For FastQC, pass the raw data output, not the HTML report.

{
  "results": [
    {
      "software_cond": {
        "software": "fastqc",
        "output": [
          {
            "type": "data",
            "input": [
              {"src": "hda", "id": "FASTQC_RAW_DATA_1"},
              {"src": "hda", "id": "FASTQC_RAW_DATA_2"}
            ]
          }
        ]
      }
    }
  ],
  "title": "QC summary",
  "flat": true,
  "export": true
}

Command examples

Common Galaxy tasks

Discover tools and input names

FASTQC_TOOL=$(galaxy-cli tool search fastqc | jq -r '.[0].id')
MULTIQC_TOOL=$(galaxy-cli tool search multiqc | jq -r '.[0].id')
galaxy-cli tool show "$FASTQC_TOOL"
galaxy-cli --human tool show "$MULTIQC_TOOL"
galaxy-cli tool show "$MULTIQC_TOOL" \
  | jq '.inputs[] | select(.name == "results")'

Create and inspect a history

HID=$(galaxy-cli history create "qc $(date +%F)" | jq -r .id)
galaxy-cli history show "$HID"
galaxy-cli history show "$HID" --contents
galaxy-cli dataset list --history-id "$HID"

Upload and inspect datasets

R1=$(galaxy-cli dataset upload reads_R1.fastq.gz \
  --history-id "$HID" \
  --file-type fastqsanger.gz | jq -r .id)

galaxy-cli dataset show "$R1" --history-id "$HID"
galaxy-cli dataset peek "$R1" --lines 5

Create collections

PAIR=$(galaxy-cli collection create sampleA \
  --history-id "$HID" \
  --collection-type paired \
  --forward "$R1" \
  --reverse "$R2" | jq -r .id)

galaxy-cli collection show "$PAIR"

Run FastQC with JSON inputs

cat > fastqc_inputs.json <<EOF
{"input_file": "hda:$R1"}
EOF

galaxy-cli tool run "$FASTQC_TOOL" \
  --history-id "$HID" \
  --inputs-json fastqc_inputs.json

Run MultiQC on FastQC raw data

cat > multiqc_inputs.json <<EOF
{
  "results": [
    {
      "software_cond": {
        "software": "fastqc",
        "output": [
          {
            "type": "data",
            "input": [
              {"src": "hda", "id": "$FASTQC_DATA_1"},
              {"src": "hda", "id": "$FASTQC_DATA_2"}
            ]
          }
        ]
      }
    }
  ],
  "flat": true,
  "export": true
}
EOF

galaxy-cli tool run "$MULTIQC_TOOL" \
  --history-id "$HID" \
  --inputs-json multiqc_inputs.json

Debug failed jobs

galaxy-cli job list --history-id "$HID" --state error
galaxy-cli job show "$JOB_ID"
galaxy-cli job show "$JOB_ID" --logs
galaxy-cli job wait "$JOB_ID" --timeout 1800

Download outputs

galaxy-cli dataset download "$REPORT_ID" multiqc_report.html
galaxy-cli dataset download "$DATA_ZIP_ID" multiqc_data.zip
galaxy-cli history export "$HID"

Run and export workflows

WF=$(galaxy-cli workflow import workflow.ga | jq -r .id)
galaxy-cli workflow show "$WF"
galaxy-cli workflow run "$WF" \
  --history-id "$HID" \
  -i 0="$R1" \
  --wait
galaxy-cli workflow export "$WF" -o workflow.ga

Command groups

Core CLI surface

config

Show configuration and test Galaxy connectivity.

history

Create, copy, list, inspect, publish, and delete histories.

dataset

Upload, download, show, delete, and inspect datasets.

collection

Create list, paired, and list-of-pairs collections.

tool

Search, inspect, run, wait, and return compact output metadata.

workflow

List, show, export, run, and monitor Galaxy workflows.

Release flow

GitHub Release to PyPI

`galaxy-cli` uses a pandas-style release flow: publish a GitHub Release, build artifacts in Actions, attach them to the Release, and publish to PyPI with Trusted Publishing.

Release checklist

1TagvX.Y.Z

2Testpytest

3Buildsdist + wheel

4PublishPyPI OIDC