CLI Reference

This page documents the command-line tools used to manage, monitor, and maintain a Sanctum instance. Every command here has been typed in anger at least once during a production incident. They work.

Caution

Beta tester? You want the sanctum binary, not this page. This reference covers sanctumctl and the raw scripts, which only exist in the checked-out source tree — a brew-installed Sanctum does not ship them. If you installed Sanctum the normal way (brew install), the command you have is sanctum, documented at the Sanctum CLI reference. The page below is scoped to operators running from the source tree — typically because they’re hacking on the renderer or running the release gate — same audience as the operator-grade install appendix.

---

sanctumctl

sanctumctl is the checked-in operator surface for bootstrapping, rendering, verifying, and doctoring a Sanctum instance. Use it first. Drop to the raw scripts only when you are debugging a specific subsystem.

python3 tools/sanctumctl.py <subcommand>

bootstrap

Creates the local ~/.sanctum scaffold from the checked-in example configuration.

# Preview only
python3 tools/sanctumctl.py bootstrap

# Write the scaffold
python3 tools/sanctumctl.py bootstrap --write

Flag	Description
--home <path>	Target an alternate home directory, useful for test runs
--write	Materialize the scaffold instead of printing the plan
--force	Recopy instance.yaml and .node_id even if they already exist

render

Checks or syncs the canonical generated artifacts:

• checked-in workspace manifests
• runtime manifests in ~/.sanctum/services
• runtime agent capabilities
• runtime calibration byproducts

# Verify generated surfaces are current
python3 tools/sanctumctl.py render --check

verify

Runs the audited Sanctum proof wall.

python3 tools/sanctumctl.py verify

# Print the exact audit plan without executing it
python3 tools/sanctumctl.py verify --dry-run

Today that executes the workspace audit, runtime audit, and system end-to-end suites directly, so the operator entry point and the test wall stay coupled.

doctor

Runs render checks, the feature matrix audit, and optionally the full verification wall.

# Fast local confidence check
python3 tools/sanctumctl.py doctor --quick

# Full doctor pass
python3 tools/sanctumctl.py doctor

The quick pass now includes:

• generated runtime surface checks
• agent markdown drift checks
• a live MBP calibration audit
• the feature matrix audit
• Kitchen Loop source validation

It is the closest thing Sanctum has to a morning roll call. If it fails, something real drifted.

sync-agents

Installs the local helper, pushes canonical markdown and helper scripts, then audits the reachable fanout targets.

# Apply the full sync and audit pass
python3 tools/sanctumctl.py sync-agents

# Preview the exact steps first
python3 tools/sanctumctl.py sync-agents --dry-run

The sync writes machine-readable state to:

~/.sanctum/state/agent-markdown-sync.json

On the Mac Mini, this command treats the local machine as the authority and fans out to the VM and MBP when they are reachable. On the MBP, the installed helper runs in fanout-target-only mode when ~/.sanctum/instance.yaml is absent, which is a polite way of saying “thank you for receiving the update; please do not start a theological schism.”

stability

Manages the one-week soak gate before Phase 2 resumes.

# Start the seven-day stabilization window
python3 tools/sanctumctl.py stability start

# Check how much time is left
python3 tools/sanctumctl.py stability status

# Run the final exit gate after the window matures
python3 tools/sanctumctl.py stability check

The policy is checked into sanctum/stability_window.yaml and currently requires:

• sanctumctl.py doctor --quick
• sanctumctl.py verify
• pnpm build in sanctum-docs

---

Gateway Management

The OpenClaw gateway is the core agent runtime — the brain stem of the whole operation. Always use the openclaw CLI to manage it. Never use raw launchctl commands for the gateway.

Danger

Seriously. Raw launchctl skips state cleanup and port lock management. Use openclaw gateway start/stop. This is not a suggestion. This is the voice of experience, and experience has scars.

Start the Gateway

openclaw gateway start

Loads the gateway LaunchAgent and starts the agent runtime on the configured port (default 1977).

Stop the Gateway

openclaw gateway stop

Gracefully shuts down the gateway, cleans up state files and port locks, then unloads the LaunchAgent.

Caution

On the VM, use systemd instead:

systemctl --user restart openclaw-gateway.service

Restart Pattern

# Mac
openclaw gateway stop
openclaw gateway start

# VM
systemctl --user restart openclaw-gateway.service

There is no restart wrapper on purpose. Stop, then start — two commands so you always know which half failed.

---

Agent Commands

Send a Message to an Agent

openclaw agent --agent <agent_name> --message "<message>"

Flag	Description
--agent	Agent identifier: main (Yoda), windu, quigon, cilghal, mundi, or jocasta
--message	The message to deliver to the agent

# Send a message to the main agent (Yoda)
openclaw agent --agent main --message "Run the evening briefing"

# Send a message to the security agent
openclaw agent --agent windu --message "Generate the weekly security report"

Yes, you’re sending text messages to named AI agents running on a Mac Mini. This is your life now.

Cross-Node Agent Messaging

For sending messages between Mac and VM agents, use the council bridge SSH pattern:

Mac to VM

ssh ubuntu@10.0.0.10 \
  '/home/ubuntu/.npm-global/bin/openclaw agent --agent main --message "Hello from Jocasta"'

VM to Mac

ssh neo@10.0.0.1 \
  'PATH=/Users/neo/.local/share/fnm/node-versions/v22.22.0/installation/bin:/opt/homebrew/bin:$PATH \
   openclaw agent --agent main --message "Hello from Yoda"'

Note

The VM-to-Mac path requires a PATH prefix because fnm-managed Node.js is not in the default SSH PATH. This is the kind of thing that takes two hours to debug and two seconds to fix. The PATH prefix is the two-second fix.

---

launchctl Patterns

macOS uses launchctl to manage LaunchAgents and LaunchDaemons. Sanctum uses the modern bootstrap/bootout subcommands, because Apple deprecated the old load/unload commands and then kept them working anyway, which is the most Apple thing imaginable.

Load a LaunchAgent

launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/<label>.plist

# Example: load the council MLX server
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.sanctum.mlx.plist

Unload a LaunchAgent

launchctl bootout gui/$(id -u) ~/Library/LaunchAgents/<label>.plist

# Example: unload the council MLX server
launchctl bootout gui/$(id -u) ~/Library/LaunchAgents/com.sanctum.mlx.plist

Check Agent Status

launchctl print gui/$(id -u)/<label>

# Example: check if the council MLX server is running
launchctl print gui/$(id -u)/com.sanctum.mlx

Load a LaunchDaemon

LaunchDaemons require sudo and use the system domain:

sudo launchctl bootstrap system /Library/LaunchDaemons/<label>.plist
sudo launchctl bootout system /Library/LaunchDaemons/<label>.plist

---

generate-plists.sh

Renders LaunchAgent plist files from templates using values from instance.yaml and the macOS Keychain. The bridge between your clean YAML config and the XML format that Apple chose specifically to test human patience.

~/.sanctum/generate-plists.sh [--dry-run]

Flag	Description
--dry-run	Show what would be generated without writing any files

What It Does

1. Reads templates from ~/.sanctum/templates/launchagents/
2. Checks each template’s corresponding service enabled flag in instance.yaml
3. Skips disabled services
4. Expands {{PLACEHOLDER}} tokens with config values
5. Retrieves secrets from the macOS Keychain using the configured keychain_account
6. Writes rendered plists to ~/Library/LaunchAgents/ (user agents only — LaunchDaemons are installed by a separate, sudo-gated path)

# Preview changes
~/.sanctum/generate-plists.sh --dry-run

# Generate and install
~/.sanctum/generate-plists.sh

Tip

Always --dry-run first. Trust, but verify. Especially when the output is XML that macOS will silently reject if you look at it wrong.

---

run-all.sh (Test Suite)

The master test runner. It does not probe ports itself — it runs every other suite and tallies the results.

~/.sanctum/tests/run-all.sh [--quiet]

It runs five families of suites, in order:

Family	What it covers
Config	config.sh and config.ts library parity (same instance.yaml, two languages)
Infrastructure	LaunchAgent validation, instance.yaml schema, cron jobs, model scout
Connections	HA (localhost / LAN / Tailscale / Cloudflare), VM SSH, health ingester, tunnel, keychain
Skills	per-skill test scripts under openclaw-skills/
Dashboards	Command Center and Health Center vitest suites

Bash suites and vitest suites get their pass/fail/skip counts parsed and rolled up into one summary:

╔══════════════════════════════════════════╗
║             FINAL SUMMARY                ║
╚══════════════════════════════════════════╝

  Suites:  9 pass, 1 fail (of 10)
  Tests:   142 pass, 0 fail, 3 skip (of 145)

  Failed suites:
    - Connections

  Status: FAILURES DETECTED

That one failed suite is usually Connections, and it is usually the external drive — HA can’t see the media library because the drive isn’t plugged in. It’s always the external drive.

---

Watchdog

The watchdog is no longer a shell script on a timer — it is a long-running Rust daemon (sanctum-watchdog, built into the unified sanctumd binary) managed by the com.sanctum.watchdog LaunchAgent with KeepAlive, so launchd respawns it if it ever dies. It monitors all enabled services and attempts auto-healing via service-doctor. It’s the night shift security guard of your infrastructure — mostly bored, occasionally essential, and now on the payroll full-time instead of clocking in every ten minutes.

It exposes a status API on 127.0.0.1:2187 and logs to ~/.openclaw/logs/watchdog-rust.log.

Behavior

1. Iterates through all services with enabled: true in instance.yaml
2. Checks each service’s health (port check, process check, or custom probe)
3. If a service is unhealthy, invokes service-doctor to attempt recovery
4. Logs all results to ~/.openclaw/logs/watchdog-rust.log
5. Sends a notification via sanctum_notify if any service required healing

Check Current Health

The daemon answers over its API rather than being re-run by hand:

curl -s http://127.0.0.1:2187/health | jq .

---

sanctum-backup.sh

Backs up the Sanctum configuration and critical state via restic — content-addressed, client-side encrypted, deduplicated. It replaced an rsync-to-iCloud scheme that ate 356 GB of SSD by re-copying everything in full every single day. Dedup is not a luxury here; it’s the difference between a backup and a slow disk-full incident.

~/Backups/sanctum-backup.sh

It writes to two restic repositories, both encrypted with a passphrase stored in the Keychain (sanctum-backup-key):

Repo	Role
/Volumes/T9/sanctum-restic	Primary — fast local disk, full history
rclone:gdrive-sanctum:sanctum-restic	Cloud — offsite, encrypted before it leaves the Mac

Each run only ships changed blocks (typical delta: tens of MB), then enforces GFS retention with restic forget --prune (7 daily / 4 weekly / 12 monthly). On full success it beats an off-box dead-man’s-switch on GitHub, so an overdue backup pages even if this Mac, launchd, and Force Flow are all dead. There is no --destination flag — the two repos are the design, not a default to override.

The full operational playbook lives in Backup & Restore.

---

sanctum-restore.sh

The undo button for your entire haus infrastructure.

~/Backups/sanctum-restore.sh [YYYY-MM-DD]

Argument	Description
YYYY-MM-DD	Which dated snapshot to restore. Omit it to take the latest.

# Restore the most recent snapshot
~/Backups/sanctum-restore.sh

# Restore a specific day
~/Backups/sanctum-restore.sh 2026-03-19

The script previews the source, prompts before it overwrites anything, then restores the configs in place.

Caution

Restore does not automatically reload LaunchAgents. After a restore, you should either reboot or manually reload affected services via launchctl. The restore script puts everything in place. Getting macOS to acknowledge the new files is a separate negotiation.

---

Quick Reference

Command	Purpose
openclaw gateway start	Start the Mac gateway
openclaw gateway stop	Stop the Mac gateway
openclaw agent --agent main --message "..."	Send a message to an agent
~/.sanctum/generate-plists.sh	Regenerate all LaunchAgent plists
~/.sanctum/generate-plists.sh --dry-run	Preview plist generation
~/.sanctum/tests/run-all.sh	Run the full test suite
curl -s http://127.0.0.1:2187/health	Query the watchdog daemon’s health
~/Backups/sanctum-backup.sh	Run the restic backup
~/Backups/sanctum-restore.sh [YYYY-MM-DD]	Restore from a dated snapshot
launchctl bootstrap gui/$(id -u) <plist>	Load a LaunchAgent
launchctl bootout gui/$(id -u) <plist>	Unload a LaunchAgent
launchctl print gui/$(id -u)/<label>	Check agent status
systemctl --user restart openclaw-gateway.service	Restart VM gateway