agentleFS
Aidas-devAidas-dev/k8s-agent-skills/skills/netbird-cli/SKILL.md

netbird-cli

Skill4 starsChanged 5 months agoMITView on GitHub

NetBird client CLI — install, connect (up/down), status, networks, reverse proxy (expose), SSH, Kubernetes access, and debugging. Commands verified against v0.76.x.

  • Installs packages

The file

Files
SKILL.md

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

CommandPurpose
netbird upConnect (WireGuard up, connect to management, establish P2P)
netbird up --disable-dnsConnect without DNS config
netbird up --disable-firewallWithout firewall rule changes
netbird up --disable-ipv6Without IPv6 overlay
netbird up --block-inboundNo inbound connections (overrides policies)
netbird up --enable-rosenpass[Experimental] Post-quantum security
netbird downDisconnect everything
netbird deregister / netbird logoutDeregister peer from management (REMOVES from network)

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

CommandPurpose
netbird debug bundleCollect full debug bundle (logs, config, status)
netbird debug capturePacket capture on the WireGuard interface
netbird debug configDump effective configuration
netbird debug logManage daemon logging
netbird debug traceTrace a packet through the firewall
netbird debug for <duration>Run debug logs for a duration, bundle
netbird forwarding listList forwarding rules

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

FlagPurpose
-k, --setup-key / --setup-key-fileSetup key for registration
-m, --management-urlManagement URL (default https://api.netbird.io:443)
--admin-urlAdmin panel URL (default https://app.netbird.io:443)
-n, --hostnameCustom hostname for the device
--preshared-keyWireGuard PreSharedKey (only same-key peers can communicate)
-l, --log-levelLog level (default info)
-A, --anonymizeAnonymize IPs/non-netbird domains in logs/status
-c, --configOverride profile file location

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.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.