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. `deploy` installs a unit and refuses one that is already declared, so there was no command an operator could run twice, or run from a script, to make a host run what it is supposed to run. This one reads what is there first: a unit already running the declared program is reported `already_correct` with nothing touched, a unit that exists but is not running is kicked in place, and a host with no unit gets one. It also works where `deploy` cannot. An ssh login has no Aqua session, `launchctl bootstrap gui/$uid` answers `Could not switch to audit session ... Operation not permitted`, and `deploy` returned that having installed nothing — which is how two `stado agent` processes came to run for four days with no unit behind them. Where the per-login domain does not exist, the unit is rendered for launchd's system domain and installed as a daemon in /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.
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 |
--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.