CLI Reference
The repx command-line interface provides experiment management, execution, visualization, and debugging capabilities.
Synopsis
repx [OPTIONS] <COMMAND> [ARGS]
Use repx --help-all to print help for all commands and subcommands recursively.
Global Options
| Option | Short | Description |
|---|---|---|
--lab <PATH> | Lab directory path (default: ./result) | |
--verbose | -v | Increase log verbosity (repeatable: -v, -vv, -vvv) |
--resources <PATH> | Resource configuration file path | |
--target <NAME> | Execution target from config.toml | |
--scheduler <TYPE> | Override scheduler: local, slurm | |
--help-all | Print help for all commands recursively |
Commands
repx run
Execute one or more runs or individual jobs.
repx run [RUN_OR_JOB_ID...] [OPTIONS]
Accepts multiple run names or job IDs. If none are specified, all runs in the Lab are executed.
| Option | Short | Description |
|---|---|---|
--jobs <N> | -j | Maximum parallel jobs |
--mem <SIZE> | Override available memory for the local scheduler (e.g., 64G, 128G). By default, system RAM is detected automatically. | |
--continue-on-failure | Continue executing independent jobs when some fail. All failures are reported at the end. |
Exit Codes:
| Code | Meaning |
|---|---|
| 0 | All jobs completed successfully |
| 1 | One or more jobs failed |
| 2 | Configuration or validation error |
Examples:
# Execute a single run
repx run simulation --lab ./result -j 4
# Execute multiple runs
repx run training validation
# Execute a specific job by ID
repx run abc123def456
# Continue despite failures
repx run simulation --continue-on-failure
repx list
Inspect runs, jobs, dependencies, and groups in the Lab.
repx list <ENTITY> [ARGS] [OPTIONS]
repx list runs
List all runs defined in the Lab, or show details for a specific run.
repx list runs [RUN_NAME]
repx list jobs
List all jobs, optionally filtered by run, stage, or status.
repx list jobs [RUN_NAME] [OPTIONS]
| Option | Short | Description |
|---|---|---|
--stage <NAME> | -s | Filter by stage name (substring match) |
--status <STATUS> | Filter by job status (repeatable). Values: succeeded, failed, pending, running, queued, blocked | |
--output-paths | Show output directory paths | |
--param <KEY> | -p | Show effective parameter values (repeatable for multiple keys) |
--group-by-stage | -g | Group output by stage name |
When using --status, the global --target option specifies which target to check for job statuses (defaults to local).
Examples:
# List all jobs
repx list jobs
# List jobs in a specific run
repx list jobs simulation
# Filter by stage and show parameters
repx list jobs simulation -s train -p seed -p learning_rate
# Show output paths grouped by stage
repx list jobs --output-paths --group-by-stage
# List failed jobs on the default (local) target
repx list jobs --status failed
# List failed and blocked jobs
repx list jobs --status failed --status blocked
# List failed jobs on a specific target
repx --target hpc list jobs --status failed
# Combine stage and status filters
repx list jobs -s preprocess --status failed
repx list deps
Show dependencies for a specific job (alias: dependencies).
repx list deps <JOB_ID>
repx list groups
List all run groups, or show runs in a specific group.
repx list groups [GROUP_NAME]
repx show
Inspect detailed job information and output artifacts.
repx show <ENTITY> <JOB_ID> [ARGS]
repx show job
Display comprehensive information about a job: name, run, status, stage type, parameters, resource hints, inputs, outputs, file paths, log locations, and output file listing with sizes.
repx show job <JOB_ID>
repx show output
View the contents of a job's output files. Without a path argument, lists all output files. With a path, displays the file contents or directory listing.
repx show output <JOB_ID> [PATH]
Examples:
# Show job details
repx show job abc123def456
# List all output files for a job
repx show output abc123def456
# Display a specific output file
repx show output abc123def456 results.csv
repx tui
Launch the terminal user interface for interactive job monitoring.
repx tui [OPTIONS]
The TUI provides real-time job status, log streaming, resource visualization, and interactive job management. See TUI Reference for keybinding details.
repx viz
Generate experiment topology visualization. Requires Graphviz to be installed.
repx viz [OPTIONS]
| Option | Short | Description |
|---|---|---|
--output <PATH> | -o | Output file path (default: topology) |
--format <FMT> | Output format: svg, png, pdf, dot |
repx debug-run
Execute a job in debug mode with an optional interactive shell. The job environment is fully initialized, enabling inspection of inputs, environment variables, and dependency closures.
repx debug-run <JOB_ID> [OPTIONS]
| Option | Short | Description |
|---|---|---|
--command <CMD> | -c | Command to execute (default: interactive shell) |
repx trace-params
Display effective parameter values and their sources for a job, tracing inheritance through the dependency graph.
repx trace-params [JOB_ID]
repx log
View logs for a job.
repx log <JOB_ID> [OPTIONS]
| Option | Short | Description |
|---|---|---|
--lines <N> | -n | Number of lines to show (default: 50) |
--stderr | Show stderr instead of stdout | |
--follow | -f | Follow log output (like tail -f) |
By default, repx log shows stdout. For SLURM jobs, it auto-detects the combined slurm output file.
Examples:
# Show last 50 lines of stdout
repx log abc123def456
# Show last 100 lines of stderr
repx log abc123def456 -n 100 --stderr
# Follow log output
repx log abc123def456 -f
# Job ID prefix matching
repx log abc123
repx gc
Run garbage collection or manage GC roots. When called with no subcommand, removes stale artifacts from the output store. Prompts for confirmation before deleting and prints a summary of freed space afterwards.
repx gc [--target <NAME>] [--dry-run] [--yes] [--pinned-only]
| Option | Description |
|---|---|
--target <NAME> | Target to operate on (global, applies to all subcommands) |
--dry-run | Preview what would be deleted without actually deleting anything |
--yes, -y | Skip the confirmation prompt |
--pinned-only | Remove all auto GC roots before collecting, keeping only explicitly pinned labs |
repx gc list
List all GC roots (auto and pinned) on a target. Shows kind, name, lab hash, and project ID for each root.
repx gc list [--target <NAME>] [--sizes] [--kind <KIND>] [--project <ID>]
| Option | Description |
|---|---|
--sizes | Compute and display disk usage for each root |
--kind <KIND> | Filter roots by kind (auto or pinned) |
--project <ID> | Filter auto roots by project ID (substring match) |
repx gc status
Check if the current lab is pinned on a target.
repx gc status [--target <NAME>]
Reports whether the lab is pinned (and the pin name), plus how many auto roots reference it.
repx gc pin
Pin a lab to prevent its artifacts from being garbage collected.
repx gc pin [LAB_HASH] [--name <NAME>] [--target <NAME>]
| Argument/Option | Description |
|---|---|
LAB_HASH | Lab content hash to pin. Defaults to the current lab. |
--name <NAME> | Name for the pinned root. Defaults to the lab hash. |
repx gc unpin
Remove a pinned GC root.
repx gc unpin <NAME> [--target <NAME>]
| Argument | Description |
|---|---|
NAME | Name of the pinned root to remove. |
repx completions
Generate shell completion scripts.
repx completions --shell <SHELL>
Supported shells: bash, zsh, fish, elvish, powershell.
Example:
# Generate bash completions
repx completions --shell bash > ~/.local/share/bash-completion/completions/repx
# Generate zsh completions
repx completions --shell zsh > ~/.zfunc/_repx
Environment Variables
| Variable | Description |
|---|---|
REPX_LOG_LEVEL | Log verbosity: error, warn, info, debug, trace |
XDG_CONFIG_HOME | Configuration directory base (default: ~/.config) |
XDG_CACHE_HOME | Cache directory base (default: ~/.cache) |
Configuration Files
| File | Location | Purpose |
|---|---|---|
config.toml | $XDG_CONFIG_HOME/repx/ | Target and global settings |
resources.toml | Working directory or config | SLURM resource mappings |
Examples
Execute a run locally with limited concurrency:
repx run simulation --lab ./result -j 4
Submit to a remote SLURM cluster:
repx run training --target cluster --resources gpu-config.toml
Debug a failed job:
repx debug-run abc123-stage-preprocess
Inspect job details:
repx show job abc123-stage-preprocess
List jobs with specific parameters:
repx list jobs simulation -s train -p seed -p model --group-by-stage
List failed jobs on a remote target:
repx --target cluster list jobs --status failed --status blocked
Generate SVG topology diagram:
repx viz --format svg --output experiment.svg