CLI reference

Single binary: momo. Exit codes: 0 success, 1 operational/validation error, 2 usage error. Success JSON includes schema_version: "momo.cli.v1".

Global patterns:

• --store / MOMO_STORE — desired-state URI:
  • file://./momo-state — local single-process development
  • sqlite://./momo.db — single-host multi-process
  • postgres://… / postgresql://… — multi-host production
• --output text|json — human vs machine output
• MOMO_ACTOR — audit actor (defaults to $USER)

Process modes

Foreground momo gateway|node|edge is the only form used by Docker and systemd/launchd ExecStart. For local detach and OS service wrappers, see Lifecycle below.

momo gateway

Run the HTTP gateway (route watch, node pool, proxy).

Flag / env	Purpose
--config	Optional YAML config path
--store / MOMO_STORE	Store URI (file://, sqlite://, or postgres://; required)
--bind / MOMO_GATEWAY_BIND	HTTP listen (default 127.0.0.1:8080)
--auth-token / MOMO_AUTH_TOKEN	Node RPC shared secret
--log-format / MOMO_LOG_FORMAT	text or json

momo edge

Optional public front door (Pingora). Terminates TLS and forwards HTTP/WebSocket to the gateway over plain HTTP. Host routing stays in the gateway.

Precedence: CLI flags override env; env overrides defaults.

Flag / env	Purpose
--tls-listen / MOMO_EDGE_TLS_LISTEN	HTTPS listen (e.g. 0.0.0.0:443)
--http-listen / MOMO_EDGE_HTTP_LISTEN	HTTP listen (e.g. 0.0.0.0:80)
--upstream / MOMO_EDGE_UPSTREAM	Gateway host:port (repeatable / comma-separated; default 127.0.0.1:8080)
--tls-cert / MOMO_EDGE_TLS_CERT	Static PEM certificate
--tls-key / MOMO_EDGE_TLS_KEY	Static PEM private key
--http-mode / MOMO_EDGE_HTTP_MODE	redirect (default with TLS) or proxy
--acme-domain / MOMO_EDGE_ACME_DOMAINS	Domain(s); presence enables Let’s Encrypt HTTP-01
--acme-email / MOMO_EDGE_ACME_EMAIL	ACME contact email (recommended)
--acme-dir / MOMO_EDGE_ACME_DIR	Persist account/certs (default /var/lib/momo/acme)
--acme-staging / MOMO_EDGE_ACME_STAGING	Use Let’s Encrypt staging
--acme-renew-days / MOMO_EDGE_ACME_RENEW_DAYS	Renew when within N days of expiry (default 30)
--acme-fail-fast	Exit if initial issuance fails (default: retry)
--log-format / MOMO_LOG_FORMAT	text or json

ACME is mutually exclusive with --tls-cert/--tls-key. Public binds require MOMO_ALLOW_PUBLIC_BIND=1. See Production and Security.

momo node

Run a node reconciler, or manage the node registry via subcommands.

Run (no subcommand): --node-id, --store, --docker-host, --bind, --metrics-bind, --reconcile-interval, --auth-token, --auto-register, --advertise-addr, idle/startup timeouts, --log-format.

Subcommands:

Command	Purpose
node link	Register node in ClusterSpec
node drain	Block new placements
node undrain	Allow placements again
node unlink	Remove from ClusterSpec (--force orphans apps)

Lifecycle (local detach + OS services)

Two equal control planes. Never put momo start in systemd/Docker — those must run foreground momo <role>.

Local detach (laptop / quick stacks)

Pid and log files live under $MOMO_RUNTIME_DIR (default ~/.local/share/momo/runtime).

Command	Purpose
momo start gateway|node|edge [flags…]	Spawn detached child; wait until ready
momo start all	Start node → gateway (edge if listen flags set)
momo stop <role>|--all	SIGTERM via pidfile
momo logs <role> [-f] [--tail N]	Tail role log file
momo ps	List detached roles

Example:

export MOMO_RUNTIME_DIR=./.momo-runtime
momo start node --node-id node-a --store file://./momo-state --auto-register
momo start gateway --store file://./momo-state --bind 127.0.0.1:8080
momo ps
momo logs gateway -f
momo stop --all

OS services (systemd / launchd)

Command	Purpose
momo service install [--role …|--all] [--user] [--dry-run]	Install units/plists
momo service uninstall|start|stop|restart|status|logs	Delegate to OS manager

Linux uses the templates under deploy/systemd/ (Type=simple, foreground ExecStart). macOS installs LaunchAgents/Daemons that exec the same foreground commands. Package path remains sudo make install-systemd.

momo service install --all --dry-run --output json   # preview
sudo momo service install --all
sudo momo service start --all
momo service logs --role gateway -f

When to use what

Situation	Tool
Debug in a terminal	momo gateway|node|edge (foreground)
Local multi-role without extra terminals	momo start / stop / logs / ps
Production Linux host	systemd units or momo service …
Compose lab	docker compose -f deploy/docker-compose.momo.yml up -d

Cluster/app stats remain momo status / momo nodes; process metrics are at gateway and node /metrics.

Desired-state operators

Command	Purpose
apply -f app.yml [--node] [--dry-run] [--diff] [--wait]	Upsert app + HostSpec/routes
remove <app-id> [--drain-timeout] [--force] [--dry-run]	Delete app after drain
validate -f app.yml	Schema + policy check (no write)
diff -f app.yml [--node]	Planned changes vs store
status [--node] [--app]	Cluster / node / app status
inspect <app-id>	Detailed desired + observed view
routes	List RouteSpecs
nodes	List linked nodes + availability
doctor [--gateway-url]	Store, Docker, production posture, local detach
export [-o file] [--format yaml|json]	Backup full desired state
import -f file [--dry-run]	Replace desired state from backup
skill [topic]	AI agent skill instructions (catalog / topic)

AI agent skills

momo skill exposes progressive-disclosure instructions for AI agents:

momo skill                     # catalog (name + description)
momo skill --list --output json
momo skill momo                # main overview
momo skill cli|appspec|ops|production|coding

Topics ship inside the binary (see crates/momo-cli/skills/momo/). Prefer --output json when an agent consumes the payload.

Export / import

momo export --store "$MOMO_STORE" -o backup.yaml
momo import -f backup.yaml --store "$MOMO_STORE" --dry-run
momo import -f backup.yaml --store "$MOMO_STORE"

Wire format: apiVersion: momo.dev/v1, kind: StoreSnapshot with cluster, apps, hosts. Treat exports as secrets if AppSpecs contain credentials.

Help

momo --help
momo <command> --help
momo skill              # AI agent skill catalog
momo skill momo|cli|appspec|ops|production|coding