thakares/nx9-wg
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
master
nx9-wg/docs/CLI.md
T
thakares edc710cbd2 Release v1.1.0
2026-09-02 15:19:19 +05:30

187 lines
11 KiB
Markdown
Raw Permalink Blame History

# 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.
```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 <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.
```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 <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`).
Reference in new issue View Git Blame Copy Permalink