CLI Reference¶

Complete reference for all otto command-line options.

Global options¶

These options are available on every otto command:

Shell completion¶

After otto --install-completion, tab completion covers the dynamic, otto-specific values a static shell script couldn’t know: suite and instruction names, host ids and their per-class verbs, transfer/term backends, reservation usernames, and — comma-separated lists included — --lab names and --tests names. It is served from a per-repo cache so the process answering the keystroke never runs your init modules or test code. --tests completes by base name and layers a static source scan (the instant floor) with a pytest-collected set that also includes dynamically-generated tests; that set warms itself from any real otto test --list-tests run, or from a one-time bounded collection on the first --tests TAB (see otto test). --clear-autocomplete-cache drops the cache if it ever goes stale.

Output directories¶

Most commands create a per-invocation output directory under --xdir before the command body runs; the run’s log files and artifacts are written there, and the path is printed at the end of the run (Output directory: ...):

<xdir>/<command>/<timestamp>_<subcommand>/

• <command> is the top-level subcommand (run, test, host, …) and <subcommand> is the leaf — the instruction name, suite name, or host verb. Commands with no distinct leaf (monitor) omit the suffix: monitor/<timestamp>/.

• <timestamp> is UTC with millisecond precision (YYYYMMDD_HHMMSS_mmm), so directories sort chronologically.

• Hyphens in command names become underscores (write-file → write_file).

Read-only commands create no directory: otto cov, otto reservation, otto schema, and otto init opt out entirely, as do read-only host verbs such as ls, exists, read-file, is-installed, and is-uninstalled. Third-party commands control this with the output_dir= flag at registration — see Extending the otto CLI.

otto init¶

Scaffold a new otto repo, or validate an existing one’s setup. See Getting Started for the full walkthrough.

otto init [--all | --lab | --tests | --instructions] [--name NAME]
          [--version X.Y.Z] [--path DIR]

otto init is lab-free: it needs no --lab and no OTTO_SUT_DIRS, and it never creates an output directory.

With no flags, otto init runs interactively: it prompts to confirm each missing area (prompting for --name/--version only when .otto/settings.toml itself is missing). --all scaffolds every missing area with no prompts. Passing one or more of --lab/--tests/ --instructions scaffolds exactly those areas, plus settings automatically whenever it’s missing — every other area depends on it.

Areas that already exist are never modified. Instead, otto init validates them with the same ingestion code otto uses elsewhere and reports each one ✓ or ✗ in a summary table; the command exits with code 1 if any existing area fails validation. The name used for areas scaffolded on a later run is read from the existing settings.toml’s name field, falling back to the directory name.

Every run also prints a “Next steps” list of the commands to run next — export OTTO_SUT_DIRS=... (skipped if the repo is already listed there), otto --install-completion, otto --lab example_lab --list-hosts, otto test --list-suites, otto test TestExample, and otto test --tests test_example_function.

otto run¶

Run registered instructions.

otto run <instruction> [OPTIONS]
otto run --list-instructions

Each instruction defines its own options via Typer annotations. Use otto run <instruction> --help to see them.

otto test¶

Run registered test suites — or, without a suite name, a suite-less selection by exact test name (--tests) and/or marker expression (-m).

otto test [PARENT OPTIONS] <Suite> [SUITE OPTIONS]
otto test [PARENT OPTIONS] --tests NAME[,NAME...] [--markers EXPR]
otto test [PARENT OPTIONS] --markers EXPR
otto test --list-suites
otto test --list-tests [--markers EXPR] [<Suite>]
otto test --list-markers

--tests and/or --markers with no suite name select across every suite and repo that has a match, including plain pytest test_* functions; bare otto test with neither flag and no suite name prints help. See otto test for the full selection-run semantics, including how suite Options defaults are applied.

Parent options (before the suite name)¶

Each suite also defines its own options via its Options dataclass — these flags only exist on that suite’s own subcommand (otto test <Suite> --flag), not on a --tests/-m selection run. Use otto test <Suite> --help to see them. Selection runs default-construct each suite’s Options; a suite with a required option fails its own tests with a hint to run the suite form directly.

otto host¶

Run commands, transfer files, log in, and invoke capability verbs on lab hosts.

otto host <HOST_ID> run [--sudo] [--timeout SECS] <COMMANDS...>
otto host <HOST_ID> put <SRC...> <DEST>
otto host <HOST_ID> get <SRC...> <DEST>
otto host <HOST_ID> login
otto host <HOST_ID> reboot [--hard] [--wait] [--timeout SECS]
otto host <HOST_ID> install [--stage-only]
otto host <HOST_ID> power [STATE]
otto host <HOST_ID> ls [PATH] [--all]
otto host --list-hosts

Subcommands¶

All otto host subcommands are synthesized from @cli_exposed host methods using the same signature-driven mechanism — run, put, get, and login included. The full set varies by host class; run otto host <HOST_ID> --help to see what is available for a specific host.

See Host capabilities for class-scoping rules and which verbs each host type exposes.

run options¶

otto host <HOST_ID> run [OPTIONS] COMMANDS...

put / get arguments¶

otto host <HOST_ID> put SRC... DEST
otto host <HOST_ID> get SRC... DEST

SRC... is one or more source paths (space-separated); DEST is the destination directory. For put, sources are local paths; for get, sources are remote paths.

reboot options¶

otto host <HOST_ID> reboot [--hard] [--wait] [--timeout SECS]

install options¶

otto host <HOST_ID> install [--stage-only]

Host-level options¶

otto monitor¶

Launch the interactive performance dashboard.

otto monitor [OPTIONS]

Docker container hosts are excluded from the default monitored fleet.

otto cov¶

Retrieve, reset, and report gcov coverage across the lab’s tiers. For the full walkthrough, prerequisites (lcov/gcov), and tier recipes, see the coverage guide.

otto cov get    [OPTIONS]
otto cov clean
otto cov report [OUTPUT_DIR...] [OPTIONS]

otto cov get options¶

Retrieval requires a git repository (captures are pinned to HEAD); a dirty working tree is remapped onto committed-code coordinates automatically.

otto cov report arguments and options¶

Tiers¶

Tiers are normally declared under [coverage.tiers] in .otto/settings.toml and loaded automatically — with no --tier flags, the report uses the configured tiers (or an implicit system tier when none are configured).

Passing any --tier flag bypasses the declarative model entirely (settings tiers, the manual store, and unit harvesting are not consulted) — a git-less fallback for foreign .info files. --tier is repeatable, and the order of flags is the precedence order — the first tier is highest precedence and wins row coloring on the annotated source view.

• --tier system (no path) — the implicit tier built by merging the supplied OUTPUT_DIR .gcda files with lcov. Only the system tier may omit a path.

• --tier NAME=PATH — any other tier; PATH must be a pre-existing lcov-format .info tracefile. A non-system tier without a path is rejected.

• Duplicate tier names are rejected.

Examples¶

otto cov get --tier manual --ticket PROJ-123 --note "verified failover"
otto cov report runs/2026-05-16_T1200/ --report ./report
otto cov report run_a/ run_b/ run_c/ --report ./combined
otto cov report runs/ --tier unit=unit.info --tier system --tier manual=manual.info

On success, otto logs the overall coverage percentage, the file count, and the path to index.html. If no coverage data is found anywhere — supplied directories, unit harvest, or the manual store — the command logs an error naming the searched locations and exits non-zero.

Collecting coverage (otto test --cov)¶

otto test --cov collects coverage as part of a test run — it fetches counters after the suite and produces the same pinned per-board captures as otto cov get:

See the otto test section above for the full option table, and the coverage guide for end-to-end examples.

otto docker¶

Build images and orchestrate compose stacks on docker-capable lab hosts.

otto docker build [--repo NAME] [--on HOST] [--rebuild] [<IMAGE>...]
otto docker up    [--repo NAME] [--on HOST] [--no-build]
otto docker down  [--repo NAME] [--on HOST]
otto docker ps    [--on HOST]

Docker subcommands¶

Docker options¶

otto reservation¶

Inspect and verify lab reservations.

otto reservation whoami
otto reservation check

Reservation subcommands¶