Configuration

Relux.toml

Every Relux project requires a Relux.toml file at the project root. The relux binary discovers this file by searching the current directory and all parent directories.

Scaffold a new project

relux new

Creates Relux.toml and the conventional directory structure in the current directory.

Minimal example

An empty Relux.toml is valid — all fields have defaults:

# empty Relux.toml is valid — all fields have defaults

The name defaults to the directory containing Relux.toml. Override it explicitly if needed:

name = "my-test-suite"

Full example

name = "my-test-suite"

[shell]
command = "/bin/sh"
prompt = "relux> "

[timeout]
match = "5s"
test = "5m"
suite = "10m"

[run]
jobs = 1

[flaky]
max_retries = 0
timeout_multiplier = 1.5

Root-level fields

Field	Type	Default	Description
`name`	string	directory containing Relux.toml	Suite name

`[shell]` section

Field	Type	Default	Description
`command`	string	`/bin/sh`	Shell executable spawned for each shell
`prompt`	string	`relux>`	PS1 prompt set on shell init

`[timeout]` section

All durations use humantime format (e.g. 5s, 1m30s, 2h).

Field	Type	Default	Description
`match`	duration	`5s`	Per-match timeout
`test`	duration	`5m`	Max wall-clock time per test
`suite`	duration	`10m`	Max wall-clock time for the entire test run

`[run]` section

Field	Type	Default	Description
`jobs`	integer	`1`	Number of parallel test workers

`[flaky]` section

Field	Type	Default	Description
`max_retries`	integer	`0`	Max retries for `# flaky`-marked tests (0 = no retries)
`timeout_multiplier`	float	`1.5`	Exponential timeout multiplier base for flaky retries (must be > 1.0)

Project structure

project-root/
├── Relux.toml
└── relux/
    ├── tests/       # test files (*.relux)
    ├── lib/         # reusable functions and effects
    ├── out/         # run output (auto-generated)
    │   ├── run-2025-03-05-…/
    │   └── latest -> run-2025-03-05-…
    └── .gitignore   # ignores out/

relux/tests/ — test files are discovered recursively when relux run is invoked without --file flags.
relux/lib/ — library files are always loaded alongside tests to make functions and effects available. May be empty or absent.
relux/out/ — run output directory. Each run creates a timestamped subdirectory. A latest symlink points to the most recent run.

CLI reference

`relux new`

Scaffolds a new project in the current directory. Errors if Relux.toml already exists.

`relux new --test <module_path>`

Creates a test module file from a template. The module path uses / separators and each segment must be lowercase alphanumeric with underscores ([a-z_][a-z0-9_]*). The .relux extension is optional.

relux new --test foo/bar/baz       # creates relux/tests/foo/bar/baz.relux
relux new --test foo/bar/baz.relux # same

`relux new --effect <module_path>`

Creates an effect module file from a template in relux/lib/. Same path rules as --test.

relux new --effect network/tcp_server       # creates relux/lib/network/tcp_server.relux

`relux run [flags]`

Runs tests. Discovers Relux.toml by walking upward from the current directory.

Use -f/--file to specify files or directories. Directories are searched recursively for *.relux files. If no --file flags are given, tests are discovered from relux/tests/.

Use -t/--test to filter by test name within a single file. Requires exactly one --file.

Library files from relux/lib/ are always loaded regardless of which files are specified.

Exits with code 1 if any test fails.

Flag	Description
`-f`, `--file <path>`	Test file or directory to run (repeatable; default: `relux/tests/`)
`-t`, `--test <name>`	Run only tests with this name (repeatable; requires exactly one `--file`)
`--manifest <path>`	Path to `Relux.toml` (default: auto-discover by walking upward)
`-j`, `--jobs`	Number of parallel test workers (default: `1`)
`--tap`	Generate TAP artifact file in the run directory
`--junit`	Generate JUnit XML artifact file in the run directory
`-m`, `--timeout-multiplier`	Scale tolerance (`~`) timeout values (default: `1.0`). Assertion (`@`) timeouts are never scaled
`--progress <mode>`	Display mode: `auto` (TUI if TTY), `plain` (results only), `tui` (force TUI)
`--strategy <mode>`	`all` (default) or `fail-fast`
`--rerun`	Re-run only non-passing tests from the latest run
`--flaky-retries`	Max retries for `# flaky`-marked tests
`--flaky-multiplier`	Exponential timeout multiplier base for flaky retries (default: `1.5`, must be > 1.0)
`--test-timeout`	Override per-test timeout (humantime string)
`--suite-timeout`	Override suite timeout (humantime string)

`relux check [paths...] [flags]`

Validates test files without executing them. Runs the parser and resolver, reports diagnostics, and exits with code 1 if any diagnostics are found. Same path discovery as run.

Flag	Description
`--manifest <path>`	Path to `Relux.toml` (default: auto-discover by walking upward)

`relux history [flags]`

Analyze run history from relux/out/.

Flag	Description
`--manifest <path>`	Path to `Relux.toml` (default: auto-discover by walking upward)
`--flaky`	Show tests that have been both passing and failing
`--failures`	Show tests that have failed
`--first-fail`	Show the first failure for each test
`--durations`	Show test duration statistics
`--tests <path>...`	Filter to specific test files or directories
`--last <N>`	Limit analysis to the N most recent runs
`--top <N>`	Show only the top N results
`--format <format>`	Output format: `human` (default) or `toml`

`relux completions [flags]`

Installs shell completions for bash, zsh, or fish. Relux uses dynamic completions — the shell calls back into the relux binary at tab-press time, enabling context-aware completions like .relux file discovery and timeout presets.

Without --install, shows a dry-run of what would be written. With --install, writes the completion script.

Flag	Description
`--shell <shell>`	Shell to generate completions for: `bash`, `zsh`, `fish` (default: autodetect from `$SHELL`)
`--install`	Write the completion script to the target location
`--path <path>`	Override the install path (required for zsh, optional for bash/fish)

Default install paths:

bash: ~/.local/share/bash-completion/completions/relux
fish: ~/.config/fish/completions/relux.fish
zsh: no default — specify with --path

Relux Reference