Skip to content

CLI Reference

Note: the user-facing CLI lives in lb_ui (invoke via lb or python -m lb_ui.cli). Runner/controller packages do not expose separate entrypoints.

Setup

  • Install in a venv: uv venv && uv pip install -e ".[ui,controller]"
  • Make lb globally available (optional): uv tool install -e ".[ui,controller]"
  • Enable shell completion: lb --install-completion (bash/zsh/fish)

Global flags

  • --headless forces headless output (useful in CI or pipes).

Config resolution

Order used by commands that need a config:

  1. -c/--config flag
  2. Saved default at ~/.config/lb/config_path (set via lb config set-default or lb config init)
  3. ./benchmark_config.json if present
  4. Built-in defaults

Top-level commands

  • lb run [WORKLOAD ...] [-c FILE] [--run-id ID] [--experiment/-e NAME] [--analyze/--no-analyze] [--remote/--no-remote] [--repetitions N] [--intensity LEVEL] [--setup/--no-setup] [--stop-file PATH] [--debug] Run workloads remotely via Ansible. Local execution is not supported by the CLI. --analyze unifies the run's experiment into data_exports/<experiment>/ when the run ends, without asking; an interactive run asks instead (default No), and --no-analyze never asks. --experiment adds the run to an experiment (also settable as experiment_id in the config file; the command line wins). Without one, a new exp-<date>-<time> id is generated and printed at the end of the run. Allowed: 1-64 letters, digits, ., _, -, starting with a letter or digit; the run- prefix is reserved for run ids.
  • lb run ... --docker [--docker-engine docker|podman] [--nodes N] Dev-only: provision containers and run via Ansible (requires .lb_dev_cli or LB_ENABLE_TEST_CLI=1).
  • lb run ... --multipass [--nodes N] Dev-only: provision Multipass VMs and run via Ansible (requires .lb_dev_cli or LB_ENABLE_TEST_CLI=1).
  • lb resume [RUN_ID] [-c FILE] [--root PATH] [--remote/--no-remote] [--docker|--multipass] Resume a previous run; without RUN_ID, pick interactively from benchmark_results/.
  • lb runs list [--root PATH] [-c FILE] / lb runs show RUN_ID [--root PATH] [-c FILE] Inspect stored runs under benchmark_results/.
  • lb runs analyze [--experiment/-e ID | --folder] [--root PATH] [-c FILE] [--host NAME ...] [--workload NAME ...] Unify an experiment's datasets (or every run of the folder, with --folder) into Parquet tables under data_exports/<experiment>/ (data_exports/_folders/<folder>/ for --folder). Without --experiment or --folder, an interactive terminal opens a picker with a preview, then a summary to unify, filter or cancel; headless, one of the two is required. Prints the equivalent command at the end. In lb runs list, the Analyze action opens the same flow on the selected run's experiment.
  • lb plugin ... Inspect and manage workload plugins.
  • lb provision loki-grafana install|remove|status [--mode local|docker] [--grafana-url URL] [--grafana-api-key KEY] [--loki-endpoint URL] [--no-configure] Install/remove Loki + Grafana and configure datasources/dashboards.
  • lb config ... Create and manage benchmark configuration files.
  • lb doctor ... Run prerequisite checks.
  • lb test multipass ... (dev-only) Helper to run integration tests.

Plugin management (lb plugin ...)

  • lb plugin list
  • lb plugin enable NAME
  • lb plugin disable NAME
  • lb plugin select Plugin enablement is stored in the platform config (~/.config/lb/platform.json); workloads live in the run config.

Config management (lb config ...)

  • lb config init [-i] [-c FILE] [--set-default/--no-set-default]
  • lb config set-repetitions N [-c FILE] [--set-default/--no-set-default]
  • lb config set-default FILE / lb config unset-default / lb config show-default
  • lb config edit [-c FILE]
  • lb config workloads [-c FILE]
  • lb config enable-workload NAME [-c FILE] [--set-default]
  • lb config disable-workload NAME [-c FILE] [--set-default]
  • lb config select-workloads [-c FILE] [--set-default]

Doctor checks (lb doctor ...)

  • lb doctor controller - Python deps + Ansible requirements
  • lb doctor local - local workload tools (stress-ng, fio, sysstat)
  • lb doctor multipass - Multipass availability
  • lb doctor all - run all checks

Test helpers (lb test ..., dev installs only)

  • Available when .lb_dev_cli exists in the project root or LB_ENABLE_TEST_CLI=1 is set.
  • lb test multipass [-o DIR] [--vm-count {1,2}] [--multi-workloads] [-- EXTRA_PYTEST_ARGS...]

Environment variables

  • LB_ENABLE_TEST_CLI=1 enables lb test and provisioning flags in the CLI.
  • LB_USER_PLUGIN_DIR overrides the user plugin install directory.
  • LB_STOP_FILE sets a stop sentinel path if --stop-file is omitted.
  • LB_SUPPRESS_SUMMARY suppresses the end-of-run summary table.
  • LB_TEST_RESULTS_DIR, LB_MULTIPASS_VM_COUNT customize test helpers.