Stado

CLI reference / service

stado service

Invocation

stado service <COMMAND>

Purpose

Manage the services registry hosts run: list, status, restart, adopt, retire, deploy, logs, env

Required inputs and options

This command has no command-specific inputs or options.

Output and state effect

This command group selects one of the subcommands listed below; use its exact child invocation to perform an operation.

Refusals

  • Before dispatch, Stado refuses a missing required token shown in the invocation, an unknown option, or a value outside a listed value set; argument-usage failures exit with code 2.

Subcommands

  • directory — Where a service is reachable from here, and who may use it
  • catalog — The preconfigured Wisent services, ready to deploy by name: no declaration to write, no flags to know. `service deploy <name>` and `service ensure <name>` resolve these when nothing else declares the unit
  • list — Every registry-managed service across all hosts, with its state
  • bootout — Boot one exact launchd label or systemd unit out of its system or user scope
  • reap — End the duplicate copies of one program on HOST that no declared label holds
  • watch — Sit on HOST and name the parent of the next process matching a program, while that parent is still alive
  • unit — What the host init system holds under one named unit
  • verify — Go to each consumer and check the endpoint it is told to use, and that the thing answering is the service that was declared
  • status — One service's state everywhere it is managed
  • roles — The `stado serve` roles process PID runs on this host, from its kernel argument vector, or with --resolver-state what the resolver last published here. Asked over the host channel before a role's old unit is retired or handed over
  • image — The executable image a managed unit's process runs
  • runner-runtime — The macOS GitHub runner runtime an adopted service launches
  • restart — Restart one managed unit, without a full host-recovery pass
  • recoveries — The services this host found standing and recovered: each beacon pass asks every declared service the question its catalog entry declares (`service.answering`), and one that answers nothing longer than the resolver's declared refresh interval is repaired with its declared step, restarted, recorded here and alerted. A service on another host that holds this host's resolver requests that long is recovered from here the same way, over that host's registry SSH channel, and its record names this host as `observed_by`. Reads this host's register, oldest first
  • update — Move an already-managed service onto a new artifact version
  • release — Install and activate one service release, rolling back on failed readiness
  • show — What a managed unit actually runs: its program, arguments and unit file
  • stop — Stop one managed unit, including a process the unit no longer owns
  • secret — One Skarbiec field in a service's runtime env file
  • file — One file in a managed service's target home, copied in or out byte-exact
  • env — One managed unit's environment: show it, set or unset one key, and check the endpoints its env file declares
  • serving — Is the DECLARED unit the process on its own port?
  • grant — The Skarbiec grants this service's consumers hold: show the declared ones, mint them, or reconcile one with an existing token file
  • token-file — The owner-only raw bearer file a host binds to the fleet object store
  • auth — A managed service's bearer against its own loopback endpoint
  • adopt — Bring an existing launchd/systemd unit under management
  • onboarding — Echo onboarding product metadata of managed services: attach it to one, or print every service that carries it
  • retire — Remove a service from management: bootout/disable and forget
  • handoff — Hand a placed logical service's lifecycle to its active signed release
  • remove — Remove a service entirely: stop it, withdraw its declaration and the directory routes that name it in one registry write, then delete its unit file from the host — the operation an operator means by "remove this service", which `retire` deliberately is not. The file path comes from the registry declaration, never from operator words. A failed stop or withdrawal leaves the declaration and file in place; a file-delete failure leaves the service retired and reports that partial state
  • deploy — Install a new unit under management: render, push, bootstrap, record
  • declare — Declare a service against the fleet's one contract
  • ensure — Assert the unit a host must be running, over ssh, idempotently
  • logs — Tail a managed unit's log over the approved channel