CLI Commands Reference

Detailed documentation of the wiretastix-cli commands.

wiretastix-cli is an interactive shell only – there is no non-interactive, single-command mode. Running wiretastix-cli always launches the > prompt; any commands you want to run are typed there, one at a time. This section details the global connection flags and every command available inside the shell.

Global Flags

These flags configure the connection the interactive shell uses to reach the Wiretastix API. They’re parsed before the shell starts.

• -api <url> (or --api): The base API URL of Wiretastix (e.g., https://127.0.0.1:8095/wiretastix/api/v1/). Can also be set via the WIRETASTIX_API environment variable. Defaults to https://127.0.0.1:8095/wiretastix/api/v1/.
• -token <token> (or --token): The authentication token to use to connect to the API. Can also be set via the WIRETASTIX_TOKEN environment variable. Required – the CLI exits immediately with “no token specified” if neither this flag nor the environment variable is set.
• -k (or --k): Skip TLS certificate verification when connecting to the API (use with caution).
• -V (or --V): Prints version/build info in a slightly different format on startup. Note this does not exit early or skip launching the shell – it still requires a valid token and still drops you into the interactive prompt afterwards.

wiretastix-cli -h/--help documents both environment variables directly in the flag descriptions:

$ wiretastix-cli --help
Usage of wiretastix-cli:
  -V	Show version and exists
  -api string
    	The base API url of wiretastix. Overridden by $WIRETASTIX_API if set. (default "https://127.0.0.1:8095/wiretastix/api/v1/")
  -k	Insecure: skip TLS checks when connecting to the API
  -token string
    	The Auth Token to use to connect to the API. Overridden by $WIRETASTIX_TOKEN if set.

Interactive Shell Commands

Once connected, you’ll see a Wiretastix Interactive Shell banner and a > prompt. All command groups below use the singular noun (peer, user, group, rule, token), not the plural.

version

Shows the CLI’s build version and timestamp.

> version

token

Manage API authentication tokens.

• token list – List all tokens. Actual token values are never shown (they’re stored hashed); only name, description, and creation date are listed.
• token create <name> [description...] – Create a new token. The name (letters/numbers/-/_/., max 16 chars) is the only argument the CLI itself requires, and a multi-word description joins with spaces. In practice you still need to supply a real description, though: the server rejects one that’s empty or under 3 characters (after trimming whitespace) with “description must be filled in,” and the CLI sends an empty string if you omit it entirely – so token create prometheus-scraper with nothing else will fail server-side even though the CLI’s own argument parsing accepts it.
  • Usage: token create prometheus-scraper read-only metrics scraper.
• token delete <name> [<name2> ...] – Delete one or more tokens by name.
  • Usage: token delete prometheus-scraper

config

Manage global Wiretastix configuration parameters.

• config list – List all configuration parameters currently set.
• config set <param> <value> – Set a configuration parameter.
  • Usage: config set default_keepalive_seconds 30
• config delete <param> [<param2> ...] – Delete one or more configuration parameters, resetting them to their built-in default.
  • Usage: config delete default_keepalive_seconds

Valid parameter names: default_keepalive_seconds, max_devices, default_group, default_mtu, default_dns, default_search, default_endpoint, new_users_enabled, new_devices_enabled, default_allowed_ips, auto_disable_on_auth_error, reauthenticate_every, additional_ports – this is the complete set of thirteen; config set/config list/config delete reject anything not on this list. See the Configuration Reference for what each one does.

peer

Manage WireGuard peers. See Managing Peers for a walkthrough.

• peer list – List all peers (ID, public key, associated user if any, name, IPv4/IPv6, active status).
• peer status – Real-time status and statistics (handshake, Rx/Tx) for peers.
• peer create <name> – Create a new unmanaged/anonymous peer (no user or OIDC association). Outputs the client’s WireGuard config as both a QR code and raw text – this is the only time it’s ever shown; there’s no separate command to retrieve it again.
  • Usage: peer create backup-server
• peer delete <id> [<id2> ...] – Delete one or more peers by their numeric ID (from peer list) – not by name.
  • Usage: peer delete 42 43

user

Manage users. There is no user create command – users are provisioned automatically when they first authenticate through your OIDC Identity Provider, not created manually via the CLI.

• user list – List all users (ID, nickname, name, email, enabled, active).
• user show <id> – Show full details for a specific user, including their groups.
• user delete <id> [<id2> ...] – Delete one or more users by ID.
• user enable <id> [<id2> ...] – Enable one or more users.
• user disable <id> [<id2> ...] – Disable one or more users (blocks further authentication without deleting their data).
• user update <id> maxdevices <n> – Update a user’s max-devices override. maxdevices is the only property this command supports.
  • Usage: user update jdoe maxdevices 5

group

Manage groups. Group membership itself comes from your OIDC provider’s group claims at login time – there is no CLI command to add or remove a specific user from a group.

• group list – List all groups, including each group’s Policy.
• group show <oidc> – Show full details for a group, identified by its OIDC group name.
• group delete <oidc> [<oidc2> ...] – Delete one or more groups.
• group enable <oidc> [...] / group disable <oidc> [...] – Enable or disable one or more groups.
• group create <key> <value> [<key2> <value2> ...] – Create a group from key/value pairs (not flags). oidc and policy are both required; the rest are optional.
  • Valid keys: oidc, name, prio, policy (accept/drop/none – required, an empty/unset policy is rejected), enabled (true/false), allowed-ips, dns, max-devices, search-domain.
  • Usage: group create oidc developers name Developers prio 10 policy accept allowed-ips 10.0.0.0/24
  • policy is enforced as a catch-all for the group – accept/drop apply after that group’s own rules, to any traffic they didn’t match; none makes no policy statement (unmatched traffic just falls through). See NFTables Integration.
  • prio (lower runs first) decides which group’s policy wins when a peer belongs to more than one group – the first group in priority order with an accept/drop policy decides, and groups after it don’t get a say for that traffic. See NFTables Integration.
• group update <oidc> <key> <value> [...] – Update an existing group using the same keys as create.
  • Usage: group update developers max-devices 3

rule

Manage nftables-backed firewall rules. Rules are structured field/value pairs, not raw nftables expressions, and are identified by an auto-generated numeric ID rather than a name.

• rule list – List all rules.
• rule add <key> <value> [<key2> <value2> ...] – Add a rule from key/value pairs.
  • Valid keys: group (the target group’s OIDC name), nfproto (ip4/ip6), l4proto (tcp/udp/icmp), src, sport, dst, dport, action (accept/drop/none).
  • Usage: rule add group developers nfproto ip4 l4proto tcp dport 22 action drop
  • All of this is validated when the rule is created, not just when it’s later applied: group/action are required, sport/dport require l4proto to be tcp or udp, and src/dst must be a CIDR (with a mask, e.g. 10.0.1.0/24 – a bare IP is rejected) whose address family matches nfproto. A malformed rule that used to only fail silently at rule apply time now errors immediately on rule add.
• rule apply – Apply all stored rules to the live nftables firewall.
• rule del <id> [<id2> ...] – Delete one or more rules by numeric ID (from rule list).
  • Usage: rule del 7