thakares/nx9-wg
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
96e4e0fd97c930fb648b208d33b42ee1f75d89ab
nx9-wg/docs/cli.md
T

8.3 KiB
Raw Blame History

Native CLI Command Reference (nx9-wg)

The nx9-wg binary provides 100% native CLI coverage for the entire NX9 WireGuard application stack. The CLI directly executes native Rust application services (Store, WireGuardEngine, NetworkEngine, ReconciliationEngine, BackupService, AuthService) without calling external subprocesses.

Global Options

  • -c, --config <PATH>: Path to configuration file (env: NX9_WG_CONFIG, default: /etc/nx9-wg/config.toml)
  • -d, --data-dir <PATH>: Path to data directory (env: NX9_WG_DATA_DIR, default: /var/lib/nx9-wg)
  • --database <PATH>: Explicit SQLite database path or URL (env: NX9_WG_DATABASE)
  • --format <table|json|yaml|csv>: Output formatting style (default: table)
  • --json: Output strictly in formatted JSON
  • -q, --quiet: Suppress status and conversational messages
  • -v, --verbose: Enable debug trace output
  • --log-level <LEVEL>: Log verbosity level (trace, debug, info, warn, error, env: NX9_WG_LOG_LEVEL)

Command Groups

1. version

Displays version, build metadata, target architecture, and feature capabilities.

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

2. serve

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

nx9-wg serve

# To intentionally expose the management API on all interfaces:
nx9-wg serve --bind 0.0.0.0:8080

3. init

Initializes the single administrator account across 7 supported bootstrap sources.

# Generated password:
nx9-wg init --generate-password --write-password-file /root/admin-pw.txt

# Password from standard input:
echo "SecureSecret123!" | 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 database connectivity health check.
  • nx9-wg system info: System platform, architecture, and runtime paths.
  • nx9-wg system settings list: List all configuration 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 status: View administrator profile and last login metrics.
  • nx9-wg admin create: Provision administrator if not already initialized.
  • nx9-wg admin password --new-password <PW> | --stdin | --password-file <PATH> | --generate: Update password and invalidate all sessions.
  • nx9-wg admin sessions list: List active sessions.
  • nx9-wg admin sessions revoke <SESSION_ID>: Invalidate specific session.
  • nx9-wg admin sessions revoke-all: Invalidate all active administrator sessions.
  • nx9-wg admin tokens create --name <NAME> [--days <DAYS>] [--write-token-file <PATH>]: Generate a long-lived API token. The recommended secure workflow writes the one-time plaintext token to a file with restrictive permissions; token hashes are redacted from normal CLI output.
  • nx9-wg admin tokens list: List all API token metadata.
  • nx9-wg admin tokens revoke <TOKEN_ID>: Revoke an API token.

6. interface

  • nx9-wg interface list: List all WireGuard interfaces.
  • nx9-wg interface show <NAME_OR_ID>: Inspect interface details.
  • nx9-wg interface create <NAME> --address-v4 <CIDR> [--port <PORT>] [--address-v6 <CIDR>] [--mtu <MTU>] [--dns <DNS>]: Create an interface.
  • nx9-wg interface update <NAME_OR_ID> [--port <PORT>] [--address-v4 <CIDR>] [--enabled <BOOL>]: Update interface properties.
  • nx9-wg interface enable <NAME_OR_ID> / disable <NAME_OR_ID>: Toggle administrative state.
  • nx9-wg interface delete <NAME_OR_ID>: Delete interface and associated peers.
  • nx9-wg interface status <NAME>: Query live interface telemetry.
  • nx9-wg interface reconcile <NAME>: Reconcile interface state with the Linux kernel.

7. peer

  • nx9-wg peer list [--interface <NAME_OR_ID>]: List enrolled peers.
  • nx9-wg peer show <PEER_ID>: Inspect peer configuration and metadata.
  • nx9-wg peer create --interface <NAME_OR_ID> --name <NAME> [--address-v4 <CIDR>] [--allowed-ips <CIDRS>] [--endpoint <IP:PORT>]: Enroll peer.
  • nx9-wg peer update <PEER_ID> [--name <NAME>] [--allowed-ips <CIDRS>] [--enabled <BOOL>]: Update peer parameters.
  • nx9-wg peer enable <PEER_ID> / disable <PEER_ID> / revoke <PEER_ID>: Peer lifecycle transitions.
  • nx9-wg peer delete <PEER_ID>: Remove peer.
  • nx9-wg peer status <PEER_ID>: Live handshake, endpoint, and bandwidth telemetry.
  • nx9-wg peer config <PEER_ID> [--output <PATH>]: Generate standard client .conf file.
  • nx9-wg peer qr <PEER_ID> [--qr-format <terminal|svg|png>]: Generate enrollment QR code.

8. network

  • nx9-wg network list: List defined subnet networks.
  • nx9-wg network show <ID>: Inspect network details.
  • nx9-wg network create <NAME> <CIDR> [--description <TEXT>]: Create subnet network.
  • nx9-wg network update <ID> [--name <NAME>] [--cidr <CIDR>] [--enabled <BOOL>]: Update network.
  • nx9-wg network delete <ID>: Delete subnet network.

9. route

  • nx9-wg route list: List configured kernel routing rules.
  • nx9-wg route show <ID>: Inspect route rule.
  • nx9-wg route add --destination <CIDR> [--gateway <IP>] [--interface-name <IFACE>] [--metric <METRIC>]: Add route.
  • nx9-wg route update <ID> [--destination <CIDR>] [--gateway <IP>] [--metric <METRIC>]: Update route.
  • nx9-wg route delete <ID>: Delete route.
  • nx9-wg route status: Status of kernel routing table management.
  • nx9-wg route sync: Synchronize desired routes to Linux kernel routing table.

10. firewall

  • nx9-wg firewall list: List nftables firewall rules.
  • nx9-wg firewall show <ID>: Inspect firewall rule.
  • nx9-wg firewall add --name <NAME> [--direction <in|out|forward>] [--source <CIDR>] [--destination <CIDR>] [--protocol <tcp|udp|icmp|any>] [--port <PORT>] [--action <accept|drop|reject>] [--priority <INT>]: Add rule.
  • nx9-wg firewall update <ID> [--action <ACTION>] [--priority <INT>] [--enabled <BOOL>]: Update rule.
  • nx9-wg firewall delete <ID> / enable <ID> / disable <ID>: Rule management.
  • nx9-wg firewall status: Inspect active nftables ruleset and table.
  • nx9-wg firewall sync: Synchronize firewall ruleset to nftables.

11. nat

  • nx9-wg nat status: Inspect NAT masquerade status and managed subnets.
  • nx9-wg nat enable / disable: Toggle NAT masquerade setting.
  • nx9-wg nat list: List subnets configured for NAT masquerade.
  • nx9-wg nat sync: Synchronize NAT rules to nftables postrouting chain.

12. forwarding

  • nx9-wg forwarding status: Inspect IPv4 and IPv6 kernel packet forwarding state.
  • nx9-wg forwarding enable / disable: Enable or disable kernel packet forwarding.
  • nx9-wg forwarding sync: Synchronize sysctl forwarding parameters.

13. reconcile

  • nx9-wg reconcile status: Summary of detected drift across all subsystems.
  • nx9-wg reconcile plan [--interface <NAME>]: Dry-run drift analysis without state mutation.
  • nx9-wg reconcile apply [--interface <NAME>]: Reconcile SQLite desired state to Linux kernel.
  • nx9-wg reconcile verify: Assert zero drift exists between SQLite and kernel (returns exit code 1 if drift exists).

14. backup

  • nx9-wg backup create [--description <TEXT>]: Generate consistent SQLite backup snapshot with SHA-256 manifest.
  • nx9-wg backup list: List all backup snapshots.
  • nx9-wg backup show <ID>: Inspect backup metadata and file size.
  • nx9-wg backup verify --path <PATH>: Verify integrity and checksum of backup archive.
  • nx9-wg backup restore --path <PATH> --yes: Safely restore database with pre-restore safety snapshot.
  • nx9-wg backup delete <ID>: Delete backup record and archive.

15. audit

  • nx9-wg audit list [--event-type <TYPE>] [--actor <ACTOR>] [--resource-type <RESOURCE>] [--limit <N>] [--offset <N>]: Query security audit trail.
  • nx9-wg audit show <ID>: Inspect complete audit event details.

16. live

  • nx9-wg live interface list / show <NAME>: Query active WireGuard interfaces from kernel.
  • nx9-wg live peer list <IFACE> / show <KEY_OR_ID>: Query active peers from kernel.
  • nx9-wg live routes: Query live kernel routing status.
  • nx9-wg live firewall: Query live nftables ruleset.
  • nx9-wg live forwarding: Query live kernel forwarding sysctls.
  • nx9-wg live nat: Query live NAT state.
Reference in new issue View Git Blame Copy Permalink