shelbi machine
View as markdownshelbi machine <COMMAND> [OPTIONS]shelbi machine manages the shelbi binary on the project's remote machines.
Because each worker runs in its own Shelbi session, every machine that takes
tasks needs a compatible shelbi binary of its own. These commands find, check,
or install one, and report each machine's status.
A remote binary is compatible when its major.minor version matches the hub's.
Patch versions may differ. An older binary is reported as too old (and setup
installs a managed copy alongside it); a newer one is too new.
Machines are declared under the machines: block of the project YAML. The hub
reaches them over SSH.
Subcommands
| Subcommand | Description |
|---|---|
setup <NAME> | Find or install a compatible shelbi on a remote machine. Probes the machine's interactive-login PATH for a compatible binary; otherwise installs the matching release to ~/.shelbi/bin/shelbi. Idempotent: a second run with a compatible binary already in place changes nothing. |
check <NAME> | Verify a machine is ready for this project: SSH connects, a compatible shelbi is present, Git is usable, and the machine's work_dir is a writable checkout root. Read-only on the machine; records the verified binary when everything passes. |
status [<NAME>] | Show each machine's reachability, resolved shelbi path, version, and whether it is compatible with this hub. With NAME, shows just that one. |
setup
The hub probes the remote's interactive-login shell for a shelbi on PATH. A
compatible binary found there is used as-is. A package-manager install that is
too old is never overwritten: Shelbi installs its own copy at
~/.shelbi/bin/shelbi alongside it and uses that. Installs detect the remote's
OS and architecture, fetch the release matching the hub's version, and verify
its checksum. If the machine can't reach the internet, the hub downloads the
release and copies it over SSH. The resolved path is recorded in the hub's
~/.shelbi/machines.json and shown by status.
A kind: local machine needs no setup: it runs the hub's own shelbi, and
setup says so and changes nothing. An unknown machine name is an error.
setup prints one line per result, for example
devbox: already set up — compatible shelbi 0.11.0 at /home/you/.shelbi/bin/shelbi (shelbi-managed).
or devbox: installed shelbi 0.11.0 to /home/you/.shelbi/bin/shelbi.
shelbi machine setup <NAME>| Argument | Type | Default | Description |
|---|---|---|---|
<NAME> | string | — | Machine name, as declared under machines: in the project YAML (required). |
check
Checks that a machine is ready for this project without changing anything on
it: SSH connects, a compatible shelbi is present, Git is usable, and the
machine's work_dir is a writable checkout root. It installs and creates
nothing.
shelbi machine check <NAME>| Argument | Type | Default | Description |
|---|---|---|---|
<NAME> | string | — | Machine name, as declared under machines: in the project YAML (required). |
On success it prints <name>: ready. followed by a summary, and records the
verified binary in the hub's ~/.shelbi/machines.json. Otherwise it prints one
<name>: <issue> line per problem, suggests shelbi machine setup <name> when
an install would fix it, and exits non-zero with <name>: not ready. A local
machine has nothing to check over SSH, and check says so.
status
shelbi machine status [<NAME>]Prints the hub's version, then one row per machine. Each remote is probed live
over SSH, and a reachable probe refreshes its record in ~/.shelbi/machines.json.
hub version: 0.11.0
MACHINE REACHABLE PATH VERSION COMPATIBLE
hub local /opt/homebrew/bin/shelbi 0.11.0 yes
devbox yes /home/you/.shelbi/bin/shelbi 0.11.0 yesREACHABLE is local, yes, unreachable, auth-denied, or host-key. A
local machine shows the hub's own executable. For a machine that can't be
reached, the last recorded path is shown with (last known). COMPATIBLE is
yes, no, not installed, or - (no record).
| Argument | Type | Default | Description |
|---|---|---|---|
[<NAME>] | string | all machines | Machine to inspect. Omit to show every declared machine. |
Flags
Every subcommand accepts the same options:
| Flag | Type | Default | Description |
|---|---|---|---|
--root <PATH> | string | install-time default / $SHELBI_ROOT / ~/.shelbi | Override the Shelbi root directory. The flag wins over both the env var and the compile-time default. |
-p, --project <PROJECT> | string | env / cwd lookup | Project to operate on. |
Examples
Install or verify shelbi on the devbox machine:
shelbi machine setup devboxVerify devbox is ready without changing anything on it:
shelbi machine check devboxCheck every declared machine:
shelbi machine statusSee also
- Workspaces — how remote workspaces run their agents in sessions on their own machines.
shelbi attach— attach to a session on any machine.