# CLI Reference: `bauxite`

The `bauxite` is the primary command-line tool for interacting with the Bauxite Mesh.

## Global Options

- `--help`: Show help information.
- `--version`: Show version information.

## Commands

### `join`
Register a new node with the Bauxite Hub.

**Arguments:**
- `--token`: The one-time join token provided by the Control Plane.
- `--hub-url`: The gRPC URL of your Control Plane (e.g., `https://hub.example.com:50052`).
- `--node-id`: A unique identifier for this node within your mesh.
- `--hub-public-key`: The public key of the Hub for identity verification.
- `--challenge`: (Optional) Cryptographic challenge response for high-security environments.

**Example:**
```bash
bauxite join --token xyz-123 --hub-url https://hub.com --node-id robot-1 --hub-public-key abc...
```

### `run`
Start the Bauxite Mesh data plane.

**Arguments:**
- `--config`, `-c`: Path to the `config.toml` file (default: `config.toml`).
- `--connect-to`: (Optional) Node ID of a specific peer to initiate an immediate connection.
- `--telemetry-pipe`: (Optional) Enable piping of internal telemetry events to a Unix socket for external monitoring.

**Example:**
```bash
sudo bauxite run --config /etc/bauxite/config.toml
```

### `connect`
Manually trigger a connection to another node via the local management socket.

**Arguments:**
- `--id`: The Node ID of the target peer.

**Example:**
```bash
bauxite connect --id robot-2
```

### `bridge`
Log ROS 2 bridge configuration settings. **Note**: This command is a stub — it only records the settings to the agent's info log. The actual FastDDS discovery server is managed by the Citadel subsystem when the agent is running (`bauxite run`).

**Arguments:**
- `--enable-ros`: Enable ROS 2 support (default: `false`).
- `--discovery-server-id`: Discovery server identifier (default: `0`).
- `--discovery-port`: Discovery server port (default: `11811`).

**Example:**
```bash
bauxite bridge --enable-ros --discovery-server-id 1 --discovery-port 11811
```

### `setup`
Prepare the host system by mounting eBPF filesystem interfaces and configuring virtual devices.

**Arguments:**
- `--dry-run`: (Optional) Generate declarative `cloud-init.yaml` systemd templates to stdout without making host mutations.

**Examples:**
- Interactive (workstations):
  ```bash
  sudo bauxite setup
  ```
- Declarative (IaC/production):
  ```bash
  bauxite setup --dry-run > cloud-init.yaml
  ```

### `sandbox`
Manage an ephemeral, containerized multi-node local simulation for testing eBPF data plane offloads.

**Subcommands:**
- `start`: Spawn the sandbox network and nodes.
  - `--nodes`: (Optional) The number of nodes to spawn in the simulation (default: `3`).
- `stop`: Terminate and clean up all sandbox containers, namespaces, and virtual interfaces.

**Examples:**
- Start simulation:
  ```bash
  bauxite sandbox start --nodes 3
  ```
- Clean up simulation:
  ```bash
  bauxite sandbox stop
  ```

### `dashboard`
Launch the live visual fabric monitor in the terminal to review stack bypass latencies, SHM pool utilization, and core telemetry counters.

**Example:**
```bash
bauxite dashboard
```

### `tunnel`
Manage and diagnose userspace native tunnels.

**Subcommands:**
- `diagnose`: Run network audits (MTU, firewall, certificates).
  - `--interface`: (Optional) target interface to audit.
  - `--json`: (Optional) output results in structured JSON format.
- `monitor`: Monitor tunnel statistics in real-time.
  - `--dry-run`: Run a simulated monitor TUI test.

**Examples:**
- Path audit:
  ```bash
  bauxite tunnel diagnose --interface eth0 --json
  ```
- Run dry-run monitor test:
  ```bash
  bauxite tunnel monitor --dry-run
  ```

### `policy`
Manage network firewall policies by sending HTTP requests to the Bauxite Hub (Control Plane).

**Subcommands:**
- `upsert`: Create or update a firewall rule.
  - `--rule-id`: Unique identifier for the rule (required).
  - `--target`: Destination Node ID of the target peer, or `*` for all peers (required).
  - `--protocol`: Protocol (`tcp`, `udp`, `icmp`, `any`) (required).
  - `--action`: Policy action (`allow`, `deny`) (required).
  - `--port`: Allowed port(s) (comma-separated list, e.g. `80,443`, optional).
  - `--config`, `-c`: Path to the config file to load the Hub URL (default: `config.toml`).
- `delete`: Delete a firewall rule.
  - `--rule-id`: Unique identifier for the rule (required).
  - `--config`, `-c`: Path to the config file to load the Hub URL (default: `config.toml`).

**Examples:**
- Allow TCP traffic on ports 80 and 443 to a specific node:
  ```bash
  bauxite policy upsert --rule-id 10-allow-web --target web-server-node --protocol tcp --action allow --port 80,443
  ```
- Deny all UDP traffic:
  ```bash
  bauxite policy upsert --rule-id 01-deny-udp --target * --protocol udp --action deny
  ```
- Delete a rule:
  ```bash
  bauxite policy delete --rule-id 10-allow-web
  ```