Commands¶

Every command is morzer <command> [flags]. The two command groups with their own subcommands live on their own pages: secret and release.

Every mutating command takes the deployment lock, journals what it did before and after each step, and can be planned first with --dry-run. Every command maps its failure onto a stable exit code.

Global flags¶

These are accepted by every command.

Index¶

init¶

Creates the directory layout, the machine's age identity, the installation configuration, the encrypted secret state and, optionally, the systemd units.

It never overwrites an existing installation, and it does not start the product: run apply afterwards.

morzer init --release ./bundle --profile embedded --domain example.com \
    --recovery-recipient age1...

The interactive first run¶

At a terminal, with something required still missing, init asks for it — product name, deployment profile (offering what the release declares), domains, and the recovery key, with an option to generate one on the spot.

It is a front-end over the flags and never a second path. It fills the same options the flags do, and prints the command line that would have produced the same result:

equivalent to:
  morzer init \
      --product demo \
      --profile embedded \
      --domain demo.example \
      --recovery-recipient age1vm6ncva…

Put that in your provisioning script and you never need the wizard again, which is the point of printing it.

It never runs with --yes, --json or --quiet, without a terminal, or when the command line already answers everything. A CI job, a systemd unit and a scripted install all take the flags exactly as given.

--require-signature without --signing-key is refused: no bundle could satisfy it, and a policy nothing can satisfy is a configuration error rather than something to discover on the next update. Both are written into installation.yaml under policy, and can be edited there afterwards.

apply¶

Renders configuration and secrets, pulls images, runs migrations, starts services and waits for health.

Idempotent: applying an unchanged system runs nothing and says so. Each step answers a Check before it runs, and a satisfied postcondition marks it skipped rather than repeating the work.

--startup is what the systemd unit uses. It exists so a machine rebooting without network connectivity still comes back up.

update¶

Installs a new release over the current one.

Takes a bundle path, or --to <version> for a release already fetched into the release store. A pre-update backup is taken by default.

morzer update ./bundle-1.3.0
morzer update --to 1.3.0

--check and --stage are alternatives, and both stop short of installing. See following a channel for what staging leaves behind and what a poll costs.

A failed update rolls back to the release that was running. The database is never rolled back automatically: when a migration cannot be undone, the release says so through compatibility.rollback_safe, and the answer is a restore from the backup taken here.

rollback¶

Returns to the previous release.

It is not "update in reverse". It assesses three questions first — are the containers reversible, is the schema compatible, is a restore required — and refuses when the answers do not permit a safe return, naming the backup to restore from instead.

Each rollback promotes the release it displaced to previous, so a second rollback without --to returns to where the first started. Reaching a release two steps back means naming it.

--force does not override a refusal. Force authorises destructive actions, not incorrect ones, and the failure mode here is quiet data corruption rather than a visible break.

status¶

Shows what is deployed, which services are up, the last backup, the last operation, and anything needing attention.

An operation that ended in exit 12 keeps surfacing in status and doctor until it is cleared explicitly. That is deliberate: the flag exists to stop an operator proceeding as though nothing happened.

Watching¶

--watch redraws the status on a timer until you press q. It is the only view that takes over the screen, and it restores what was there when it exits — there is nothing in a repeatedly-redrawn table worth keeping in the scrollback.

It observes and never acts. No key restarts a service or clears an intervention: those take the deployment lock and are journaled, which makes them commands rather than keystrokes.

A refresh that fails leaves the last good reading on screen with the error underneath, because a runtime that briefly stops answering is exactly when the previous reading matters most. Refreshes never overlap: if one is still in flight when the timer fires, the tick is skipped rather than queued against a runtime that is already struggling.

It is refused without a terminal, rather than falling back to printing the table in a loop — a --watch left in a unit file would otherwise fill a journal with thousands of copies of the same output. For scripts, poll morzer status --json instead.

doctor¶

Read-only diagnostics, with a suggested remedy for every non-ok result. It checks tool versions against what the release requires, the installation layout, the secret state, service and health status, disk headroom, and the journal.

Exits 3 when any check fails; warnings exit 0.

Three checks are advisory by design, and warn rather than fail:

The rotation remedy names the command that will actually work: secret rotate for a secret the release declares a generator for, and secret set for one it does not — pointing at rotate there would point at a command that fails.

One check about images does fail rather than warn:

backup¶

Coordinates the release's backup hook, wraps the result in a self-describing manifest, and verifies the checksums by re-reading what was written.

backup list¶

Lists backups, newest first.

backup target¶

Manages where backups are kept besides this machine. See backup target URLs.

morzer backup target add <url> records a target, checking it answers first. morzer backup target list shows them and whether each is reachable. morzer backup target remove <url> stops using one and deletes nothing that is already there.

backup push¶

Copies an existing backup to every configured target, verifying it again first. Takes a backup id; the most recent when omitted.

This is the retry for a push that failed. A backup whose push failed is still on this machine, verified and correct — what failed was the network or the medium, and the remedy should not be taking another backup.

backup fetch¶

Copies a backup down from a target into this machine's backup store, and verifies it. Takes a backup id; the newest on the target when omitted.

Restoring is a separate command on purpose: a backup that has come back from a bucket is one you should be able to look at before it overwrites a database.

backup verify¶

Re-reads a backup and checks its checksums. Takes a backup id; locally, the most recent backup when omitted.

morzer backup verify 01J8ZP...
morzer backup verify --remote

With --remote it checks the copy on the configured targets instead, streaming each component through a checksum and keeping nothing. A full transfer, and the only thing that notices rot on a target.

Omitting the id means something different in each mode: locally it verifies the most recent backup, and with --remote it verifies every backup on every configured target, which is what a scheduled check wants.

restore¶

Restores from a backup.

Destructive: it requires --force and --confirm <installation-id>, typed out. A restore that could be triggered by one mistyped command is a restore waiting to destroy a production database.

--allow-cross-installation is separate from --force because --force is already required for every restore: using it for both would mean the cross-installation guard was only ever checked after the one thing that disabled it. Restoring another deployment's data is a distinct decision and gets its own answer.

If the machine is a rebuild of the one the backup came from, installation import is the right answer instead — it restores the original id, so the guard never fires.

Restore declares that it requires manual intervention on failure: a half-restored database is a state no automatic action can repair, so a failure here exits 12 rather than pretending compensation succeeded.

version¶

Prints the manager version, the commit it was built from, and the manifest API versions it can read.

Under --json the supported API versions are a list, so a bundle author can check compatibility programmatically rather than by trial and error.