Authoring User-Defined Tools

Create a Galaxy tool from a containerized command without waiting for an administrator to install it. Define its inputs and outputs here, then run it like any other tool.

Getting Started

Quick start

Paste this definition into the editor. It accepts a text dataset and writes a copy without lines beginning with #.

class: GalaxyUserTool
id: remove_comments
name: Remove Comment Lines
version: 0.1.0
description: from a text file
container: quay.io/biocontainers/grep:3.4--hf43ccf4_4
shell_command: grep -v '^#' '$(inputs.input_file.path)' > output.txt || test "$?" = 1
inputs:
  - name: input_file
    type: data
    format:
      - txt
outputs:
  - name: output_file
    type: data
    format_source: input_file
    from_work_dir: output.txt

Reference

Tool definition

A user-defined tool is a YAML document. class: GalaxyUserTool selects the user-defined tool format. container # selects a container image containing the program and everything it needs to run. shell_command # supplies the command line Galaxy runs inside that image, with inputs referenced as $(inputs.input_name) for scalar values and $(inputs.input_name.path) for files.

Field	Details	Required
`class` #	Selects the user-defined tool format. Must be `GalaxyUserTool`.	Yes
`id`	Stable lowercase identifier. Must start with a letter and may contain letters, digits, `_`, and `-`.	No
`name`	Name displayed in the tool menu.	Yes
`version`	Version of this wrapper. Change it when behavior or the container changes.	Yes
`description`	Short text displayed after the tool name.	No
`container` #	Fully qualified image supplying the program, interpreters, libraries, and utilities the tool needs.	Yes
`shell_command` #	Command line Galaxy evaluates and runs in the selected image, with inputs referenced through expressions.	Yes
`configfiles` #	Scripts and configuration files required by the software you are wrapping.	No
`inputs` #	Input parameters shown on the tool form.	No
`outputs` #	Datasets and collections Galaxy claims after the command finishes.	No
`requirements` #	JavaScript helpers and compute-resource requests.	No
`help` #	Longer help text shown below the tool form.	No
`tests` #	Tool test declarations.	No
`citations` #, `license` #, `edam_operations` #, `edam_topics` #, `xrefs` #	Publication and ontology metadata.	No
`profile` #	Galaxy tool profile controlling versioned tool behavior.	No

Compared with an equivalent Galaxy XML tool, three things differ:

class: GalaxyUserTool is required.
A top-level container # is required. XML tools may instead resolve dependencies through Conda.
The command lives under shell_command # and is templated with sandboxed JavaScript expressions rather than Cheetah, so it has no access to the Galaxy database or filesystem.

Every output must say where its bytes come from: a data output needs from_work_dir or discover_datasets #, and a collection output needs discover_datasets #. An output that declares neither is rejected, because nothing would ever be claimed from the working directory.

Config files

Use configfiles # for scripts and configuration files required by the software you are wrapping. Galaxy writes each file into the job working directory before it runs shell_command #. File content supports the same sandboxed ECMAScript expressions as the command.

Field	Details	Default	Required
`filename`	Name of the file in the job working directory.	—	No
`content`	File contents, including any input expressions.	—	Yes
`name`	Internal name for the config file.	—	No
`eval_engine`	Template engine; user-defined tools use `ecmascript`.	`ecmascript`	No

configfiles:
  - filename: message.txt
    content: |
      Selected motif: $(inputs.motif)
shell_command: cat message.txt

Input parameters

User-defined tools support the input types listed below. Unknown and unsupported fields are rejected.

Parameter type	Details
`boolean` #	A true-or-false input.
`color` #	A color-picker input.
`conditional` #	A control input that selects which nested inputs are displayed and supplied to the command.
`data` #	One dataset, or a list of datasets when `multiple` is true.
`data_collection` #	A dataset collection input.
`float` #	A numeric input with optional bounds and validators.
`integer` #	A whole-number input with optional bounds and validators.
`repeat` #	A group the user may add multiple times, with `parameters` defining one repeated entry.
`section` #	Related inputs that users can expand or collapse to reduce form complexity.
`select` #	A choice from a fixed list of options.
`text` #	A single-line or multiline text input.

Each type below has its own field table and example.

For data inputs, format lists accepted Galaxy datatype extensions. See the Datatypes page in your Galaxy instance for the extensions available there.

Types that exist in the XML tool vocabulary but are rejected here: hidden, drill_down, data_column, genomebuild, group_tag, baseurl, rules, directory. XML-only fields such as truevalue, falsevalue, argument, is_dynamic and parameter_type are likewise rejected on any parameter.

Validators

Validators reject parameter values before a job starts. Each parameter type’s field table lists the validators it supports.

Validator type	Details
`empty_field` #	Require a value that is neither an empty string nor null.
`in_range` #	Require a numeric value to fall within optional lower and upper bounds.
`length` #	Require the number of characters in a text value to fall within optional bounds.
`no_options` #	Require a select parameter to have at least one available option.
`regex` #	Require a regular expression to match from the start of the value.

Outputs

Each output declares a type and a name. Dataset outputs identify the produced file with from_work_dir; collection outputs use discover_datasets #.

Output type	Details
`collection` #	A user-defined tool collection populated only by matching produced filenames.
`data` #	A user-defined tool dataset discovered only from files inside the job working directory.

Each type below has a field table and example.

Tool help

Tool help is rendered below the input form. Declare its format and content together.

Field	Details	Required
`format`	One of `markdown`, `restructuredtext`, or `plain_text`.	Yes
`content`	Help shown to the user.	Yes

help:
  format: markdown
  content: |
    Finds lines containing the selected motif.

Citations and metadata

Use citations # for publications describing the wrapped tool, license # for the wrapper license, EDAM identifiers for topics and operations, and xrefs # for identifiers in other registries.

citations:
  - type: doi
    content: 10.1093/bioinformatics/bts611
license: MIT
edam_topics:
  - topic_0102
edam_operations:
  - operation_0308
xrefs:
  - type: bio.tools
    value: example_tool

Expression syntax

shell_command # is not handed to the shell unchanged. Galaxy first evaluates it with a sandboxed ECMAScript 5.1 engine, using the same parameter-reference syntax CWL uses, and only the evaluated result is written into the job script.

Form	Details	Example
`$( ... )`	Parameter reference or single expression.	`$(inputs.num_lines)`, `$(inputs.query.path)`
`${ ... }`	Function body that must return a value.	`${ return inputs.num_lines * 2 }`

Substituted values are inserted literally; Galaxy does not shell-quote them. Quote any substitution that can contain spaces yourself, as '$(inputs.query.path)'.

Reusable helper functions can be declared with a javascript requirement, and are then available to every expression in the tool:

requirements:
  - type: javascript
    expression_lib:
      - |
        function basename(path) { return path.split('/').pop(); }

Resource requirements

Declare compute needs with a resource entry under requirements #:

requirements:
  - type: resource
    cores_min: 32
    ram_min: 8192
    cuda_device_count_min: 1
    cuda_device_count_max: 1
    gpu_memory_min: 40960

Field	Details	Required
`type`	Selects a resource requirement. Must be `resource`.	Yes
`cores_min`, `cores_max`	Minimum and maximum reserved CPU cores. Fractional values are allowed.	No
`ram_min`, `ram_max`	Minimum and maximum reserved RAM in MiB.	No
`tmpdir_min`, `tmpdir_max`	Minimum and maximum temporary-directory space in MiB.	No
`cuda_version_min`	Minimum required CUDA runtime version.	No
`cuda_compute_capability`	Minimum required CUDA compute capability.	No
`gpu_memory_min`	Minimum required GPU memory in MiB.	No
`cuda_device_count_min`, `cuda_device_count_max`	Minimum and maximum number of GPUs to reserve.	No
`shm_size`	Requested `/dev/shm` size in bytes.	No
`timelimit`	Maximum runtime in seconds. Galaxy terminates the job if it is exceeded.	No

Pass $GALAXY_SLOTS to threaded programs; Galaxy sets it to the number of CPU cores allocated to the job.

Use numbers or numeric strings. Other strings are reserved for runtime expressions, which are not supported yet: a non-numeric value such as 2g fails the create-time lint check (ResourceRequirementExpression), so the tool cannot be saved until it is corrected.

API endpoints

This editor is a client of a small API, so tools can also be created and managed programmatically, which is useful when registering many tools or many versions of one tool. All of these endpoints require the Custom Tool Execution role and operate only on the calling user’s own tools.

Endpoint	Purpose
`POST /api/unprivileged_tools`	Create a tool; returns its `uuid`.
`GET /api/unprivileged_tools`	List the calling user’s tools.
`GET /api/unprivileged_tools/{uuid}`	Show one tool and its representation.
`DELETE /api/unprivileged_tools/{uuid}`	Deactivate a tool.
`POST /api/unprivileged_tools/build?history_id=...`	Render the tool form without saving the tool.
`POST /api/unprivileged_tools/runtime_model`	Return an OpenAPI model of the tool’s inputs.

The create payload wraps the YAML document, converted to JSON, in a representation key. Keeping it in a file avoids complex shell quoting for shell_command #:

{
  "representation": {
    "class": "GalaxyUserTool",
    "id": "my-cool-tool",
    "name": "My Cool Tool",
    "version": "0.1.0",
    "container": "quay.io/biocontainers/python:3.13",
    "shell_command": "head -n '$(inputs.n_lines)' '$(inputs.data_input.path)' > out.txt",
    "inputs": [
      {"type": "integer", "name": "n_lines"},
      {"type": "data", "name": "data_input"}
    ],
    "outputs": [
      {"type": "data", "name": "out", "from_work_dir": "out.txt"}
    ]
  }
}

$ curl -X POST "$GALAXY_URL/api/unprivileged_tools" \
    -H "x-api-key: $GALAXY_API_KEY" \
    -H 'Content-Type: application/json' \
    -d @tool.json

Run the resulting tool by passing its uuid to the normal tool execution endpoint: POST /api/tools with tool_uuid instead of tool_id.

Your server publishes the request and response details at <galaxy_url>/api/docs under the dynamic_tools tag.

Detailed reference

Input parameter types

Field tables and examples for every input type supported by user-defined tools.

boolean parameter

A true-or-false input.

Field	Details	Default	Required
`name`	Identifier used to read this input from `shell_command` # and other expressions.	—	Yes
`label`	Label shown for the input on the tool form.	`null`	No
`help` #	Additional guidance shown on the tool form to help users choose a value.	`null`	No
`optional`	Set true when the command can run without the user supplying this input.	`false`	No
`type`	Presents a true-or-false choice and supplies the selected Boolean value to expressions.	—	Yes
`value`	Initial choice shown when the user first opens the tool form.	`false`	No

Add this boolean parameter under inputs #:

inputs:
  - label: Include a header line
    name: include_header
    type: boolean
    value: true

Use the parameter in shell_command # like this:

shell_command: |
  include_header="$(inputs.include_header)"

color parameter

A color-picker input.

Field	Details	Default	Required
`name`	Identifier used to read this input from `shell_command` # and other expressions.	—	Yes
`label`	Label shown for the input on the tool form.	`null`	No
`help` #	Additional guidance shown on the tool form to help users choose a value.	`null`	No
`optional`	Set true when the command can run without the user supplying this input.	`false`	No
`type`	Presents a color picker and supplies the selected hexadecimal color string.	—	Yes
`value`	Color initially selected in the picker, written in hexadecimal notation.	`null`	No

Add this color parameter under inputs #:

inputs:
  - label: Plot color
    name: plot_color
    type: color
    value: '#3366cc'

Use the parameter in shell_command # like this:

shell_command: |
  plot_color="$(inputs.plot_color)"

conditional parameter

A control input that selects which nested inputs are displayed and supplied to the command.

Field	Details	Default	Required
`name`	Identifier used to read this input from `shell_command` # and other expressions.	—	Yes
`label`	Label shown for the input on the tool form.	`null`	No
`help` #	Additional guidance shown on the tool form to help users choose a value.	`null`	No
`optional`	Set true when the command can run without the user supplying this input.	`false`	No
`type`	Shows one set of nested inputs at a time according to a Boolean or select control.	—	Yes
`test_parameter`	Boolean or select input whose submitted value chooses the active `whens` branch.	—	Yes
`whens`	Maps each control value to the nested parameters shown and supplied for that branch.	—	Yes

Add this conditional parameter under inputs #:

inputs:
  - name: search_options
    test_parameter:
      label: Search mode
      name: mode
      options:
      - label: Fast
        selected: true
        value: fast
      - label: Sensitive
        selected: false
        value: sensitive
      type: select
    type: conditional
    whens:
    - discriminator: fast
      parameters: []
    - discriminator: sensitive
      parameters:
      - name: iterations
        type: integer
        value: 3

Use the parameter in shell_command # like this:

shell_command: |
  mode="$(inputs.search_options.mode)"
  iterations="$(inputs.search_options.iterations)"

data parameter

One dataset, or a list of datasets when multiple is true.

Field	Details	Default	Required
`name`	Identifier used to read this input from `shell_command` # and other expressions.	—	Yes
`label`	Label shown for the input on the tool form.	`null`	No
`help` #	Additional guidance shown on the tool form to help users choose a value.	`null`	No
`optional`	Set true when the command can run without the user supplying this input.	`false`	No
`type`	Lets the user select history datasets and exposes their paths and metadata to expressions.	—	Yes
`format`	Limits selectable datasets to these Galaxy datatype extensions.	`["data"]`	No
`multiple`	Set true to accept several datasets (a list) for this input instead of one.	`false`	No

Add this data parameter under inputs #:

inputs:
  - format:
    - txt
    - tabular
    label: Input file
    name: input_file
    type: data

Use the parameter in shell_command # like this:

shell_command: |
  input_file='$(inputs.input_file.path)'

data_collection parameter

A dataset collection input.

Field	Details	Default	Required
`name`	Identifier used to read this input from `shell_command` # and other expressions.	—	Yes
`label`	Label shown for the input on the tool form.	`null`	No
`help` #	Additional guidance shown on the tool form to help users choose a value.	`null`	No
`optional`	Set true when the command can run without the user supplying this input.	`false`	No
`type`	Lets the user select a history collection and exposes its elements to expressions.	—	Yes
`collection_type`	Limits selectable collections to this structure, such as `list` or `paired`.	`null`	No
`format`	Requires every selectable collection element to use one of these datatype extensions.	`["data"]`	No

Add this data_collection parameter under inputs #:

inputs:
  - collection_type: paired
    format:
    - fastqsanger
    label: Paired reads
    name: reads
    type: data_collection

Use the parameter in shell_command # like this:

shell_command: |
  forward='$(inputs.reads.elements.forward.path)'
  reverse='$(inputs.reads.elements.reverse.path)'

float parameter

A numeric input with optional bounds and validators.

Field	Details	Default	Required
`name`	Identifier used to read this input from `shell_command` # and other expressions.	—	Yes
`label`	Label shown for the input on the tool form.	`null`	No
`help` #	Additional guidance shown on the tool form to help users choose a value.	`null`	No
`optional`	Set true when the command can run without the user supplying this input.	`false`	No
`type`	Accepts a number, including decimal values, and supplies it to expressions.	—	Yes
`value`	Number prefilled when the user first opens the tool form.	`null`	No
`min`	Rejects submitted values smaller than this inclusive lower bound.	`null`	No
`max`	Rejects submitted values larger than this inclusive upper bound.	`null`	No
`validators` #	Additional validation rules; supports `in_range`.	`[]`	No

Add this float parameter under inputs #:

inputs:
  - label: Score threshold
    max: 1.0
    min: 0.0
    name: threshold
    type: float
    value: 0.5

Use the parameter in shell_command # like this:

shell_command: |
  threshold="$(inputs.threshold)"

integer parameter

A whole-number input with optional bounds and validators.

Field	Details	Default	Required
`name`	Identifier used to read this input from `shell_command` # and other expressions.	—	Yes
`label`	Label shown for the input on the tool form.	`null`	No
`help` #	Additional guidance shown on the tool form to help users choose a value.	`null`	No
`optional`	Set true when the command can run without the user supplying this input.	`false`	No
`type`	Accepts a whole number and supplies it as a numeric value to expressions.	—	Yes
`value`	Number prefilled when the user first opens the tool form.	`null`	No
`min`	Rejects submitted values smaller than this inclusive lower bound.	`null`	No
`max`	Rejects submitted values larger than this inclusive upper bound.	`null`	No
`validators` #	Additional validation rules; supports `in_range`.	`[]`	No

Add this integer parameter under inputs #:

inputs:
  - label: Number of lines
    max: 1000
    min: 1
    name: num_lines
    type: integer
    value: 10

Use the parameter in shell_command # like this:

shell_command: |
  num_lines="$(inputs.num_lines)"

repeat parameter

A group the user may add multiple times, with parameters defining one repeated entry.

Field	Details	Default	Required
`name`	Identifier used to read this input from `shell_command` # and other expressions.	—	Yes
`label`	Label shown for the input on the tool form.	`null`	No
`help` #	Additional guidance shown on the tool form to help users choose a value.	`null`	No
`optional`	Set true when the command can run without the user supplying this input.	`false`	No
`type`	Lets the user add multiple entries that all contain the same nested inputs.	—	Yes
`parameters`	Nested inputs that make up one entry in the repeated group.	`[]`	No
`min`	Keeps at least this many entries in the group and creates them when the form opens.	`null`	No
`max`	Prevents the user from adding more than this many entries.	`null`	No

Add this repeat parameter under inputs #:

inputs:
  - label: Additional files
    max: 3
    min: 0
    name: extra_files
    parameters:
    - format:
      - txt
      name: input_file
      type: data
    type: repeat

Use the parameter in shell_command # like this:

shell_command: |
  files='$(inputs.extra_files.map((item) => item.input_file.path).join(" "))'

section parameter

Related inputs that users can expand or collapse to reduce form complexity.

Field	Details	Default	Required
`name`	Identifier used to read this input from `shell_command` # and other expressions.	—	Yes
`label`	Label shown for the input on the tool form.	`null`	No
`help` #	Additional guidance shown on the tool form to help users choose a value.	`null`	No
`optional`	Set true when the command can run without the user supplying this input.	`false`	No
`type`	Places related inputs in a collapsible group to simplify the tool form.	—	Yes
`parameters`	Nested inputs displayed together inside the section.	`[]`	No

Add this section parameter under inputs #:

inputs:
  - label: Advanced options
    name: advanced
    parameters:
    - max: 1.0
      min: 0.0
      name: threshold
      type: float
      value: 0.5
    type: section

Use the parameter in shell_command # like this:

shell_command: |
  threshold="$(inputs.advanced.threshold)"

select parameter

A choice from a fixed list of options.

Field	Details	Default	Required
`name`	Identifier used to read this input from `shell_command` # and other expressions.	—	Yes
`label`	Label shown for the input on the tool form.	`null`	No
`help` #	Additional guidance shown on the tool form to help users choose a value.	`null`	No
`optional`	Set true when the command can run without the user supplying this input.	`false`	No
`type`	Lets the user choose from the declared `options` and supplies the selected value.	—	Yes
`options`	Choices presented on the tool form, each with a display label and value.	—	Yes
`multiple`	Set true to let the user select and supply several option values instead of one.	`false`	No
`validators` #	Additional validation rules; supports `no_options`.	`[]`	No

Add this select parameter under inputs #:

inputs:
  - label: Search mode
    name: mode
    options:
    - label: Fast
      selected: true
      value: fast
    - label: Sensitive
      selected: false
      value: sensitive
    type: select

Use the parameter in shell_command # like this:

shell_command: |
  mode="$(inputs.mode)"

text parameter

A single-line or multiline text input.

Field	Details	Default	Required
`name`	Identifier used to read this input from `shell_command` # and other expressions.	—	Yes
`label`	Label shown for the input on the tool form.	`null`	No
`help` #	Additional guidance shown on the tool form to help users choose a value.	`null`	No
`optional`	Set true when the command can run without the user supplying this input.	`false`	No
`type`	Accepts user-entered text and supplies the resulting string to expressions.	—	Yes
`value`	Text prefilled when the user first opens the tool form.	`null`	No
`area`	Set true to use a multiline editor instead of a single-line text box.	`false`	No
`validators` #	Additional validation rules; supports `length`, `regex`, and `empty_field`.	`[]`	No

Add this text parameter under inputs #:

inputs:
  - area: false
    label: Sequence motif
    name: motif
    type: text
    value: ACGT

Use the parameter in shell_command # like this:

shell_command: |
  motif="$(inputs.motif)"

Validator types

Field tables and examples for every validator supported by user-defined tool inputs.