CLI Reference¶

All commands require a topology YAML file passed. By default the path is conglomerate.yaml. It is possible to override that via the global --yaml option:

hexrift --yaml conglomerate.yaml <command> [options]

Global options¶

validate¶

hexrift validate

Validate the topology YAML against the Pydantic schema and report any errors.

Output on success:

Valid — conglomerate.yaml
  2 groups, 5 users, 2 exit regions, 1 hub regions, 6 nodes

Output on failure: prints the validation error and aborts.

show¶

hexrift show

Visualize the full network topology as a tree: global settings, regions, nodes, users (by group), portals, and guests. Each portal lists its members, its strict state, and one line per published port carrying that port's source allowlist and node scope.

derive¶

hexrift derive <entity>

Show derived identifiers in a table.

Arguments:

Example:

hexrift derive users
hexrift derive all

nodes¶

hexrift nodes list [--names | --domains | --json] [--type exit|hub]
hexrift nodes add <NODE_ID> [options]
hexrift nodes remove <NODE_ID>

add and remove edit the regions: section of the topology YAML in place: only the edited lines change, everything else is kept byte for byte, and YAML shapes that cannot be spliced safely are refused with a message saying why. After writing, the file is re-validated. A validation failure is reported as a warning and the edit is kept, so a missing piece such as an exit node's reality block can be filled in by hand.

list¶

List nodes with their hostnames. Designed for use in shell scripts.

Options:

Examples:

# Tab-separated ID + hostname (default)
hexrift nodes list

# All exit node IDs — useful for loops
hexrift nodes list --names --type exit

# All hub hostnames
hexrift nodes list --domains --type hub

# Structured output for other tools
hexrift nodes list --json --type exit | jq -r '.[].hostname'

--json output:

[
  {"id": "nlA00", "hostname": "nlA00.aphelion.example.com", "region": "nl", "type": "exit"},
  {"id": "mskA00", "hostname": "mskA00.perigee.example.com", "region": "msk", "type": "hub"}
]

add¶

Add NODE_ID to its region, creating the region when missing (exits get an unused vless_route). A balanced region without lb_fallback gets its first primary node written as one. Adding a node that is already present is a no-op.

Options:

remove¶

Remove NODE_ID from its region, dropping hub_routes and lb_fallback entries that point at it, and routes to the region once it is empty. An emptied region keeps its settings. A node that is not in the topology is skipped.

Examples:

# New exit node in the existing `nl` region
hexrift nodes add nlA40 --reality-dest www.samsung.com:443 \
  --reality-server-names www.samsung.com,samsung.com --reality-xhttp-path /login/

# New hub node, hostname follows the other `msk` hubs
hexrift nodes add mskA30 --no-ipv6

# First node of a new exit region, `--type` is required
hexrift nodes add frA00 --type exit

# Decommission
hexrift nodes remove nlA40

share¶

hexrift share <username> [options]

Generate VLESS or Hysteria share URLs — or WireGuard client configs — for a user. Direct URLs are Reality by default; a hub that serves tls gets one security=tls URL per node, labelled TLS.

Arguments:

Options:

Examples:

# Direct link for alice on all hubs
hexrift share alice

# CDN link on a specific hub
hexrift share alice --cdn --hub euH00

# Hysteria 2 link, bare, piped to clipboard
hexrift share alice --hy2 --bare | clip

# WireGuard client config for alice
hexrift share alice --wg

# WireGuard configs for all of alice's guests, piped to clipboard
hexrift share alice --wg --all-guests --bare | clip

# All guest links, piped to clipboard
hexrift share alice --all-guests --bare | clip

gen-keys¶

hexrift gen-keys [NODE_ID | --all] [options]

Generate x25519 Reality keypairs and ML-KEM 768 encryption keys. One YAML file is written per node to <keys-dir>/<nodeId>.yaml.

Arguments:

Options:

Examples:

# Single node
hexrift gen-keys nlA00

# All nodes, overwrite existing
hexrift gen-keys --all --force

# Custom keys directory
hexrift gen-keys --all --keys-dir /etc/hexrift/keys

build¶

hexrift build [NODE_ID | --all] --xray|--haproxy [options]

Generate Xray config.json and/or HAProxy .cfg for node(s). Output is written to <out-dir>/<nodeId>/.

Arguments:

Options:

Examples:

# Xray config for one node
hexrift build nlA00 --xray

# All nodes, both Xray and HAProxy
hexrift build --all --xray --haproxy --out-dir ./out

# Custom directories
hexrift build euH00 --xray --keys-dir /etc/hexrift/keys --out-dir /etc/xray

gen-portal¶

hexrift gen-portal <PORTAL_ID> [options]
hexrift gen-portal --all [options]

Generate the Xray bridge config.json for portal(s) declared in the top-level portals: section. Each config is written to <out-dir>/<portal-id>/config.json with 0o600 permissions (it embeds key material). Deploy it on the portal machine; several machines may run the same config — the hubs pool their tunnels.

Unless the portal sets strict: false, the generated routing mirrors the portal's routes and publish matchers and blackholes everything else, so the config has to be regenerated whenever those matchers change.

Arguments:

Options:

Examples:

# All portals
hexrift gen-portal --all

# A single portal, into a custom directory
hexrift gen-portal home --out-dir ./portals

diff¶

hexrift diff <NODE_ID> [options]

Show a unified diff between the freshly generated config.json and the currently deployed one.

Arguments:

Options:

Examples:

# Diff against local configs/ directory
hexrift diff nlA00

# Diff against deployed config
hexrift diff nlA00 --current-dir /etc/xray

Prints No differences. if configs match.