# 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 ` | `NX9_WG_CONFIG` | Path to configuration file (default: `/etc/nx9-wg/config.toml`) | | `-d, --data-dir ` | `NX9_WG_DATA_DIR` | Path to data directory (default: `/var/lib/nx9-wg`) | | `--database ` | `NX9_WG_DATABASE` | Specific SQLite database file path or URL | | `--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 ` | `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. ```bash nx9-wg version nx9-wg version --format json ``` ### 2. `serve` Starts the Axum REST API daemon, WebSocket streamer, and background reconciliation scheduler. ```bash nx9-wg serve nx9-wg serve --bind 0.0.0.0:8080 ``` ### 3. `init` Initializes the single administrator account across bootstrap sources. ```bash # 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 `: Query setting value. - `nx9-wg system settings set [--secret]`: Save setting (validates `wireguard.server_host`, `wireguard.server_port`, `wireguard.server_endpoint_enabled`). - `nx9-wg system settings delete `: Delete setting. ```bash # 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 [--days N] [--write-token-file PATH]`: Generate API token. - `nx9-wg admin tokens list`: List active API tokens. - `nx9-wg admin tokens revoke `: Revoke an API token. - `nx9-wg admin sessions list`: List active browser sessions. - `nx9-wg admin sessions revoke `: Revoke an active session. - `nx9-wg admin sessions revoke-all`: Invalidate all active sessions. ### 6. `interface` - `nx9-wg interface list`: List all WireGuard interfaces. - `nx9-wg interface create --address-v4 [--address-v6 ] [--port PORT] [--mtu MTU] [--dns DNS]`: Create interface. - `nx9-wg interface show `: Show interface details. - `nx9-wg interface update [--port P] [--address-v4 A] [--address-v6 A] [--mtu M] [--dns D] [--enabled BOOL]`: Update interface. - `nx9-wg interface enable `: Enable interface (`IFF_UP`). - `nx9-wg interface disable `: Disable interface (`IFF_DOWN`). - `nx9-wg interface delete `: Delete interface (cascades to peers). - `nx9-wg interface status `: Show live interface status and peer metrics. - `nx9-wg interface reconcile `: Reconcile specific interface with kernel. ### 7. `peer` - `nx9-wg peer list [--interface NAME_OR_ID]`: List enrolled peers. - `nx9-wg peer show `: Show peer configuration. - `nx9-wg peer create --interface --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 [--name N] [--allowed-ips IPS] [--endpoint EP] [--persistent-keepalive SECS] [--mtu M] [--enabled BOOL]`: Update peer. - `nx9-wg peer enable ` / `disable `: Toggle peer state. - `nx9-wg peer revoke `: Revoke peer. - `nx9-wg peer expire `: Mark peer as expired. - `nx9-wg peer lifecycle `: Show peer lifecycle metadata. - `nx9-wg peer status `: Show live peer status and telemetry. - `nx9-wg peer delete `: Delete peer. - `nx9-wg peer config [--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 [--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 `: Show details of a client profile (e.g. `default-mobile`, `android-mobile`). - `nx9-wg profile validate `: 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 `: Show network details. - `nx9-wg network create --cidr [--description DESC]`: Create network. - `nx9-wg network available [--limit N] [--interface IFACE]`: Show available unallocated IP addresses. - `nx9-wg network allocations `: Show allocated IP addresses and peer mappings. - `nx9-wg network update [--name N] [--cidr C] [--description D] [--enabled BOOL]`: Update network. - `nx9-wg network delete `: Delete subnet network. ### 10. `route` - `nx9-wg route list`: List configured routing rules. - `nx9-wg route show `: Show route details. - `nx9-wg route add --destination [--gateway IP] [--interface-name IFACE] [--metric M]`: Add kernel routing rule. - `nx9-wg route update [--destination C] [--gateway IP] [--interface-name IFACE] [--metric M] [--enabled BOOL]`: Update route. - `nx9-wg route delete `: 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 `: Show firewall rule details. - `nx9-wg firewall add --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 [--name N] [--action A] [--priority P] [--enabled BOOL]`: Update rule. - `nx9-wg firewall enable ` / `disable `: Toggle rule. - `nx9-wg firewall delete `: 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 `: Show backup details and manifest. - `nx9-wg backup verify `: Verify SQLite 3 header and SHA-256 checksum. - `nx9-wg backup restore [-y, --yes]`: Restore database with automatic safety snapshot. - `nx9-wg backup delete `: 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 `: 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 `: Show live interface statistics. - `nx9-wg live peer `: 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 [--peer PEER_UUID]`: Inspect specific subsystem (`system`, `network`, `wan`, `wireguard`, `peer`, `routing`, `forwarding`, `firewall`, `nat`, `mtu`, `reconciliation`).