NetBird client — connect, disconnect, status and network management (CLI and GUI)

Overview

• This document describes the most common NetBird client operations: bring the client up and down, check status, and enable/disable networks. It covers both the command-line interface (CLI) and the graphical user interface (GUI) on Windows, macOS and Linux, plus common service and troubleshooting commands.

Command-line (recommended for scripting, servers and advanced users)

  netbird login

  netbird logout

  netbird up

  netbird down

  netbird status

• Basic session and service control
• Log in (first-time authorisation):
• Log out:
• Start the client (bring the NetBird interface up):
• Stop the client (tear down interfaces):
• Show current client state, peers, assigned IPs and active networks:

  netbird networks list

  netbird networks enable <network-id>

  netbird networks disable <network-id>

• Network listing and enable/disable
• List known networks (shows network IDs needed for enable/disable):
• Enable (join) a network by its ID:
• Disable (leave) a network by its ID:
• Notes:
• Use the netbird networks list output to obtain the <network-id> value.
• Enabling a network provisions routes and peer access for that network to the local host; disabling removes those routes.

  sudo systemctl start netbird
  sudo systemctl stop netbird
  sudo systemctl restart netbird
  sudo systemctl status netbird
  sudo journalctl -u netbird -f

• Service control on systemd Linux hosts
• Use journalctl -u netbird -f to follow live logs while troubleshooting.

  brew services start netbird
  brew services stop netbird
  brew services restart netbird

• macOS with Homebrew (if installed as a service)

  Get-Service -Name "netbird"

• Windows service (PowerShell example to view service state)
• Use the Windows tray GUI (below) for start/stop if the service name differs.

GUI (Windows, macOS, Linux desktop)

• Common UI concepts
• The NetBird GUI exposes a main connect/disconnect control, a status area (Connected / Disconnected / Authentication required / Healthy), and a Networks or Organisations view listing available networks and their enable/disable toggles.
• The tray (Windows), menu bar (macOS) or system tray / notification area (Linux) is the usual place to open the UI.

• Windows
• Open the NetBird app from the system tray (right-hand side of taskbar).
• Authenticate using Sign in or Login if not already authorised.
• Connect / Disconnect:
• Use the main Connect toggle or button in the app to bring the client up or down.
• Networks:
• Open the Networks or Organisation tab.
• Enable or disable a network using the toggle next to the network name (or use the three-dot menu for per-network actions such as Join/Leave).
• Settings:
• Advanced or Settings → Management URL can be used for corporate deployments that require a custom management endpoint.

• macOS
• Click the NetBird icon in the menu bar and open the application window.
• Use the Connect toggle to start/stop the client.
• Use the Networks tab to enable/disable networks using per-network toggles or menu items.

• Linux (desktop)
• Use the system tray / application menu to open the NetBird UI (application name NetBird).
• Use the Connect toggle to bring the client up or down.
• Use the Networks section to enable/disable networks as with other platforms.

Interpreting status and expected behaviour

• netbird status or the GUI status should show:
• Authentication state (signed in / authorised).
• Connection state (Connected / Disconnected).
• Assigned IP addresses for the client.
• Active networks (which networks are enabled).
• Peer list (other machines visible to this client).
• Enabling a network typically creates WireGuard routes and makes peers and services from that network reachable. Disabling removes those routes.

Common troubleshooting steps

  netbird down
  netbird up

  sudo systemctl restart netbird
  sudo journalctl -u netbird -f

• Quick restart (CLI):
• Restart the service (Linux systemd):
• Check connectivity and authentication:
• Confirm netbird status shows the client is authorised and connected.
• Confirm system firewall or local policy is not blocking WireGuard/UDP traffic or the NetBird service.
• Confirm network membership:
• Use netbird networks list to make sure the desired network is available, and netbird networks enable <network-id> to join it if required.
• Logs:
• Use journalctl -u netbird -f on systemd systems to follow logs; use the GUI log view where provided on desktop clients.

Best practices and notes

• Always run netbird login and finish authorisation before attempting to up the client.
• Use the CLI for automation and servers; use the GUI for desktop convenience.
• Changing network enable/disable in the GUI or via CLI updates the daemon state; a restart is rarely required but may help after major changes.
• Keep the NetBird client up to date through the OS package manager or the official installers.

See also

• FAQ #337: Client Install - Windows
• FAQ #338: Client Install - Debian (and downstreams)
• FAQ #344: Onboarding