Netbird CLI

netbird-cli — Client

For Terraform provider see netbird-terraform. For K8s operator see netbird-operator.

Install

curl -fsSL https://pkgs.netbird.io/install.sh | sudo bash   # Linux
# or: apt install netbird / dnf install netbird / pacman -S netbird
# GUI on desktop: netbird-ui (Wails v3 app since v0.75.0)

Client runs as a daemon (netbird service run); the CLI talks to it over a Unix socket. Default config: /var/lib/netbird/default.json.

Register & Connect

# Interactive SSO (opens browser)
netbird up

# Headless / server / routing peer — setup key from Management dashboard or API
netbird up --setup-key <key>
netbird up --setup-key-file <file>

# SSO without browser (print URL + QR for phone)
netbird login --no-browser
netbird login --qr

# Re-auth without tearing down the tunnel
netbird login --extend

Setup-key peers don't expire (not subject to login session expiration) — always use setup keys for routing peers/gateways.

Connect / Disconnect

Status

netbird status                  # connection status + peer info
netbird status -d               # detailed human-readable
netbird status --json           # JSON (jq-able)
netbird status -y               # YAML
netbird status -4               # only overlay IPv4 (e.g. 100.64.0.33)
netbird status -6               # only overlay IPv6
netbird status --check live     # health check, exit 0/1 (live|ready|startup)
netbird status -d --filter-by-status connected
netbird status -d --filter-by-connection-type P2P

Networks & Resources

netbird networks (alias routes) replaces the old routes command — for clientless Networks (subnets/domains behind routing peers).

netbird networks list                    # list available networks
netbird networks select all              # accept all (incl. new)
netbird networks select <net1> <net2>    # select specific (replace mode)
netbird networks select -a <net3>        # append to selection
netbird networks deselect <net>          # deselect

Reverse Proxy (expose a local service)

netbird expose 8080                                  # HTTP, public URL auto-created
netbird expose --protocol tcp 5432                   # L4 TCP
netbird expose --protocol udp 53                     # L4 UDP
netbird expose --protocol tls --with-custom-domain tls.example.com 4443
netbird expose --with-password safe-pass 8080        # password-protected
netbird expose --with-pin 123456 8080                # 6-digit PIN
netbird expose --with-user-groups devops,Backend 8080 # restrict to SSO groups
netbird expose --with-name-prefix my-app 8080
netbird expose --protocol tcp --with-external-port 5433 5432

Protocols: http, https, tcp, udp, tls. --with-custom-domain requires the domain configured on your account. Managed via dashboard/API afterwards (netbird_route-independent — it's the reverse proxy subsystem, not routes).

SSH

Central SSH access control (policies in dashboard, no manual key distribution):

netbird ssh <peer-name>            # SSH to peer with policy-based access
netbird ssh -u <user> <peer>       # specify username
netbird ssh -i <keyfile> <peer>    # explicit identity

Kubernetes Access (API server proxy)

netbird kubernetes list             # list clusters exposed via operator API proxy
netbird kubernetes write-kubeconfig <cluster>   # write kubeconfig for remote cluster

Works with the operator's ClusterProxy/API-server-proxy pattern: your NetBird user is the identity.

Debug & Diagnostics

Service Management

netbird service install --disable-networks        # harden: disable network selection
netbird service install --disable-profiles        # harden: disable profile switching
netbird service install --enable-json-socket      # enable HTTP/JSON API socket
netbird service install --enable-capture          # allow packet capture
netbird service status / start / stop / restart / uninstall
netbird service reset-params

Profiles (multi-account)

netbird profile list                 # show profiles
netbird profile switch <name>        # switch account

Global Flags

Troubleshooting

• Peer shows idle/connecting → netbird status -d, check connection type (P2P vs Relayed). Relayed = NAT traversal failed, traffic via relay service (still encrypted).
• Registration fails with setup key → key expired or used up (one-off vs reusable). Check dashboard; netbird up --setup-key fresh key.
• Can't reach a resource → netbird networks list — is the network selected? Policy must allow your group. Resource reachable ≠ routing peer itself reachable (needs separate peer-to-peer policy).
• DNS issues → netbird up --disable-dns to isolate; check netbird status -d DNS state.
• Need support bundle → netbird debug bundle FIRST, then reproduce.
• v0.75.1 security advisory — versions 0.5.0–0.75.1 had a local privilege escalation via the unauthenticated daemon socket (GHSA-qcpp-8vwj-hhwr). Upgrade clients; don't expose the daemon socket to untrusted local users.

Common Mistakes

• logout vs down — down just disconnects; deregister/logout removes the peer from the network (re-registration needed).
• Interactive netbird up on a server — SSO login expires. Use --setup-key for always-on gateways/routing peers.
• netbird expose ≠ route — expose is the reverse proxy (public internet); routes/networks are for private overlay. Don't mix them up in docs/automation.
• Forgetting -n on networks select — default is REPLACE mode; -a appends. select all is the way to accept everything.
• Editing /etc/netbird config directly — client is daemon-managed; use flags + service reconfigure, not hand-edited config.