Working with hosts¶

otto host provides direct access to host operations from the command line – running commands, transferring files, opening an interactive shell, and invoking host capabilities – without writing a test suite or instruction.

Hosts are defined in lab.json — see Lab Configuration. This section is about using them.

otto host --help¶

Syntax¶

The host ID comes before the subcommand, so all host-level options apply to every action:

otto host <host_id> <command> [ARGS...] [OPTIONS]

The host verb model¶

Every otto host action is a verb on the host. The four core verbs – run, put, get, and login – are built in (see Core commands). Every other verb is a capability verb: a host method marked @cli_exposed that otto turns into a subcommand automatically, scoped to that host’s class. otto host <host_id> --help lists exactly the verbs the chosen host supports. See Capability verbs for the capability verbs and Netcat transfers, Connections, and Configuration for transport and tuning.

Listing hosts¶

Use --list-hosts to see which host IDs are available in the loaded lab:

otto --lab my_lab host --list-hosts

This is the same --list-hosts option available on the top-level otto command.

Tab completion¶

Host ids tab-complete from the loaded lab, including the built-in local host:

Once a host id is typed, the verb candidates narrow to that host’s class — only the verbs the chosen host actually supports:

See The host subsystem for how completion is synthesized from the same class-scoped mechanism as the verbs themselves.

Dry run¶

Like all otto commands, --dry-run (or -n) previews what would happen without executing commands or transferring files:

otto --lab my_lab --dry-run host router1 run "make install"

From Python¶

The otto host subcommands map directly to methods on the BaseHost class. Everything otto host does from the CLI can also be done inside instructions and test suites:

>>> host = LocalHost()
>>> result = run(host.run(["echo hello", "echo world"]))
>>> result.status
<Status.Success: 0>
>>> [cr.value.strip() for cr in result]
['hello', 'world']

File transfers work the same way – put and get map to put() and get():

from pathlib import Path

# Upload
res = await host.put(
    src_files=[Path("firmware.bin")],
    dest_dir=Path("/tmp"),
)
if not res:
    logger.error(f"upload failed: {res.msg}")

# Download
res = await host.get(
    src_files=[Path("/var/log/syslog")],
    dest_dir=Path("./logs"),
)
if not res:
    logger.error(f"download failed: {res.msg}")

Exit codes¶

Every otto host <name> <verb> invocation derives its exit code from the verb’s returned Result family, via Result.exit_code. Command results are ssh-like: the shell’s retcode when the command ran, 255 when it never ran. (exec is Python-only — it is not a CLI verb, so these rows apply to run.)

Custom verbs on third-party host classes may return plain values instead of a Result; the CLI prints them as-is and exits 0.

Extending¶

Hosts are otto’s most extensible area: register new connection or transfer backends (Extending otto with custom connection and transfer backends) and bring up embedded targets otto doesn’t ship support for (Extending otto for new embedded targets). The registry machinery behind every seam is described in Extension points.