xlab/ USER MANUAL
Product ↗
XLAB / EXPERIMENT INFRASTRUCTUREREFERENCE

xlab-cli(1) ​

The executable is the source for every option below.

Download the complete help capture.

XLAB ​

text
usage: xlab [-h] [--lab LAB] [--version] [--json]
            {init,check,preflight,plan,enqueue,queue,status,work,up,pause,resume,cancel,tasks,record,import,analyze,analyse,explain,report,insight,tree,standing,corpus,suite,adapters,selftest,service,doctor} ...

Decision-tree experiment lab.

positional arguments:
  {init,check,preflight,plan,enqueue,queue,status,work,up,pause,resume,cancel,tasks,record,import,analyze,analyse,explain,report,insight,tree,standing,corpus,suite,adapters,selftest,service,doctor}
    init                create a lab with example specs and trees
    check               validate a spec or a tree
    preflight           check a spec's system under test before running it
    plan                show the randomized plan a spec would get, its spend
                        estimate and how it fits the budgets
    enqueue             preflight a spec, check its spend against the budgets,
                        plan it and queue it
    queue (status)      what is running and what waits
    work                run the queue in the foreground until it is empty
    up                  runner + trees + reports + AI analysis + dashboard,
                        until stopped
    pause               start no new run
    resume              resume (also clears a halt)
    cancel              cancel a run (a running one stops after its current
                        sample)
    tasks               manual samples waiting to be recorded
    record              record one manual sample: xlab record RUN UNIT
                        metric=value ...
    import              record manual samples from a CSV (see `xlab tasks
                        --csv`)
    analyze (analyse)   an experiment's paired comparisons and Pareto fronts
    explain             an experiment's (or one run's) verdicts and costs in
                        plain sentences
    report              write a report now: the lab's window, or one
                        experiment
    insight             run the AI analysis now
    tree                decision trees: start, status, advance, draft
    standing            sentinel runs: a short spec repeated on a schedule
                        (noise floor, drift)
    corpus              build or list corpora
    suite               task suites for agents: show one (with the digest to
                        pin) or list them
    adapters            list adapters
    selftest            check the statistics on synthetic experiments with
                        known effects
    service             print a launchd/systemd unit that keeps `xlab up`
                        running
    doctor              check this Python, the lab, its specs and trees, the
                        runner and the host

options:
  -h, --help            show this help message and exit
  --lab LAB             lab directory (default: XLAB_HOME, or the nearest
                        lab.toml upward)
  --version             show program's version number and exit
  --json                print one JSON object on stdout (also accepted after
                        the command)

Every command takes --json. Exit status: 0 done, 1 checked and found wanting,
2 error, 3 refused (preflight or budget; nothing queued).

XLAB INIT ​

text
usage: xlab init [-h] [--json] [--name NAME]
                 [--example {all,simulated,compression,manual,command,agent}]
                 [dir]

positional arguments:
  dir

options:
  -h, --help            show this help message and exit
  --json                print one JSON object on stdout (logs go to stderr)
  --name NAME
  --example {all,simulated,compression,manual,command,agent}

XLAB CHECK ​

text
usage: xlab check [-h] [--json] file

positional arguments:
  file

options:
  -h, --help  show this help message and exit
  --json      print one JSON object on stdout (logs go to stderr)

XLAB PREFLIGHT ​

text
usage: xlab preflight [-h] [--json] file

positional arguments:
  file

options:
  -h, --help  show this help message and exit
  --json      print one JSON object on stdout (logs go to stderr)

XLAB PLAN ​

text
usage: xlab plan [-h] [--json] [--seed SEED] [--limit LIMIT] file

positional arguments:
  file

options:
  -h, --help     show this help message and exit
  --json         print one JSON object on stdout (logs go to stderr)
  --seed SEED
  --limit LIMIT

XLAB ENQUEUE ​

text
usage: xlab enqueue [-h] [--json] [--front] [--skip-preflight] [--over-budget]
                    [--seed SEED] [--count COUNT]
                    file

positional arguments:
  file

options:
  -h, --help        show this help message and exit
  --json            print one JSON object on stdout (logs go to stderr)
  --front           run it next
  --skip-preflight  queue it even if its preflight fails (the runner still
                    checks before the first sample)
  --over-budget     queue it even if it does not fit the budgets now, or has
                    no estimate: it waits until it fits
  --seed SEED
  --count COUNT     queue N independent runs (fresh seeds)

XLAB QUEUE ​

text
usage: xlab queue [-h] [--json]

options:
  -h, --help  show this help message and exit
  --json      print one JSON object on stdout (logs go to stderr)

XLAB WORK ​

text
usage: xlab work [-h] [--json] [--trees]

options:
  -h, --help  show this help message and exit
  --json      print one JSON object on stdout (logs go to stderr)
  --trees     also advance trees and keep going while they queue runs

XLAB UP ​

text
usage: xlab up [-h] [--json] [--no-runner] [--no-dashboard] [--host HOST]
               [--port PORT]

options:
  -h, --help      show this help message and exit
  --json          print one JSON object on stdout (logs go to stderr)
  --no-runner
  --no-dashboard
  --host HOST
  --port PORT

XLAB PAUSE ​

text
usage: xlab pause [-h] [--json]

options:
  -h, --help  show this help message and exit
  --json      print one JSON object on stdout (logs go to stderr)

XLAB RESUME ​

text
usage: xlab resume [-h] [--json]

options:
  -h, --help  show this help message and exit
  --json      print one JSON object on stdout (logs go to stderr)

XLAB CANCEL ​

text
usage: xlab cancel [-h] [--json] run

positional arguments:
  run

options:
  -h, --help  show this help message and exit
  --json      print one JSON object on stdout (logs go to stderr)

XLAB TASKS ​

text
usage: xlab tasks [-h] [--json] [--limit LIMIT] [--csv] [run]

positional arguments:
  run

options:
  -h, --help     show this help message and exit
  --json         print one JSON object on stdout (logs go to stderr)
  --limit LIMIT
  --csv          print a CSV to fill in and `xlab import`

XLAB RECORD ​

text
usage: xlab record [-h] [--json] [--void REASON] [--note NOTE]
                   run unit [values ...]

positional arguments:
  run
  unit
  values

options:
  -h, --help     show this help message and exit
  --json         print one JSON object on stdout (logs go to stderr)
  --void REASON  void the sample instead (its block is re-planned)
  --note NOTE

XLAB IMPORT ​

text
usage: xlab import [-h] [--json] run file

positional arguments:
  run
  file

options:
  -h, --help  show this help message and exit
  --json      print one JSON object on stdout (logs go to stderr)

XLAB ANALYZE ​

text
usage: xlab analyze [-h] [--json] [--run RUN] [--metric METRIC]
                    [--control CONTROL] [--looks LOOKS]
                    [experiment]

positional arguments:
  experiment

options:
  -h, --help         show this help message and exit
  --json             print one JSON object on stdout (logs go to stderr)
  --run RUN          analyse only these runs
  --metric METRIC
  --control CONTROL
  --looks LOOKS

XLAB EXPLAIN ​

text
usage: xlab explain [-h] [--json] target

positional arguments:
  target      an experiment id or a run id

options:
  -h, --help  show this help message and exit
  --json      print one JSON object on stdout (logs go to stderr)

XLAB REPORT ​

text
usage: xlab report [-h] [--json] [--hours HOURS] [--control CONTROL]
                   [--looks LOOKS]
                   [experiment]

positional arguments:
  experiment         write this experiment's full report instead of the
                     periodic one

options:
  -h, --help         show this help message and exit
  --json             print one JSON object on stdout (logs go to stderr)
  --hours HOURS      window length (default: [reports] every_hours)
  --control CONTROL  for an experiment: compare against this arm instead of
                     the spec's control
  --looks LOOKS      for an experiment: widen intervals for N looks

XLAB INSIGHT ​

text
usage: xlab insight [-h] [--json] [--hours HOURS] [--evidence]

options:
  -h, --help     show this help message and exit
  --json         print one JSON object on stdout (logs go to stderr)
  --hours HOURS
  --evidence     print the evidence that would be sent, and stop

XLAB TREE ​

text
usage: xlab tree [-h] [--json] [--restart] [--adapter ADAPTER]
                 {start,status,advance,draft} [target]

positional arguments:
  {start,status,advance,draft}
  target                tree file (start), tree id (status) or question
                        (draft)

options:
  -h, --help            show this help message and exit
  --json                print one JSON object on stdout (logs go to stderr)
  --restart
  --adapter ADAPTER     for draft: the adapter the experiments use

XLAB STANDING ​

text
usage: xlab standing [-h] [--json] [--every-hours EVERY_HOURS] [--limit LIMIT]
                     {add,list,remove} [target]

positional arguments:
  {add,list,remove}
  target                spec file (add) or spec id (remove)

options:
  -h, --help            show this help message and exit
  --json                print one JSON object on stdout (logs go to stderr)
  --every-hours EVERY_HOURS
  --limit LIMIT         runs to show per standing spec (list)

XLAB CORPUS ​

text
usage: xlab corpus [-h] [--json] {build,list} [names ...]

positional arguments:
  {build,list}
  names

options:
  -h, --help    show this help message and exit
  --json        print one JSON object on stdout (logs go to stderr)

XLAB SUITE ​

text
usage: xlab suite [-h] [--json] {show,list} [name]

positional arguments:
  {show,list}
  name         a suite name: a folder in suites/, or generated (arith-N,
               fix-N)

options:
  -h, --help   show this help message and exit
  --json       print one JSON object on stdout (logs go to stderr)

XLAB ADAPTERS ​

text
usage: xlab adapters [-h] [--json]

options:
  -h, --help  show this help message and exit
  --json      print one JSON object on stdout (logs go to stderr)

XLAB SELFTEST ​

text
usage: xlab selftest [-h] [--json] [--experiments EXPERIMENTS]
                     [--blocks BLOCKS] [--sd SD]

options:
  -h, --help            show this help message and exit
  --json                print one JSON object on stdout (logs go to stderr)
  --experiments EXPERIMENTS
  --blocks BLOCKS
  --sd SD

XLAB SERVICE ​

text
usage: xlab service [-h] [--json]

options:
  -h, --help  show this help message and exit
  --json      print one JSON object on stdout (logs go to stderr)

XLAB DOCTOR ​

text
usage: xlab doctor [-h] [--json]

options:
  -h, --help  show this help message and exit
  --json      print one JSON object on stdout (logs go to stderr)
GENERATED FROM THE CHECKOUTSource fingerprints ↗