nx9-wg/docs/cli.md

Native CLI Command Reference (nx9-wg)

The nx9-wg binary provides 100% native CLI coverage across all 17 application subcommands without spawning external subprocesses.

---

1. Global Options

Option	Environment Variable	Description
-c, --config <PATH>	NX9_WG_CONFIG	Path to configuration file (default: /etc/nx9-wg/config.toml)
-d, --data-dir <PATH>	NX9_WG_DATA_DIR	Path to data directory (default: /var/lib/nx9-wg)
--database <PATH>	NX9_WG_DATABASE	Specific SQLite database file path or URL
--format <FORMAT>	N/A	Output format (table, json, yaml, csv, default: table)
--json	N/A	Convenience flag for strict JSON output
-q, --quiet	N/A	Suppress status and conversational messages
-v, --verbose	N/A	Enable verbose trace logging
--log-level <LEVEL>	NX9_WG_LOG_LEVEL	Log verbosity level (trace, debug, info, warn, error)

---

2. Command Groups Reference

1. version

Displays version, build edition, architecture, OS platform, and security flags.

nx9-wg version
nx9-wg version --format json

2. serve

Starts the Axum REST API daemon, WebSocket streamer, and background reconciliation scheduler.

nx9-wg serve
nx9-wg serve --bind 0.0.0.0:8080

3. init

Initializes the single administrator account across 7 bootstrap sources.

# Generated secure password:
nx9-wg init --generate-password --write-password-file /var/lib/nx9-wg/admin-password

# Password via stdin:
echo "StrongPassword123!" | nx9-wg init --password-stdin

# Password from file:
nx9-wg init --password-file /run/secrets/admin_pw

4. system

• nx9-wg system status: System database statistics and object counts.
• nx9-wg system health: System and SQLite connectivity health check.
• nx9-wg system info: System platform, architecture, and runtime paths.
• nx9-wg system settings list: List all key-value settings.
• nx9-wg system settings get <KEY>: Query setting value.
• nx9-wg system settings set <KEY> <VALUE> [--secret]: Save setting.
• nx9-wg system settings delete <KEY>: Delete setting.

5. admin

• nx9-wg admin info: Query administrator account metadata.
• nx9-wg admin password: Change administrator password.
• nx9-wg admin token create <NAME> [--expires-in-days N] [--write-token-file PATH]: Generate API token.
• nx9-wg admin token list: List active API tokens.
• nx9-wg admin token revoke <TOKEN_ID>: Revoke an API token.
• nx9-wg admin session list: List active browser sessions.
• nx9-wg admin session revoke-all: Invalidate all active sessions.

6. interface

• nx9-wg interface list: List all WireGuard interfaces.
• nx9-wg interface create <NAME> --address-v4 <CIDR> [--port PORT] [--mtu MTU]: Create interface.
• nx9-wg interface show <NAME_OR_ID>: Show interface configuration.
• nx9-wg interface enable <NAME_OR_ID>: Enable interface (IFF_UP).
• nx9-wg interface disable <NAME_OR_ID>: Disable interface (IFF_DOWN).
• nx9-wg interface delete <NAME_OR_ID>: Delete interface.

7. peer

• nx9-wg peer list [--interface NAME]: List enrolled peers.
• nx9-wg peer create --interface <IFACE> --name <NAME> [--profile PROFILE] [--mtu MTU]: Enroll peer.
• nx9-wg peer show <PEER_ID>: Show peer configuration.
• nx9-wg peer enable <PEER_ID> / disable <PEER_ID>: Toggle peer state.
• nx9-wg peer delete <PEER_ID>: Delete peer.
• nx9-wg peer config <PEER_ID> [--device DEV] [--connection CONN]: Output .conf client file.
• nx9-wg peer qr <PEER_ID>: Render ASCII QR code in terminal for mobile scanning.

8. network

• nx9-wg network list: List subnet networks.
• nx9-wg network create <NAME> --cidr <CIDR>: Create network.
• nx9-wg network delete <NAME_OR_ID>: Delete network.

9. route

• nx9-wg route list: List routing table entries.
• nx9-wg route add --destination <CIDR> [--gateway IP] [--interface-name IFACE] [--metric M]: Add route.
• nx9-wg route delete <ROUTE_ID>: Delete route.

10. firewall

• nx9-wg firewall list: List nftables firewall rules.
• nx9-wg firewall add --name <NAME> [--protocol PROTO] [--port PORT] [--action ACTION] [--priority P]: Add rule.
• nx9-wg firewall enable <RULE_ID> / disable <RULE_ID>: Toggle rule.
• nx9-wg firewall delete <RULE_ID>: Delete rule.

11. nat

• nx9-wg nat status: Query NAT masquerade state.
• nx9-wg nat enable / disable: Toggle outbound NAT masquerading.

12. forwarding

• nx9-wg forwarding status: Query kernel /proc/sys/net/ipv4/ip_forward status.
• nx9-wg forwarding enable / disable: Toggle kernel IP forwarding.

13. reconcile

• nx9-wg reconcile plan: Calculate read-only drift between SQLite and kernel.
• nx9-wg reconcile apply: Apply mutations across all execution planes.
• nx9-wg reconcile verify: Post-apply verification check.

14. backup

• nx9-wg backup list: List backup snapshots.
• nx9-wg backup create [--description DESC]: Generate atomic SQLite online backup (VACUUM INTO).
• nx9-wg backup verify <PATH>: Verify SQLite 3 header and SHA-256 checksum.
• nx9-wg backup restore <PATH_OR_ID>: Restore database with automatic safety snapshot.

15. audit

• nx9-wg audit list [--limit N] [--event-type TYPE]: List append-only audit trail records.

16. live

• nx9-wg live interfaces: Query active Linux kernel WireGuard interfaces.
• nx9-wg live peers <IFACE>: Query live peers, transfer bytes, and handshakes.
• nx9-wg live routes: Query live kernel routing table.
• nx9-wg live nftables: Query active table inet nx9_wg ruleset.

17. diagnostics

• nx9-wg diagnostics all: Inspect health across all 9 subsystems.
• nx9-wg diagnostics <SUBSYSTEM>: Inspect specific subsystem (system, network, wireguard, peer, routing, forwarding, firewall, nat, reconciliation).