Command Line Arguments
This document describes all command-line arguments and options for rouser.
Usage
rouser [OPTIONS]
Options
Configuration
| Option | Description | Default Search Order |
|---|---|---|
-c, --config <CONFIG> |
Path to a single configuration file (overrides merge behavior) | — |
By default, rouser loads and merges multiple config sources in priority order (lowest → highest):
- Embedded defaults — compiled-in TOML from
config/rouser.toml /etc/rouser/config.toml— system-wide user overrides$XDG_CONFIG_HOME/rouser/config.tomlor~/.config/rouser/config.toml— per-user overrides
When a specified config file path exists, its values override the embedded defaults (deep merge: nested tables are merged field-by-field). When it does not exist and rouser is running as root, the default config is automatically installed at /etc/rouser/config.toml. For non-root users, the default is auto-installed at ~/.config/rouser/config.toml.
When --config is explicitly provided, only that single file is loaded (no merging). This takes priority over all other config sources.
Examples:
# Use custom config path (single file, no merging)
rouser --config /path/to/custom-config.toml
rouser -c /etc/my-custom-rouser.toml
# Auto-merge: embedded defaults + user/system overrides
rouser
Validation
| Option | Description |
|---|---|
--validate-config |
Validate configuration and exit without running the daemon |
Validates that the config file exists, is valid TOML, and all fields match the expected schema. Does not start metric collection or inhibition.
Example:
# Validate using default path search
rouser --validate-config
# Validate explicit config
rouser -c /etc/rouser/config.toml --validate-config
Expected output on success: Configuration validation passed
Expected output on failure: Configuration validation failed: <error details>
Runtime Mode
| Option | Description |
|---|---|
--dry-run |
Test mode: collect metrics and log readings but never inhibit sleep. Runs indefinitely until interrupted (Ctrl+C). |
Example:
# Dry run with default config search — runs forever until Ctrl+C
rouser --dry-run
# Dry run with explicit config, debug logging to see per-device GPU readings
RUST_LOG=debug rouser -c /etc/rouser/config.toml --dry-run
Logging Level Override
| Option | Description | Precedence |
|---|---|---|
-l, --log-level <LEVEL> |
Set log level at runtime, overriding config.log_level and RUST_LOG env var. Values: debug, info, warn, error. |
Highest — overrides everything |
Log level precedence (highest to lowest):
1. CLI flag -l/--log-level
2. Environment variable RUST_LOG
3. Config file field log_level at root level
4. Hardcoded default "info"
Examples:
# Override log level via CLI (takes priority over RUST_LOG and config)
rouser --dry-run -l debug
# Set via environment variable (lower precedence than -l flag)
RUST_LOG=debug rouser --dry-run
# Both can be combined — CLI flag wins if both are set
RUST_LOG=error rouser --dry-run -l debug # Results in debug level
Help and Version
| Option | Description |
|---|---|
-h, --help |
Print help information (all available options) |
-V, --version |
Print version information (from Cargo.toml package version) |
Examples:
rouser --version
# Output: rouser 0.1.0
rouser --help
Complete Examples
Basic Usage
# Run with default config search path
rouser
# Dry run to test configuration without inhibiting sleep
rouser --dry-run
# Validate config and exit (useful in CI or deployment scripts)
rouser --validate-config
Custom Configuration Paths
# Use custom config (single file, no merging with defaults)
rouser -c /etc/my-custom-rouser.toml
# Auto-merge: embedded defaults + system user overrides + per-user overrides
rouser
# System-wide override (auto-installed if running as root on first start)
sudo tee /etc/rouser/config.toml > /dev/null <<EOF
update_interval = "10s"
log_level = "warn"
...
EOF
rouser # will merge with embedded defaults
# Explicit path (always takes priority, single file load)
rouser -c /opt/custom/rouser-config.toml
Debugging with Logging
# Enable debug logging to see per-device metric readings
RUST_LOG=debug rouser --dry-run
# Override log level at runtime via CLI flag
rouser -l debug --dry-run
# Crate-specific logging (rouser debug, zbus info)
RUST_LOG=rouser=debug,zbus=info rouser --dry-run
Exit Codes
| Code | Description |
|---|---|
0 |
Success — daemon ran until interrupted or dry run completed normally |
1 |
Failure — invalid config, missing dependencies (e.g., no D-Bus), or other error |
Environment Variables
In addition to configuration file options, rouser respects these environment variables:
| Variable | Description | Affects |
|---|---|---|
RUST_LOG |
Logging level filter (see tracing-subscriber for format) | Console logging output only |
There are no ROUSER_* environment variable overrides for configuration values. All settings must come from the TOML file or be overridden at runtime via CLI flags (-l/--log-level).
RUST_LOG Format Examples
# Simple log level
RUST_LOG=debug rouser --dry-run
# Crate-specific levels
RUST_LOG=rouser=debug,zbus=info rouser --dry-run
# Module-level filtering (if applicable)
RUST_LOG=rouser::metrics=debug,rouser::service=warn rouser --dry-run
Logging Output
Console Logging
By default, rouser logs to stdout. Log format includes level, timestamp, and target module:
rouser -l debug --dry-run
# Sample output:
# 2026-04-24T10:00:00.123Z INFO rouser::service [service.rs:45] Tick 1: CPU=45.2%, card0(nvidia)=92.1%, net=12.3Mbps, disk=0.5MB/s
# 2026-04-24T10:00:00.124Z INFO rouser::inhibit [inhibit.rs:78] Sleep inhibited: GPU at 92% (threshold: 90%)
Journalctl (systemd user service)
When installed via the installer script and running as a systemd user service:
journalctl --user -u rouser -f
Error Handling
Invalid Configuration File Format
If the config file has invalid TOML syntax:
rouser --validate-config /path/to/bad.toml
# Output: Configuration validation failed: Failed to parse TOML configuration: expected `=`, found end-of-file at line 1 column 10
Missing GPU Libraries (non-fatal)
When NVML (libnvidia-ml.so) is not available but NVIDIA hardware exists in sysfs, rouser logs a warning and continues with other metrics. No error exit occurs — the daemon degrades gracefully.
Config Resolution and Merging
Config resolution follows this order (lowest priority → highest):
- Embedded defaults — always loaded first from compiled-in
config/rouser.toml /etc/rouser/config.toml— system-wide user overrides (auto-installed by rouser if running as root)$XDG_CONFIG_HOME/rouser/config.tomlor~/.config/rouser/config.toml— per-user overrides (auto-installed by rouser if non-root)
When any of the file-based config paths exist, their values are deep-merged over embedded defaults: nested tables merge field-by-field, scalar/array values from higher-priority configs override lower ones.
The --config <path> flag bypasses merging entirely — only the specified single file is loaded and used as-is.
Auto-install Behavior
On first startup (when no user config exists), rouser automatically installs the embedded default config:
- Root users: writes to /etc/rouser/config.toml
- Non-root users: writes to ~/.config/rouser/config.toml
An INFO-level log message is emitted when a config is auto-installed. The file is only created if it does not already exist — existing configs are never overwritten.
See Also
- Configuration Reference — Complete configuration options and format
- Installation — Getting started with rouser
- Systemd User Service — Running as a service