Skip to main content

ludus config — Local Configuration Management

What It Does​

ludus config manages ludus configuration without manually editing TOML files or environment variables.

Two subcommands:

  • ludus config set host <hostname> — Write host configuration to ~/.config/b4arena/config.toml
  • ludus config get <key> — Read and display a configuration value

Gettable keys: host, state_dir, watcher_log, poll_log

Why it matters: Before this, if no host was configured, the entire ludus CLI would fail to start (chicken-and-egg problem). Now users can configure their host first, then use all other commands.

Configuration discovery order (highest to lowest priority):

  1. LUDUS_HOST environment variable
  2. ~/.config/b4arena/config.toml [host] name
  3. Error: no host configured

Environment​

  • Working directory: ludus/
  • ludus CLI installed (uv run ludus)
  • No remote connection required — purely local configuration
  • ~/.config/b4arena/ directory will be created if it doesn't exist

1. Check command availability​

ludus config --help

Verify​

  • Lists set and get subcommands
  • Help text: "Manage local configuration."
  • Both subcommands shown in command list

2. Attempt to get host when not configured​

ludus config get host

Verify​

  • Exit code: 1 (error)
  • Output includes error message: "No host configured."
  • Helpful hint: "Set it with: ludus config set host "
  • Shows config file path: ~/.config/b4arena/config.toml

3. Set host configuration​

ludus config set host myrpi5

Verify​

  • Exit code: 0 (success)
  • Output: Configured host: myrpi5
  • Output: Saved to: ~/.config/b4arena/config.toml

4. Verify config file created​

cat ~/.config/b4arena/config.toml

Verify​

  • File exists and contains valid TOML: 
    [host]
    name = "myrpi5"
  • Proper syntax: [host] section header, name = "..." key-value pair

5. Get host configuration​

ludus config get host

Verify​

  • Exit code: 0 (success)
  • Output: myrpi5 (the configured hostname)
  • Simple, machine-readable format (no extra text)

6. Get XDG state directory​

ludus config get state_dir

Verify​

  • Exit code: 0
  • Output: /home/<user>/.local/state/b4arena (absolute path — or $XDG_STATE_HOME/b4arena if set)
  • Follows the freedesktop basedir spec

7. Get derived log paths​

ludus config get watcher_log
ludus config get poll_log

Verify​

  • watcher_log output: /home/<user>/.local/state/b4arena/beads-watcher.log (absolute path)
  • poll_log output: /home/<user>/.local/state/b4arena/poll.log (absolute path)
  • Both paths are derived from state_dir — no independent override

8. Override state_dir via environment variable​

LUDUS_STATE_DIR=/tmp/test-state ludus config get state_dir
LUDUS_STATE_DIR=/tmp/test-state ludus config get watcher_log

Verify​

  • state_dir output: /tmp/test-state
  • watcher_log output: /tmp/test-state/beads-watcher.log
  • Log paths follow state_dir automatically

9. Override with environment variable​

LUDUS_HOST=override-host ludus config get host

Verify​

  • Exit code: 0
  • Output: override-host
  • Environment variable takes priority over config file

10. Host-dependent commands now work​

With host configured, operations that need a host can execute:

ludus ops --help

Verify​

  • Help text shows: Infrastructure changes on myrpi5 (host: ~/.config/b4arena/config.toml or LUDUS_HOST)
  • Notice it displays the actual host myrpi5, not <not set>
  • Commands like ludus ops provision, ludus ops deploy, etc. can now proceed past initialization

11. Try unsupported key (error handling)​

ludus config set unsupported_key value

Verify​

  • Exit code: 1 (error)
  • Output: Error: unsupported key 'unsupported_key'. Only 'host' is supported.
ludus config get unsupported_key

Verify​

  • Exit code: 1 (error)
  • Output: Error: unsupported key 'unsupported_key'. Supported: host, poll_log, state_dir, watcher_log.

12. Clean up (remove config)​

rm ~/.config/b4arena/config.toml
ludus config get host

Verify​

  • Exit code: 1 (error)
  • Back to "No host configured" message
  • Cycle complete

Configuration Key Reference​

KeySettableSourceExample
hostyesLUDUS_HOST / config.tomlrpi5
state_dirread-onlyLUDUS_STATE_DIR / $XDG_STATE_HOME/b4arena~/.local/state/b4arena
watcher_logread-onlyderived from state_dir~/.local/state/b4arena/beads-watcher.log
poll_logread-onlyderived from state_dir~/.local/state/b4arena/poll.log