nx9-wg/docs/CLI.md

Native CLI Command Reference (nx9-wg)

The nx9-wg binary provides native CLI coverage across all 18 application command groups 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 bootstrap sources.

# Generate secure random password written to a restricted file:
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 (validates wireguard.server_host, wireguard.server_port, wireguard.server_endpoint_enabled).
• nx9-wg system settings delete <KEY>: Delete setting.

# Configure persistent WireGuard server endpoint:
nx9-wg system settings set wireguard.server_host vpn.thakares.com
nx9-wg system settings set wireguard.server_port 51820
nx9-wg system settings set wireguard.server_endpoint_enabled true

5. admin

• nx9-wg admin status: Query administrator account metadata.
• nx9-wg admin create [--username U] [--password P | --password-stdin | --generate-password]: Bootstrap admin if uninitialized.
• nx9-wg admin password [--new-password P | --stdin | --password-file F | --generate]: Change administrator password.
• nx9-wg admin tokens create --name <NAME> [--days N] [--write-token-file PATH]: Generate API token.
• nx9-wg admin tokens list: List active API tokens.
• nx9-wg admin tokens revoke <TOKEN_ID>: Revoke an API token.
• nx9-wg admin sessions list: List active browser sessions.
• nx9-wg admin sessions revoke <SESSION_ID>: Revoke an active session.
• nx9-wg admin sessions revoke-all: Invalidate all active sessions.

6. interface

• nx9-wg interface list: List all WireGuard interfaces (displays Role: Overlay vs Upstream).
• nx9-wg interface create <NAME> --address-v4 <CIDR> [--address-v6 <CIDR>] [--port PORT] [--mtu MTU] [--dns DNS]: Create interface.
• nx9-wg interface show <NAME_OR_ID>: Show interface details.
• nx9-wg interface update <NAME_OR_ID> [--port P] [--address-v4 A] [--address-v6 A] [--mtu M] [--dns D] [--enabled BOOL]: Update interface.
• nx9-wg interface enable <NAME_OR_ID>: Enable interface (IFF_UP).
• nx9-wg interface disable <NAME_OR_ID>: Disable interface (IFF_DOWN; wg0 cannot be disabled).
• nx9-wg interface restart <NAME_OR_ID>: Restart interface (tears down kernel device and re-applies desired configuration and peers).
• nx9-wg interface delete <NAME_OR_ID>: Delete interface (removes kernel device via Netlink and cascades to peers in database; wg0 cannot be deleted).
• nx9-wg interface status <NAME_OR_ID>: Show live interface status and peer metrics.
• nx9-wg interface reconcile <NAME_OR_ID>: Reconcile specific interface with kernel.
• nx9-wg interface upstream list: List all Upstream WireGuard interfaces.
• nx9-wg interface upstream show <NAME_OR_ID>: Show Upstream interface configuration and provider peer details.
• nx9-wg interface upstream import <NAME> [--file <PATH> | --config <CONF_STR>]: Import third-party WireGuard .conf configuration (e.g. ProtonVPN) and create an Upstream interface.
• nx9-wg interface upstream status <NAME_OR_ID>: Show live kernel status and handshake for an Upstream interface.
• nx9-wg interface upstream enable <NAME_OR_ID>: Enable an Upstream interface.
• nx9-wg interface upstream disable <NAME_OR_ID>: Disable an Upstream interface.
• nx9-wg interface upstream restart <NAME_OR_ID>: Restart an Upstream interface (teardown + re-sync).
• nx9-wg interface upstream delete <NAME_OR_ID>: Delete an Upstream interface.

7. peer

• nx9-wg peer list [--interface NAME_OR_ID]: List enrolled peers.
• nx9-wg peer show <PEER_ID>: Show peer configuration.
• nx9-wg peer create --interface <IFACE> --name <NAME> [--peer-type TYPE] [--profile PROFILE] [--network NET] [--address-v4 CIDR] [--allowed-ips IPS] [--endpoint EP] [--persistent-keepalive SECS] [--mtu MTU] [--expires-at RFC3339]: Enroll peer.
• nx9-wg peer update <PEER_ID> [--name N] [--allowed-ips IPS] [--endpoint EP] [--persistent-keepalive SECS] [--mtu M] [--enabled BOOL]: Update peer.
• nx9-wg peer enable <PEER_ID> / disable <PEER_ID>: Toggle peer state.
• nx9-wg peer revoke <PEER_ID>: Revoke peer.
• nx9-wg peer expire <PEER_ID>: Mark peer as expired.
• nx9-wg peer lifecycle <PEER_ID>: Show peer lifecycle metadata.
• nx9-wg peer status <PEER_ID>: Show live peer status and telemetry.
• nx9-wg peer delete <PEER_ID>: Delete peer.
• nx9-wg peer config <PEER_ID> [--provider PROV] [--device DEV] [--connection CONN] [--nat NAT] [--mtu MTU] [--profile PROF] [--endpoint EP] [--output PATH]: Export .conf client file (uses persistent wireguard.server_* settings or --endpoint override).
• nx9-wg peer qr <PEER_ID> [--provider PROV] [--device DEV] [--connection CONN] [--nat NAT] [--mtu MTU] [--profile PROF] [--endpoint EP] [--qr-format terminal|svg|png]: Render QR code in terminal, SVG, or PNG format.

8. profile

• nx9-wg profile list [--provider PROV] [--device DEV] [--connection CONN] [--nat NAT]: List client configuration profiles.
• nx9-wg profile show <PROFILE_ID>: Show details of a client profile (e.g. default-mobile, android-mobile).
• nx9-wg profile validate <MTU>: Validate MTU against safe operational limits.
• nx9-wg profile resolve [--provider PROV] [--device DEV] [--connection CONN] [--nat NAT] [--mtu MTU] [--profile PROF]: Resolve optimal client profile and MTU.

9. network

• nx9-wg network list: List subnet networks.
• nx9-wg network show <ID>: Show network details.
• nx9-wg network create <NAME> --cidr <CIDR> [--description DESC]: Create network.
• nx9-wg network available <ID> [--limit N] [--interface IFACE]: Show available unallocated IP addresses.
• nx9-wg network allocations <ID>: Show allocated IP addresses and peer mappings.
• nx9-wg network update <ID> [--name N] [--cidr C] [--description D] [--enabled BOOL]: Update network.
• nx9-wg network delete <ID>: Delete subnet network.

10. route

• nx9-wg route list: List configured routing rules.
• nx9-wg route show <ID>: Show route details.
• nx9-wg route add --destination <CIDR> [--gateway IP] [--interface-name IFACE] [--metric M]: Add kernel routing rule.
• nx9-wg route update <ID> [--destination C] [--gateway IP] [--interface-name IFACE] [--metric M] [--enabled BOOL]: Update route.
• nx9-wg route delete <ID>: Delete routing rule.
• nx9-wg route status: Show current kernel routing status.
• nx9-wg route sync: Synchronize routes with kernel routing table.

11. firewall

• nx9-wg firewall list [--peer PEER]: List configured nftables rules.
• nx9-wg firewall show <ID>: Show firewall rule details.
• nx9-wg firewall add --name <NAME> [--direction in|out|forward] [--source CIDR] [--destination CIDR] [--peer PEER] [--protocol tcp|udp|tcp_udp|icmp|any] [--port P] [--port-range R] [--action accept|drop|reject] [--priority P]: Add rule.
• nx9-wg firewall update <ID> [--name N] [--action A] [--priority P] [--enabled BOOL]: Update rule.
• nx9-wg firewall enable <ID> / disable <ID>: Toggle rule.
• nx9-wg firewall delete <ID>: Delete rule.
• nx9-wg firewall sync: Synchronize nftables ruleset in table inet nx9_wg.
• nx9-wg firewall status: Show active nftables status.

12. nat

• nx9-wg nat status: Query NAT masquerade state.
• nx9-wg nat enable / disable: Toggle outbound NAT masquerading.
• nx9-wg nat list: List subnets configured for NAT masquerade.
• nx9-wg nat sync: Synchronize NAT rules with kernel.

13. forwarding

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

14. reconcile

• nx9-wg reconcile status: Inspect reconciliation status and statistics.
• nx9-wg reconcile plan [--interface IFACE]: Calculate read-only drift plan between SQLite and Linux kernel.
• nx9-wg reconcile apply [--interface IFACE]: Apply reconciliation mutations to live kernel state.
• nx9-wg reconcile verify: Verify zero drift between SQLite and kernel.

15. backup

• nx9-wg backup list: List backup snapshots.
• nx9-wg backup create [--description DESC]: Generate atomic SQLite online backup (VACUUM INTO).
• nx9-wg backup show <ID>: Show backup details and manifest.
• nx9-wg backup verify <PATH>: Verify SQLite 3 header and SHA-256 checksum.
• nx9-wg backup restore <PATH> [-y, --yes]: Restore database with automatic safety snapshot.
• nx9-wg backup delete <ID>: Delete backup record and snapshot archive.

16. audit

• nx9-wg audit list [--event-type TYPE] [--actor ACTOR] [--resource-type TYPE] [--limit N] [--offset N]: List append-only audit trail records.
• nx9-wg audit show <ID>: Show full details for an audit event.

17. live

• nx9-wg live interface list: List live WireGuard interface names in kernel.
• nx9-wg live interface show <NAME>: Show live interface statistics.
• nx9-wg live peer <IFACE>: Query live peers, transfer bytes, and handshakes.
• nx9-wg live routes: Query live Linux kernel routing table.
• nx9-wg live firewall: Query live active table inet nx9_wg nftables ruleset.
• nx9-wg live forwarding: Query live IP packet forwarding status.
• nx9-wg live nat: Query live NAT masquerade status.

18. diagnostics

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