Monarch CLI Reference
Monarch CLI is a Go-based node management tool for Monolythium. It replaces the deprecated Mono Commander and provides complete lifecycle management for validator nodes, full nodes, seed nodes, and sentry nodes. Built with the Cobra framework, Monarch delegates process management to OxidePM for auto-restart, health checks, and relay-until-synced logic.
Installation
curl -fsSL https://raw.githubusercontent.com/monolythium/monarch-cli/prod/scripts/install.sh | bash
This installs both monarch and the OxidePM process manager.
Supported Networks
| Network | Cosmos Chain ID | EVM Chain ID |
|---|---|---|
| Localnet | (custom) | (custom) |
| Testnet | mono_6940-1 | 6940 |
| Mainnet | mono_6941-1 | 6941 |
Global Flags
| Flag | Default | Description |
|---|---|---|
--home | ~/.mono | Node home directory |
--network | — | Target network: Testnet, Mainnet, or Localnet |
--json | false | Output results as JSON |
--password | — | Keyring password (for non-interactive mode) |
--yes, -y | false | Skip confirmation prompts |
--dry-run | false | Preview changes without applying them |
Command Reference
Node Lifecycle
monarch join
Full node setup in a single command. Downloads genesis, validates SHA256, initializes the node, fetches peers, configures sync mode, generates an OxidePM config, and starts the node.
monarch join --network Testnet --validator --moniker my-node
| Flag | Description |
|---|---|
--network | Target network (required) |
--validator | Join as validator node |
--sentry | Join as sentry node |
--seed | Join as seed node |
--archive | Join as archive node |
--moniker | Node moniker/name |
--sync-mode | Sync strategy: full, snapshot, state-sync |
monarch start
Start the node process via OxidePM.
monarch start [name]
monarch stop
Stop the node process. If the node is a validator, it will stop signing blocks.
monarch stop [name]
monarch restart
Restart the node process.
monarch restart [name]
monarch status
Display sync status, current block height, connected peers, and validator information.
monarch status
monarch status --json
monarch init
Initialize the node home directory. One-time operation.
monarch init
monarch init --force # Re-initialize (DANGER: overwrites existing config)
monarch first-time
Step-by-step guide for new operators. Covers validator costs, risks (downtime slashing, double-signing, key loss), responsibilities, setup steps, and command safety levels.
monarch first-time
monarch logs
View node logs with filtering options.
monarch logs
monarch logs --follow
monarch logs --level error
monarch logs --clear
| Flag | Description |
|---|---|
--follow | Stream logs in real-time |
--level | Filter by log level (info, warn, error) |
--clear | Clear log history |
monarch logs-configure
Configure OxidePM log rotation settings.
monarch logs-configure --max-size 50 # Max size in MB per log file
monarch logs-configure --max-files 10 # Number of rotated files to keep
monarch logs-configure --compress # Compress rotated logs
monarch logs-configure --show # Show current settings
Health and Monitoring
monarch doctor
Run a full 13-category health audit of your node. Categories include: system, directories, binaries, genesis, config drift, P2P, ports, sync, process, disk, network, security, and validator.
monarch doctor
Each category reports pass, warn, or fail status with actionable recommendations.
monarch repair
Fix issues identified by monarch doctor. Use --dry-run to preview changes before applying them.
monarch repair
monarch repair --dry-run
monarch monit
Live process monitoring dashboard in your terminal.
monarch monit
monarch top
Real-time resource monitor showing CPU, memory, disk, and network usage.
monarch top
Validator Operations
monarch validator setup
Guided 5-step validator setup wizard. Walks you through key creation, funding, registration, and verification.
monarch validator setup
monarch validator register
Register as a validator on-chain. Requires 200,000 LYTH (100,000 LYTH burn + 100,000 LYTH minimum self-delegation).
monarch validator register \
--from my-key \
--moniker my-validator \
--amount 100000000000000000000000alyth \
--commission-rate 0.10
| Flag | Required | Description |
|---|---|---|
--from | Yes | Key name to sign with |
--moniker | Yes | Validator display name |
--amount | Yes | Self-delegation amount in alyth |
--commission-rate | No | Commission rate (default: 0.10) |
--website | No | Validator website |
--details | No | Validator description |
--identity | No | Keybase identity for avatar |
monarch validator edit
Edit validator information after registration.
monarch validator edit --from my-key --moniker new-name --commission-rate 0.08
monarch validator unjail
Unjail a validator after downtime. Check missed blocks before unjailing.
monarch validator unjail --from my-key
monarch validator status
Show detailed validator information including rank, tokens, commission, jailed status, and missed blocks.
monarch validator status
Key Management
Account Keys
Account keys use secp256k1 and BIP39 mnemonics.
# Create a new account key (mnemonic shown once — write it down!)
monarch keys account create my-key
# Recover from mnemonic
monarch keys account recover my-key
# List all account keys
monarch keys account list
# Show key details (mono1... and 0x... addresses)
monarch keys account show my-key
# Delete a key (DANGER: irreversible)
monarch keys account delete my-key
Validator Keys
Validator keys use ed25519 for consensus signing.
# Generate a new validator key
monarch keys validator create
# Export validator key (encrypted with AES-256-GCM)
monarch keys validator export
# Import a validator key from file
monarch keys validator import /path/to/key.json
Never run two validators with the same validator key. Double-signing results in permanent slashing. See the Security Guide for safe migration procedures.
Staking and Governance
Staking
# Delegate LYTH to a validator
monarch stake delegate monovaloper1... 1000000000000000000000alyth --from my-key
# Unbond LYTH (3-day unbonding period)
monarch stake unbond monovaloper1... 500000000000000000000alyth --from my-key
# Redelegate from one validator to another
monarch stake redelegate monovaloper1... monovaloper2... 500000000000000000000alyth --from my-key
# Withdraw staking rewards
monarch rewards --from my-key
monarch rewards --from my-key --all # Withdraw from all validators
Governance
# List active proposals
monarch gov list
# Vote on a proposal
monarch gov vote 1 yes --from my-key
# Submit a new proposal
monarch gov submit --from my-key --proposal proposal.json --deposit 10000000000000000000000alyth
# Deposit to an existing proposal
monarch gov deposit 1 5000000000000000000000alyth --from my-key
Vote options: yes, no, abstain, veto.
Metrics
# Enable time-series collection (cron job, every 60 seconds, ~42KB/day)
monarch metrics enable
# Disable collection
monarch metrics disable
# Query collected metrics
monarch metrics query --since 1711756800 --limit 500 --json
# Query detected events
monarch metrics events --since 1711756800 --limit 100 --json
# Check collection status
monarch metrics status
See Node Metrics for a deep dive on collected fields, event types, and storage.
Maintenance
Upgrades
# Upgrade monod binary to a specific version
monarch upgrade --version v0.2.0
# Update monarch and oxidepm themselves
monarch upgrade self
Binary Installation
# Install all dependencies (monod + oxidepm)
monarch install
# Install monod only
monarch install-monod --version v0.2.0
# Install OxidePM only
monarch install-oxidepm --version v1.0.0
Backup and Restore
# Backup all keys
monarch backup keys
# Restore keys from a backup directory
monarch backup restore /path/to/backup
Node Maintenance
# Wipe chain data (preserves keys by default)
monarch wipe --preserve-keys
# Wipe everything including keys (DANGER)
monarch wipe --purge-keys
# Enable auto-start on server reboot
monarch enable-boot
# Disable auto-start
monarch disable-boot
# Migrate from systemd to OxidePM
monarch migrate
# Apply server security hardening
monarch harden
Networking
# Refresh peers from the peer registry
monarch peers update
# Check connectivity to a specific peer
monarch peers validate 561c4313fa36aa568ce51d13c66f326192c48b41@159.69.176.32:26656
# Manage service exposure
monarch expose --list # List exposed services
monarch expose --enable rpc # Enable RPC exposure
monarch expose --disable rpc # Disable RPC exposure
monarch expose --domain rpc.mynode.com # Set custom domain
# Print recommended UFW firewall rules
monarch firewall
# Sentry architecture management
monarch sentry init # Initialize sentry setup
monarch sentry add # Add a sentry node
monarch sentry remove # Remove a sentry node
monarch sentry status # Check sentry status
IBC
Transfer tokens across IBC channels.
monarch ibc transfer \
--from my-key \
--channel channel-0 \
--receiver cosmos1... \
--amount 1000000000000000000000alyth \
--denom alyth
Other Commands
# Environment variable management
monarch env list
monarch env set KEY=value
monarch env unset KEY
# Notification alerts
monarch notify setup # Configure alert destinations
monarch notify test # Send a test notification
monarch notify status # Check notification config
# Opt-in network monitoring
monarch monitor register # Register with monitoring service
monarch monitor heartbeat # Send a single heartbeat
monarch monitor install # Install automatic heartbeat timer
# Show supported networks
monarch networks
# Print version
monarch version
# Export genesis state
monarch genesis export --height 1000000
Safety Levels
Every command in Monarch CLI is categorized by its safety level:
| Level | Description | Commands |
|---|---|---|
| SAFE | Read-only operations, no state changes | status, doctor, logs, version, networks, keys account list, keys account show, gov list, metrics query, metrics events, metrics status, monit, top, validator status, firewall |
| CAREFUL | State-modifying with confirmation prompts | start, stop, restart, join, upgrade, repair, validator setup, validator edit, validator unjail, gov vote, gov submit, gov deposit, stake delegate, stake unbond, stake redelegate, rewards, enable-boot, disable-boot, metrics enable, metrics disable, peers update, harden, migrate |
| DANGER | Irreversible actions requiring explicit confirmation | init --force, keys account create, keys account recover, keys account delete, keys validator create, keys validator export, keys validator import, wipe --purge-keys, validator register, backup keys |
DANGER-level commands always ask for explicit confirmation and cannot be skipped with --yes for destructive key operations.
Non-Interactive Mode
All commands support non-interactive execution for automation and scripting:
# Join testnet without prompts
monarch join --network Testnet --validator --moniker my-node --yes
# Provide password for key operations
monarch validator register --from my-key --moniker my-node \
--amount 100000000000000000000000alyth --password "$(cat /secure/password)" --yes
Combine --yes and --json for CI/CD pipelines.
Process Manager
Monarch delegates process management to OxidePM rather than systemd. OxidePM provides:
- Auto-restart on crash with configurable backoff
- Health checks against the local RPC endpoint
- Relay-until-synced logic for validators (waits until the node is fully synced before enabling signing)
- Log management with rotation and retention
To migrate an existing systemd-managed node to OxidePM:
monarch migrate
Related
- Monarch Connect -- Desktop GUI for managing nodes
- Node Metrics -- Detailed metrics reference
- Security Guide -- Key management and hardening
- Validator Operations -- Full validator lifecycle guide
- Troubleshooting -- Common issues and fixes