`moorhold` command reference
On this page
The moorhold command runs on the server Moorhold is installed on. The installer puts it at
/usr/local/bin/moorhold, and it runs the CLI of the release in /opt/moorhold/current. Run it with
sudo: the release's files are readable by root only, and without root the command says
Run it with sudo: sudo moorhold <command> and stops.
This page describes the latest release (2026.11.4). Run moorhold --help on your
server for the list your release has.
Conventions
Section titled "Conventions"--profile full|corepicks the install profile.fullruns every component the Stack declares.coreleaves out Apache Superset and DataHub, for an 8 GB server.lightis the profile of a local install, for the Moorhold app for Mac, and a server refuses it. Commands that read-f, andcheck,startand plan-style commands, default tofullwhen you don't give--profile. On an installed server,applyandstart-at-bootuse the profile the server runs.--home <dir>is where Moorhold is installed (default/opt/moorhold).--secrets-dir <dir>is where its secrets are kept (default/etc/moorhold/secrets). You only need them for a test install in another place.--dry-runshows what a command would do and changes nothing.--yesanswers its question for you, for scripts. A command that asks a question and has no terminal stops unless you give--yes.moorholdrefuses an access key, a bucket's credentials or a backup repository key on the command line, where other users and logs can read them, and exits with code 2. Put each in a file of mode0600and give the file, or leave it out to be asked in a terminal without echo.
Exit codes
Section titled "Exit codes"| Code | Meaning |
|---|---|
| 0 | Done, or nothing to do. |
| 1 | The command failed, or a check found a problem. The message says which. |
| 2 | The command line was wrong, or it carried a secret. Nothing ran. |
| 3 | upgrade refused before changing anything. |
| 64 | upgrade failed after a change, and the earlier release runs again. |
| 65 | upgrade failed after a change, and putting the earlier release back didn't finish. |
| 66 | upgrade finished and the new release runs, but the restore drill after it failed. |
| 67 | upgrade finished and the new release runs, but moorhold.service couldn't be written or enabled. Run sudo moorhold start-at-boot. |
| 68 | Both 66 and 67. |
The server
Section titled "The server"status
Section titled "status"sudo moorhold statusOn an installed server: the release, the hostname, whether the access key is kept, the backups and
the health of every service. It exits 1 when a service isn't healthy, or when moorhold.service
is missing or not enabled, because then the stack won't start again after a reboot.
sudo moorhold start [--profile full|core]Writes the stack's boot secrets to /run/moorhold again and starts the stack with Docker Compose.
moorhold.service runs it at boot.
sudo moorhold stopStops the stack with docker compose stop, keeping its containers and data. moorhold.service
runs it at shutdown. start, or the next boot, starts it again.
start-at-boot
Section titled "start-at-boot"sudo moorhold start-at-boot [--profile full|core]Writes and enables moorhold.service, which runs moorhold start at boot and moorhold stop at
shutdown, for the profile given or the one the server runs. It starts the unit when it isn't
active. The installer and every upgrade run it too. Needs root.
sudo moorhold check [--hostname <name>] [--profile full|core] [--public-address-url <https-url>]The installer's checks on their own: the system, memory for the profile, disk space and
unallocated LVM space, sleep on a desktop install, ports 80 and 443, and the network check (DNS,
where the name points, NAT loopback and carrier-grade NAT). It changes nothing, and exits 1 when a
finding would stop an install. On an installed server you can leave out --hostname.
install.sh --check runs the same checks before anything is installed.
sudo moorhold apply [--profile full|core]With no -f and no store named, on an installed server: applies an edited
/opt/moorhold/stack/stack.yaml. It renders and starts the stack again, applies the Stack to the
stack's own store as the installer does, and prints what changed. With no install on the machine
it refuses. Needs root. apply -f is in Working with a store.
Updates
Section titled "Updates"upgrade
Section titled "upgrade"sudo moorhold upgrade <version> [--profile full|core] [--access-key-file <path>]Upgrades the server to <version>. It first runs the checks of upgrade --check and stops if one
fails. Then it unpacks the verified release beside the running one and hands over to that release's
own CLI, which:
- shows what changes;
- asks for approval when a tool changes version: with one admin, you type the tool's name; with two or more, a second admin approves it in the portal;
- pulls the images with the kept access key;
- edits the Stack in place and starts the new release over the same data;
- points
/opt/moorhold/currentat the new release only once it's up.
If the new release doesn't come up, the previous one is started again. Only one update runs at a
time: if another is running, upgrade exits 1. Needs root.
upgrade --check, upgrade --dry-run
Section titled "upgrade --check, upgrade --dry-run"sudo moorhold upgrade <version> --checksudo moorhold upgrade <version> --dry-runDownloads the named release into a temporary directory, checks its signature against the key the
server trusts (/etc/moorhold/release.pub) and its sha256s, and runs the pre-upgrade checks: the
version path, the stack's health, the kept access key, disk space, and the approval and manual
steps the update needs. --dry-run also shows what the upgrade would change and do. Nothing on the
server changes. Exits 1 when a check fails. Needs root.
rollback
Section titled "rollback"sudo moorhold rollback [--database <db>] [--dry-run] [--yes]Goes back to the rollback point the last upgrade took. It shows a plan listing every database it
replaces and asks. Then it stops the apps, puts back the Postgres roles, replaces each database with
its copy from the rollback point (keeping the current one under a dated name), puts back the Stack
from before the upgrade, starts the earlier release with its own code and points
/opt/moorhold/current at it.
With --database, only that database and the roles go back. The release and the Stack stay as
they are. Needs root.
Backups
Section titled "Backups"The backup commands use the installed project in /opt/moorhold/project, unless -o <outdir> names
another.
backup
Section titled "backup"sudo moorhold backup [--list [--from-bucket]]Backs up every database of the stack now, into its encrypted restic repository (the Stack's
spec.backups). --list lists the snapshots instead. --from-bucket with --list lists
snapshots that are already in the bucket the server used for backups, without making a new backup.
backup --lake
Section titled "backup --lake"sudo moorhold backup --lake [--dry-run] [--yes]Backs up SeaweedFS's data volume as well, when the stack has one. It shows a plan and asks, stops the apps and SeaweedFS (a volume that's being written to isn't a consistent copy), takes the snapshot and starts them again.
backup status
Section titled "backup status"sudo moorhold backup statusWhere the backups are, the last backup, the last failure, the next run, the last restore drill and the last rollback point.
backup drill
Section titled "backup drill"sudo moorhold backup drillThe restore drill of every database: backs each one up, restores it into a scratch database and compares every table's row count.
backup key
Section titled "backup key"sudo moorhold backup keyPrints the backup repository key, on a terminal only. Without this key no backup can be restored. Keep a copy off the server.
backup target
Section titled "backup target"sudo moorhold backup targetsudo moorhold backup target s3 --endpoint <https://host> --region <region> --bucket <bucket> [--path <path>] [--access-key-id-file <file>] [--secret-access-key-file <file>] [--dry-run] [--yes]sudo moorhold backup target volume [--dry-run] [--yes]Where the server's backups go. With no target, it says where they go now. s3 sends them to a
bucket of your own, off this server. volume keeps them on this server. Before it switches, it
checks the bucket. Then it takes the first backup there and a restore drill, and puts everything
back as it was if that backup fails. Backups taken before the switch stay where they are.
--path defaults to moorhold/<hostname>, so each server has its own place in a shared bucket. The
credentials come from files of mode 0600, or you're asked for them without echo. Needs root.
backup restore
Section titled "backup restore"sudo moorhold backup restore <snapshot> --database <db> [--from-bucket] [--dry-run] [--yes]sudo moorhold backup restore <snapshot> --lake [--dry-run] [--yes]Puts one database, or SeaweedFS's data, back from a snapshot. It shows a plan and asks, stops the
apps and refuses unless they stopped, restores into a new place, swaps it in by renaming (the old
copy is kept) and starts the apps again. --from-bucket restores a database snapshot that is
already in the bucket the server used for backups; it doesn't send a new backup there.
backup restore-server
Section titled "backup restore-server"sudo moorhold backup restore-server --endpoint <https://host> --region <region> --bucket <bucket> [--path <path>] [--access-key-id-file <file>] [--secret-access-key-file <file>] [--repository-key-file <file>] [--replace-own-data] [--server-id <id>] [--dry-run] [--yes]On a new server, after losing the old one: brings back the old server's databases and secrets from
its backups in your bucket. It needs the old server's repository key, from a file of mode 0600 or
typed without echo. It restores beside this server's databases, swaps them in, starts the stack,
then takes a backup and a restore drill.
It refuses a server that holds data of its own (an admin password set, or sources of its own)
unless you give --replace-own-data. When the path holds more than one server's backups,
--server-id picks the one to recover. Needs root.
backup pre-upgrade
Section titled "backup pre-upgrade"sudo moorhold backup pre-upgrade <from-version> <to-version>Takes the rollback point an upgrade uses: every database and the roles, tagged with the two
releases, then restic check. It isn't a test restore. upgrade runs it for you.
backup drop-kept
Section titled "backup drop-kept"sudo moorhold backup drop-kept [<name>...] [--dry-run] [--yes]Lists the copies a rollback or a restore kept (<db>_old<time>, <db>_r<time>, and the lake's
.moorhold-before-restore-<time> folders), asks, and drops them, or only the ones you name. It never
drops a copy whose own database isn't beside it, or a lake folder from a restore that stopped
halfway.
restore
Section titled "restore"sudo moorhold restore <database> --into <new-database> [--snapshot <id>]sudo moorhold restore <database> --drillRestores a database into a new one, never over an existing one. With --drill, it backs the
database up, restores it into a scratch database, compares every table's row count and drops the
scratch database.
Access, people and mail
Section titled "Access, people and mail"access-key set
Section titled "access-key set"sudo moorhold access-key set [--access-key-file <path>] [--keep-access-key-file]Replaces the access key the server keeps, from a file of mode 0600 or typed in a terminal without
echo. The registry checks the new key first. If it refuses it, the kept key stays as it was. Needs
root.
access-key forget
Section titled "access-key forget"sudo moorhold access-key forgetDeletes the kept access key. On a server, the next upgrade or rerun of the installer asks for one. A local install needs none. Needs root.
users list
Section titled "users list"sudo moorhold users listThe portal's users, whether each is enabled, and their groups. Needs root.
users reset-password
Section titled "users reset-password"sudo moorhold users reset-password <username> [--password-file <path>] [--no-temporary] [--reset-sign-in]Sets a user's portal password, typed twice in a terminal without echo or read from a file of mode
0600. They choose a new one at their next sign-in, unless --no-temporary keeps the one you gave
them. --reset-sign-in also removes their authenticator app and recovery codes and ends their
sessions: they set up a new authenticator app at their next sign-in, and their passkeys still work.
Needs root.
mail password
Section titled "mail password"sudo moorhold mail passwordSets the password of the server's own mail settings. It reads it from standard input when you pipe
it in, or asks twice in a terminal without echo. The password is kept root-only, given to the
reconciler and the portal as file:///run/secrets/smtp-password, and sent to Keycloak on the
reconciler's next pass. Needs root.
sudo moorhold plansudo moorhold plan checkWith no -f: the server's plan, what it allows, and when it was last checked. plan check asks
account.moorhold.dev now, sending the kept access key and the server's version. Needs root, because
only root can read the key. plan -f is the dry run in Working with a store.
Sample data
Section titled "Sample data"sample-data add, sample-data remove
Section titled "sample-data add, sample-data remove"sudo moorhold sample-data addsudo moorhold sample-data removeadd loads Moorhold sample: AI Release Radar, a dated snapshot of public data (credited to Epoch AI,
under CC BY 4.0), as a ready-made source with its checks and marts, and starts its first load. remove
deletes the source, its tables and catalogue entries, its mock supplier and the files add wrote. It keeps the supplier's password file while another source still names it, and says so.
They use the profile the server runs unless you give --profile.
Network and relay
Section titled "Network and relay"relay init
Section titled "relay init"sudo moorhold relay init --provider hetzner|ionos [--hostname <name>] [--port <udp-port>]For a server whose network can't take its hostname (no NAT loopback, carrier-grade NAT, or ports
blocked). It makes the server's WireGuard key (mode 0600, kept on this server), chooses the
tunnel's addresses and writes the relay's cloud-init, which holds public keys only.
relay connect
Section titled "relay connect"sudo moorhold relay connect --endpoint <address[:port]> --relay-key <relay-public-key> [--profile full|core]Brings the tunnel up with wg-quick, declares the relay in the Stack (spec.public.relay),
restarts the front so it accepts the relay's PROXY protocol header, then runs the network check.
relay disconnect
Section titled "relay disconnect"sudo moorhold relay disconnect [--profile full|core]Takes the relay out of the Stack and the tunnel down.
relay check
Section titled "relay check"sudo moorhold relay check [--hostname <name>] [--public-address-url <https-url>]The network check on its own. Exits 1 when something's wrong.
Tools that sleep while idle
Section titled "Tools that sleep while idle"power setup
Section titled "power setup"sudo moorhold power setupFor tools named in the Stack's spec.public.sleepWhenIdle: makes the directory moorhold-wake
asks through and turns on moorhold-power.path. The next moorhold start mounts it. Needs root.
Installing
Section titled "Installing"install
Section titled "install"moorhold install --lock <file> --hostname <name> [--access-key-file <path>] [--profile full|core] [--acme production|staging] [--keep-access-key-file] [--sample-data | --no-sample-data] [--no-network-check] [--public-address-url <https-url>]What install.sh runs once it has checked the release's signature. You don't run it yourself. It
writes the Stack for the hostname, generates every secret (files of mode 0600, never printed),
pulls each image by digest with the access key, starts and applies the stack, and shows the
one-time setup code (on a terminal; otherwise where to read it) and the URL. It runs the network
check before the stack asks for its certificate, unless --no-network-check. A fresh install loads
the sample only with --sample-data. Installing again keeps what the server has. See the installer
reference for the options install.sh takes.
install --local
Section titled "install --local"moorhold install --local --lock <file> [--access-key-file <path>] [--no-sample-data]For one person, in a virtual machine on their own computer, as the Moorhold app for Mac installs it. It takes no hostname, makes no certificate and runs no network check. It runs the light profile, with each tool on 127.0.0.1 and the portal at http://127.0.0.1:47300. It needs no access key: it pulls Moorhold's images without a login unless you give a key or the install kept one. install.sh refuses --local on a server.
Working with a store
Section titled "Working with a store"These commands work on a store you name: --database-ref <secret-ref> (or the
MOORHOLD_DATABASE_URL_REF environment variable) for Postgres, otherwise --state <file>
(default .moorhold/state.json). They're for development and for running Moorhold outside an
installed server. Every command that reads -f also takes --profile. Use the same profile for
up, plan and apply.
validate
Section titled "validate"moorhold validate -f <dir|file>Parses and validates the resources and lists them.
plan -f
Section titled "plan -f"moorhold plan -f <dir|file>Shows what apply would change. Nothing is changed. Exits 1 if the plan has an error.
apply -f
Section titled "apply -f"moorhold apply -f <dir|file> [--wait <seconds>]Makes the store match the files, then reconciles proposals. The pass runs under the reconciler's
lease. While a running reconciler holds it, apply stores the files and waits, up to --wait
seconds (default 600), for that reconciler to reconcile them.
reconcile
Section titled "reconcile"moorhold reconcile [--every <seconds>] [--wait <seconds>]Reconciles what's stored, under the reconciler's lease as apply does. --every keeps running the
reconciler's loop, leader-elected on Postgres, until you stop it.
delete
Section titled "delete"moorhold delete <Kind/name> [--force] [--hard-catalog] [--wait <seconds>]Tears one resource down and forgets it. --force removes it even while dashboards or other objects
depend on it. --hard-catalog also removes its catalogued datasets and purges removed DAGs' run
history from Airflow. Without it, the delete is soft and those stay.
status with a store
Section titled "status with a store"moorhold status --database-ref <secret-ref>The store's resources and their conditions: Ready, Drifted, Degraded and
BlockedByDependents.
events
Section titled "events"moorhold events [<Kind/name>]The reconciler's event log.
export
Section titled "export"moorhold export [--kind <Kind>] [--out <file>]The desired state as YAML, so you can take your stack with you. It keeps labels and annotations,
except the one-shot safety annotations (moorhold.adopt, moorhold.force-delete,
moorhold.catalog-delete). It holds secret references only, never a value. --out writes a file of
mode 0600.
proposals
Section titled "proposals"moorhold proposals [list]moorhold proposals show <name>moorhold proposals approve|reject|withdraw <name> --as <user> --password-ref <secret-ref>Lists and shows change proposals. A decision needs a person's portal sign-in (--as and a secret
reference to their password), and the same rules apply as in the portal. The next reconcile pass
acts on it.
moorhold audit [--user <name>] [--since <time>]The audit log, from a Postgres store only. Component reads show the agent whose delegated token made them.
manifest check
Section titled "manifest check"moorhold manifest check [-f <dir|file>] [--manifest <file>]Validates the supported-versions manifest, runs the licence gate and, with -f, compares the
stack's components with it. Exits 1 when a check fails.
db migrate
Section titled "db migrate"moorhold db migrate --database-ref <secret-ref>Creates or upgrades the Postgres schema.
admin bootstrap, admin password, admin disable
Section titled "admin bootstrap, admin password, admin disable"moorhold admin bootstrap [--password-ref <secret-ref>]moorhold admin password [--password-ref <secret-ref>]moorhold admin disableThe portal's hidden break-glass local admin, on a Postgres store. bootstrap creates it once.
password rotates its password and prints it once. disable turns local-admin sign-in off and
ends its sessions.
render
Section titled "render"moorhold render -f <dir|file> -o <outdir> [--manifest <file>] [--no-portal] [--profile full|core]Renders the stack as a Docker Compose project. It holds no secret values: boot-secrets.json lists
the references to write at start-up.
moorhold up -f <dir|file> [-o <outdir>] [--manifest <file>] [--runtime-dir <dir>] [--allow-disk] [--no-portal] [--profile full|core]Renders the stack, writes its boot secrets to <runtime-dir>/secrets (a tmpfs, default
/run/moorhold) and starts it with Docker Compose. --allow-disk is for development machines
without a tmpfs. --no-portal leaves out Moorhold's own containers (the reconciler, collector,
portal MCP server and portal), for example to run them on the host.
moorhold down [-o <outdir>] [--volumes]Stops the stack and removes its boot secrets. --volumes also deletes its data.
Commands Moorhold runs itself
Section titled "Commands Moorhold runs itself"Moorhold's systemd units, and the reconciler's container, run these. You don't need to run them, and their output is meant for the command that calls them.
| Command | Run by |
|---|---|
upgrade --approved |
moorhold-requests.service, as the last step of requests run-due, when an admin approves an update in the portal. You can also run it by hand, as root. It checks each approved request again (the admins, the release it was asked from, its expiry), runs the pre-upgrade checks, then upgrades. The Updates page shows the outcome. |
upgrade --staged <release-directory> |
install.sh and upgrade, to hand over to the new release's CLI. |
requests run-due [--if-due] |
moorhold-requests.service, when an admin approves a request or an update in the portal, and moorhold-requests.timer with --if-due. It checks each approved request that's due again and does it, such as more memory for one app, then installs approved updates. |
memory sample |
moorhold-memory.timer. Samples the memory of the apps Moorhold sizes, for the portal's warning near the limit. |
power run |
moorhold-power.service. Starts or stops the sleeping tools moorhold-wake asked for. |
updates approved, updates record |
The update run (upgrade --approved, which moorhold-requests.service makes), inside the reconciler's container. |
requests approved, requests record, requests stored |
requests run-due, inside the reconciler's container. |
upgrade approvals, upgrade offer, upgrade record, upgrade record-grant |
upgrade, inside the reconciler's container. |
users record-reset, mail record-password |
users reset-password and mail password, inside the reconciler's container. |
backup own-data |
backup restore-server, inside the reconciler's container. |