Parameters & Command Building

Parameters define the inputs that users fill in through the Fileglancer UI. Each parameter becomes a form field, and its value is appended to your command when the job is built. This page covers how to declare parameters and how they are assembled into the final shell command.

Parameters

Each parameter with a flag field becomes a CLI flag appended to the base command. Parameters without a flag are emitted as positional arguments.

Field	Type	Required	Description
flag	string	no	CLI flag syntax (e.g. --outdir, -n). Omit for positional arguments. Must be one or two dashes followed by letters, digits, _, ., or - — flags are emitted into the job script unquoted, so shell-significant characters are rejected
name	string	yes	Display label in the UI
type	string	yes	Data type (see Parameter Types)
description	string	no	Help text shown below the input field
required	boolean	no	Whether the user must provide a value. Default: false
default	any	no	Pre-filled default value. Type must match the parameter type
options	list of strings	no	Allowed values (only for enum type)
min	number	no	Minimum value (only for integer and number types)
max	number	no	Maximum value (only for integer and number types)
pattern	string	no	Regex validation pattern (only for string type, uses full match)
hidden	boolean	no	Whether the parameter is hidden by default in the UI. Default: false
raw	boolean	no	If true, the value is appended to the command without shell quoting. Validated against shell metacharacters for safety. Default: false
value_separator	string	no	How a flagged parameter is joined to its value: "space" emits --flag 'value', "equals" emits --flag='value'. Use equals for tools (like Nextflow) that would otherwise misparse a value starting with - as another flag. Default: "space"
boolean_style	string	no	Only valid on boolean parameters. "flag" emits the bare flag when true and omits it when false; "value" emits an explicit --flag true / --flag false (or --flag=true / --flag=false with value_separator: equals). Use value for tools where omitting a false switch would leave a default of true in effect. Default: "flag"
exists	boolean	no	Only valid on file and directory parameters. When true (the default), the path must exist and be readable before launch. Set false for outputs the job creates: the existence check is skipped, and directory parameters are created (as the user, within an allowed file share) before launch, so a home default like ~/.fileglancer/logs works on first launch. Default: true

Parameter Types

Type	UI Control	CLI Output (flagged)	CLI Output (positional)	Validation
string	Text input	--flag 'value'	'value'	Optional pattern regex (full match)
integer	Number input (step=1)	--flag 42	42	Must be a whole number. Optional min/max bounds
number	Number input	--flag 3.14	3.14	Must be numeric. Optional min/max bounds
boolean	Checkbox	--flag (if true, omitted if false); --flag true / --flag false with boolean_style: value	N/A	Must be true/false
file	Text input + file browser	--flag '/path/to/file'	'/path/to/file'	Must be an absolute path that exists, is readable, and points to a file on the server (unless exists: false)
directory	Text input + directory browser	--flag '/path/to/dir'	'/path/to/dir'	Must be an absolute path that exists, is readable, and points to a directory on the server (unless exists: false)
enum	Dropdown select	--flag 'chosen_value'	'chosen_value'	Value must be one of the options list

Notes on file and directory types:

• The UI provides a browse button alongside the text input, so users can pick paths from the Fileglancer file browser instead of typing them.
• Paths are validated server-side before job submission (must exist, be accessible, and match the expected file/folder type, unless exists: false).
• Both absolute paths (/data/images) and home-relative paths (~/output) are accepted.
• Shell metacharacters (;, &, |, `, $, (, ), etc.) are rejected for safety.
• Set exists: false on paths the job creates, such as an output or logs directory. The path is still validated for file-share containment, but not for existence. If the path already exists, Fileglancer still checks that it matches the expected file/folder type. Fileglancer additionally creates exists: false directories (as the user, within an allowed file share) just before launch, so a default like ~/.fileglancer/logs works out of the box and overrides that point at a new directory are created too. Overrides pointing at an existing directory are a no-op. This never creates anything outside a file share. file parameters with exists: false skip the existence check but nothing is created for them.
• Apps auto-detected from a Nextflow pipeline’s nextflow_schema.json follow the same convention as nf-schema: a path parameter only requires existence when the schema property sets "exists": true.

Flag Forms

Parameters support three flag styles:

• Double-dash flags (most common): flag: --outdir emits --outdir '/path'
• Single-dash flags: flag: -n emits -n 5
• Positional arguments: omit flag entirely. The value is emitted as a bare argument (no flag prefix)

An internal key is auto-generated from the flag: --outdir becomes key outdir, -n becomes key n. Positional parameters get keys _arg0, _arg1, etc. Keys must be unique within the list they belong to (parameters or env_parameters); the same key may appear once in each namespace.

Parameter Sections

Parameters can be grouped into collapsible sections in the UI. A section is an item in the parameters list that has a section key instead of name/type. Sections contain their own nested parameters list (one level deep only). Top-level parameters and sections can be interleaved freely.

Field	Type	Required	Description
section	string	yes	Section title displayed in the UI
description	string	no	Help text shown next to the section title
collapsed	boolean	no	Whether the section starts collapsed. Default: false
parameters	list of objects	no	Parameter definitions within this section (same schema as top-level parameters)

parameters:
  # Top-level parameter (always visible)
  - flag: --input
    name: Input Path
    type: file
    required: true

  # Collapsible section
  - section: Advanced Options
    description: Optional tuning parameters
    collapsed: true
    parameters:
      - flag: --chunk_size
        name: Chunk Size
        type: string
        default: "128,128,128"
      - flag: --verbose
        name: Verbose
        type: boolean
        default: false

A section with collapsed: true renders as a closed accordion; users click to expand it. Sections without collapsed (or with collapsed: false) start expanded. On form validation, any section containing a parameter with an error is automatically expanded so the user can see and fix the problem.

Hidden Parameters

Parameters can be marked hidden: true to keep them out of the default form view. When any parameter in a runnable is hidden, a Show hidden toggle appears in the top right of the Parameters tab; turning it on reveals the hidden parameters.

This is useful for advanced or rarely-changed parameters you want to keep available without cluttering the form.

parameters:
  - flag: --input
    name: Input Path
    type: file
    required: true

  - flag: --debug-level
    name: Debug Level
    type: integer
    default: 0
    hidden: true

Hidden parameters still participate in command building — if they have a default, it is used even when the parameter is not visible. Hidden parameters inside a section are filtered individually; if all parameters in a section are hidden, the entire section is hidden until the toggle is turned on.

Command Building

When a job is submitted, Fileglancer constructs the full shell command from the runnable’s command field and the user-provided values using a two-pass approach:

1. Start with the base command string.
2. Merge user-provided values with defaults for any parameters the user didn’t set. An optional flagged parameter whose value is the empty string is omitted entirely rather than emitted as --flag ''.
3. Pass 1 — Flagged arguments: emit values for parameters with a flag, in declaration order (env_parameters first, then parameters):
   • Boolean with boolean_style: flag (the default) → append the flag if true (e.g. --verbose), omit entirely if false
   • Boolean with boolean_style: value → append --flag true or --flag false
   • All other types → append {flag} {shell_quoted_value}, or {flag}={shell_quoted_value} with value_separator: equals
4. Pass 2 — Positional arguments: emit values for parameters without a flag, in declaration order. Values are shell-quoted unless raw: true is set, in which case the value is appended as-is (after being validated against shell metacharacters).
5. Join all parts with line-continuation (\) for readability.

For example, given this runnable:

command: pixi run python demo.py
parameters:
  - flag: --message
    name: Message
    type: string
    required: true
  - flag: --repeat
    name: Repeat Count
    type: integer
    default: 3
  - flag: --verbose
    name: Verbose
    type: boolean
    default: false

If the user provides message: "Hello", verbose: true, and leaves repeat at its default, the resulting command is:

pixi run python demo.py \
  --message Hello \
  --repeat 3 \
  --verbose

Shell safety

All values are shell-quoted with shlex.quote() to prevent injection. The only exception is positional parameters with raw: true, where the value is appended unquoted but first rejected if it contains shell metacharacters. The raw flag has no effect on flagged parameters — those are always quoted.

Nextflow commands get Nextflow-safe forms automatically

When a runnable’s base command is nextflow run …, every double-dash (--) flagged parameter is emitted in the Nextflow-safe forms regardless of what the manifest declares: value_separator is forced to equals (so a value starting with - stays attached to its parameter instead of being parsed as another one) and booleans are forced to boolean_style: value (so unchecking a switch emits --flag=false and actually overrides a pipeline default of true). This matches how auto-detected Nextflow pipelines generate their parameters.