stado service ensure
Invocation
stado service ensure [OPTIONS] --host <HOST> --reason <REASON> <NAME>Purpose
Assert the unit a host must be running, over ssh, idempotently. Reads the current unit first: a matching running program is `already_correct`, an existing stopped unit is started in place, and a missing unit is installed. Repeated calls use the same declaration. Where the per-login launchd domain does not exist, ensure renders the unit for the system domain under /Library/LaunchDaemons. An existing matching definition is restarted in place with `kickstart -k`. When launchd's retained Program or ProgramArguments differs from the desired definition, ensure first validates the replacement executable and complete rendered plist, then reloads that definition once and verifies launchd's readback and running executable. An unreadable retained definition is refused without touching the job. For a catalog product, every other unit on the host that runs the product's program is its predecessor, found from what it runs; no unit name is listed anywhere. A unit the product replaces whole is retired before the start and its loaded and autostart identities withdrawn in every applicable launchd domain or systemd manager; one whose work is a role of the host Stado process is retired only after the ensured live program proves it runs every such role, otherwise it is reported `kept`. Failed retirement fails the command and retains the actual partial state. The autonomy reconciler uses the same proof on each pass. Catalog `acquisition_scopes` are copied from the installed release to `$HOME/.stado/files/` and registered with the host vault before retirement or startup, as with `stado credentials acquisition-scopes sync`. A missing scope file or refused registration leaves the host unchanged.
Required inputs and options
| Input or option | Contract |
|---|---|
<NAME> | Service name; lowercase letters, digits, '.', '-' and '_' |
--host <HOST> | The single registry host that must be running it |
--from <FROM> | Absolute path, ON THE TARGET HOST, of the program the unit runs. Omit it to render the unit from the service's own declaration, which is what makes a declared service reinstallable from the document instead of from a plist somebody installed by hand |
--arg <ARGS> | One argument the unit is started with; repeat for each. Only with `--from`: the declared argument vector belongs to the declared program and the two are never mixed |
--env <NAME=VALUE> | Non-secret NAME=VALUE persisted with the unit; repeat for each key. Use `secret sync` for credentials, never put them on the command line |
--unset-env <NAME> | A variable withdrawn from the unit's declared environment; repeat for each. The declaration keeps every variable it was given until one is withdrawn here, whatever `--from` re-declares |
--reason <REASON> | Why this host must run this unit. Required: `ensure` installs units and restarts running ones, and every such change is recorded beside the registry document it declared the unit in |
--as-daemon | Install the unit as a system LaunchDaemon (`/Library/LaunchDaemons/<label>.plist`) instead of following the declaration or the per-login fallback. Implied for a registry host declared always-on on Darwin, where that is the only domain a service stays alive in; pass it for a host whose declaration does not say so yet. The privileged install and bootstrap steps run under passwordless sudo, and a host without that grant is told exactly which step was refused |
--as-launch-agent | Recreate a declared Darwin unit as a per-login Aqua LaunchAgent. The old unit must be unloaded and its old plist removed first; ensure then updates the existing registry record in one write |
--json | Command option; required or optional as shown in the invocation. |
Output and state effect
It performs the operation described above and emits its operator result on standard output or standard error. Any state change is limited to the resources and records named by the purpose and options on this page.
Refusals
- The single registry host that must be running it
- Why this host must run this unit.
- Required: `ensure` installs units and restarts running ones, and every such change is recorded beside the registry document it declared the unit in
- The privileged install and bootstrap steps run under passwordless sudo, and a host without that grant is told exactly which step was refused
- The old unit must be unloaded and its old plist removed first; ensure then updates the existing registry record in one write
- 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.