Galaxy automation from the shell
A Python Galaxy command-line client for automating Galaxy Project histories, datasets, collections, tools, workflows, and jobs via the Galaxy REST API.
$ galaxy-cli history create "qc run" | jq -r .id
bbd44e69cb8906b5...
$ galaxy-cli tool run "$MULTIQC_TOOL" \
--history-id "$HID" \
--inputs-json multiqc_inputs.json
{"success":true,"state":"ok",
"execution_backend":"strict",
"jobs":[{"id":"...","state":"ok"}],
"outputs":[{"output_name":"report","state":"ok"}]}Install
uv tool install galaxy-clipip install galaxy-cliAgent skill
The Python package includes a bundled galaxy-cli skill
so coding agents can choose safe Galaxy operations without spending
turns on duplicate verification. The skill contains decision rules;
command-specific --help remains the syntax reference.
galaxy-cli skill install --agent codexgalaxy-cli skill install --agent claude
Use galaxy-cli skill path to locate the packaged
SKILL.md, or pass --target-dir to install
into a project-level or custom skills directory.
Quickstart
export GALAXY_URL=https://usegalaxy.org
export GALAXY_API_KEY=your-api-key
galaxy-cli config testHID=$(galaxy-cli history create "analysis" | jq -r .id)
FASTQC_TOOL=$(galaxy-cli tool search fastqc --limit 5 | jq -r '.[0].id')
DS=$(galaxy-cli dataset upload reads.fastq.gz \
--history-id "$HID" \
--file-type fastqsanger.gz | jq -r .id)cat > tool_inputs.json <<EOF
{"input_file": "hda:$DS"}
EOF
galaxy-cli tool run "$FASTQC_TOOL" \
--history-id "$HID" \
--inputs-json tool_inputs.jsonReliable execution
A blocking tool run waits for every spawned job with one global deadline. Success includes the backend, exact tool version, final job states and exit codes, and compact metadata for every dataset and collection output.
The default auto backend prefers strict nested
execution. It falls back to legacy execution only when the initial
strict endpoint explicitly returns HTTP 404 or 405. Input errors,
timeouts, connection loss, server errors, and unknown submission
states never trigger a second submission.
Do not blindly retry an error whose
submission_state is unknown or whose
retry_safe value is false.
galaxy-cli tool run "$TOOL_ID" \
--history-id "$HID" \
--inputs-json inputs.json \
--execution-backend auto
galaxy-cli history copy "$SOURCE_HID" \
"working copy" \
--timeout 1800 \
--poll-interval 10Input encoding
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. Strict execution preserves nested
Galaxy input objects; the selectable legacy backend retains the
established pipe-key flattening behavior for older servers.
Optional repeat blocks with min: 0 can be omitted. If
a repeat item is supplied, its required child inputs still need
valid values.
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
}Pre-submission validation
galaxy-cli tool run and
galaxy-cli workflow run validate obvious input
problems before posting to Galaxy. The checks catch unknown input
names, missing required dataset or collection inputs, invalid
dataset-vs-collection prefixes, and simple select, boolean,
integer, and float value errors.
Use --dry-run-payload to validate and print the chosen
backend, endpoint, and exact POST body without submission. Use
--save-payload to keep the validated request body
alongside a real submission.
galaxy-cli tool run cat1 \
--history-id "$HID" \
-i input1="$DATASET_ID" \
--dry-run-payload
galaxy-cli workflow run "$WF" \
--history-id "$HID" \
-i 0="$DATASET_ID" \
--dry-run-payload
galaxy-cli workflow run "$WF" \
--history-id "$HID" \
-i 0="$DATASET_ID" \
--save-payload workflow_payload.json \
--waitCommand examples
galaxy-cli task tool "$FASTQC_TOOL" \
--history-name "qc $(date +%F)" \
--upload input=reads.fastq.gz \
--file-type fastqsanger.gz
galaxy-cli task workflow "$WF" \
--history-name "workflow run" \
--upload 0=reads.fastq.gzgalaxy-cli udt create-run \
--representation-json udt.json \
--history-id "$HID" \
--inputs-json udt-inputs.jsonFASTQC_TOOL=$(galaxy-cli tool search fastqc --limit 5 | jq -r '.[0].id')
MULTIQC_TOOL=$(galaxy-cli tool search multiqc --limit 5 | 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")'HID=$(galaxy-cli history create "qc $(date +%F)" | jq -r .id)
COPY=$(galaxy-cli history copy "$HID" "working copy" | jq -r .id)
galaxy-cli history show "$HID"
galaxy-cli history show "$HID" --contents
galaxy-cli dataset list --history-id "$HID"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 5PAIR=$(galaxy-cli collection create sampleA \
--history-id "$HID" \
--collection-type paired \
--forward "$R1" \
--reverse "$R2" | jq -r .id)
galaxy-cli collection show "$PAIR"cat > fastqc_inputs.json <<EOF
{"input_file": "hda:$R1"}
EOF
galaxy-cli tool run "$FASTQC_TOOL" \
--history-id "$HID" \
--inputs-json fastqc_inputs.json \
--dry-run-payload
galaxy-cli tool run "$FASTQC_TOOL" \
--history-id "$HID" \
--inputs-json fastqc_inputs.json \
--peek-output html_file \
--peek-lines 5cat > 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.jsongalaxy-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 1800galaxy-cli dataset download "$REPORT_ID" multiqc_report.html
galaxy-cli dataset download "$DATA_ZIP_ID" multiqc_data.zip
galaxy-cli history export "$HID"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" \
--dry-run-payload
galaxy-cli workflow run "$WF" \
--history-id "$HID" \
-i 0="$R1" \
--wait
galaxy-cli workflow export "$WF" -o workflow.gaCommand groups
Show configuration and test Galaxy connectivity.
Create, copy, list, inspect, publish, and delete histories.
Upload, download, show, delete, and inspect datasets.
Create list, paired, and list-of-pairs collections.
Create or reuse a history, upload files, and submit a tool or workflow in one command.
Search, inspect, run every spawned job, and return authoritative output metadata.
Create, inspect, run, and deactivate user-defined Galaxy tools.
List, show, export, run, and monitor Galaxy workflows.
Release flow
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.