Command reference

Run maand from the bucket root (the directory created by maand init). Use maand <hook> --help for flags.

Configuration files: configuration.md · KV: KV persistence · Templates: templates.md

Workflow commands

Inspect commands

Job control

Manual lifecycle on workers (requires prior deploy; validates worker.json / update_seq).

Common flags: --allocations ip,..., --health_check (start/stop/restart/run).

Hooks (hooks & CLI)

Flags: --verbose. Batch width follows max_concurrent_upgrades in each job manifest.

The same commands run automatically on events: post_build, pre_deploy, post_deploy, job_control, health_check.

Ad-hoc worker shell

Flags for collect facts: --workers, --labels, --concurrency, --generate-workers, --ignore-failure.

Flags for run_command: --workers, --labels, --concurrency, --health_check.

maand init

maand init

Creates (first run) or upgrades (later runs):

• data/maand.db with schema migrations
• workspace/workers.json (empty []), workspace/jobs/, workspace/bucket.conf
• maand.conf defaults — see configuration.md
• Bucket CA in secrets/ca.crt / ca.key
• KV encryption key secrets/kv.key
• tmp/ and logs/ directories

Does not contact workers. Re-running maand init on an existing bucket applies schema upgrades without changing bucket_id or the CA.

Other commands check the database schema before running. If the binary is newer than maand.db, they fail with a hint to run maand init.

maand build

maand build [--purge-secrets-kv]

Reconciles the entire workspace. No filters. Validates job demands and version constraints. See build.md.

Host prerequisites: python3, bun (if TS/JS commands), for post_build hooks.

maand deploy

maand deploy [--build] [--jobs j1,j2] [--dry-run] [--force] [--sync-only]

After rsync, deploy applies restart_policy (always → make restart, reload → make reload, never → files only). See deploy.md.

Host prerequisites: bash, ssh, rsync, python3, optional bun.
Worker prerequisites: python3, make, rsync, bash, timeout, optional sudo.

See deploy.md.

maand job

maand job start|stop|restart|status <job> [--allocations ip,...] [--health_check]
maand job run <job> --target start|stop|restart|reload|<make-target> [--allocations ip,...] [--health_check]
maand job create <job> [--selectors s1,s2]

See job.md.

maand hooks

maand hooks <hook_name> [job] [--verbose]

Omit job to run on every catalog job that defines the command for cli. Batch width follows each job’s max_concurrent_upgrades.

Command must include cli in manifest executed_on. Script: workspace/jobs/<job>/_hooks/hook_<name>.py (or .ts/.js).

Host prerequisites: python3 or job venv; bun for TS/JS.

See hooks.md and hook-api.md.

maand health_check

maand health_check [--jobs j1,j2] [--wait] [--verbose]

See health-check.md.

maand run_command

maand run_command "<hook>" [-w ip,...] [-l label,...] [-c N] [--health_check]

Host prerequisites: bash, ssh.
Worker prerequisites: bash, timeout, optional sudo.

See run-command.md.

maand collect

maand collect facts [-w ip,...] [-l label,...] [-c N] [--generate-workers] [--ignore-failure]
maand collect uptime [-w ip,...] [-l label,...] [-c N] [--ignore-failure]

Host prerequisites: bash, ssh.
Worker prerequisites: Linux, bash, timeout, optional sudo (facts also needs /proc/meminfo).

Use collect facts to print discovered memory / cpu. With --generate-workers, redirect stdout to update workspace/workers.json, then run maand build.

See collect.md.

maand gc

maand gc [--retain-days N]

See gc.md.

maand info and maand cat

maand info
maand cat workers
maand cat jobs
maand cat allocations [--jobs api] [--workers 10.0.0.1]
maand cat deployments [--jobs vault] [--workers 10.0.0.1]
maand cat hooks
maand cat ports
maand cat certs [--jobs api] [--workers 10.0.0.1]
maand cat prometheus [--jobs j1,j2]
maand cat prometheus get <job> <path>
maand cat prometheus scrape [--jobs j1,j2]
maand cat kv
maand cat kv --jobs vault
maand cat kv --jobs vault --active
maand cat kv --deleted
maand cat kv get maand/job/api job_name
maand cat kv get --reveal secrets/job/vault root_token

See info.md.

maand cat deployments

maand cat deployments [--jobs j1,j2] [--workers ip,...] [--active]

Shows current_hash, previous_hash, current_version, new_version, post_deploy_status, and rollout state per allocation. Rollout is removed, disabled, or disabled_restart when the allocation flag applies; otherwise hash/version state (new, restart, promoted, health_failed). post_deploy_status is - when unset, or pending / success / failed when the job has post_deploy hooks. deploy clears hash rows for removed allocations. See deploy.md and debugging-deploy.md.

maand cat certs

maand cat certs [--jobs j1,j2] [--workers ip,...]

Lists the bucket CA (secrets/ca.crt) and job leaf certificates from KV with common name, not_after, days_left, and status (ok, expiring, expired, invalid). Uses certs_renewal_buffer from maand.conf for the expiring window (CA and leaf). maand build prints a stderr warning for an expiring or invalid CA and fails when the CA is expired. See certs.md.

maand cat kv

maand cat kv [--jobs j1,j2] [--active] [--deleted]

With --jobs, lists every KV namespace the job can read: shared maand/bucket and vars/bucket, each allocated worker's maand/worker/<ip> and tags, job/allocation namespaces, and upstream jobs referenced in command demands.

Recommended command order

maand init
# edit workspace
maand build
maand deploy              # or: maand deploy -b
maand health_check        # optional
# day-2: maand job *, maand hook, maand collect facts, maand run_command, maand gc

Operations: disable and drain, rolling-deploy, debugging-deploy.md.

Tutorials: quickstart.md, day-2-ops.md.