NetBird Agent command line interface (CLI)

The NetBird client installation adds a binary called netbird to your system. This binary runs as a daemon service to connect your computer or server to the NetBird network as a peer. But it can also be used as a client to control the daemon service.

This section will explore the commands available in netbird.

Syntax

Use the following syntax to run netbird commands from your terminal window:

netbird [command] [subcommand] [flags]

command: Specifies the operation that you want to perform or a top-level command: up, login, down, status, ssh, expose, networks, profile, debug, service, and version
subcommand: Specifies the operation to be executed for a top-level command like service: install, uninstall, start, and stop
flags: Specifies optional flags. For example, you can use the --setup-key flag to specify the setup key to be used in the commands login and up

To see detailed command information, use the flag --help after each command

Flag value syntax

Boolean flags that default to false can be enabled by simply passing the flag: --block-inbound.
Boolean flags that default to true must use =false to disable: --strict-host-key-checking=false, --network-monitor=false.
String flags that support clearing a previous value accept an empty string: --dns-resolver-address "".

Configuration precedence

This is the CLI configuration precedence (highest to lowest priority):

environment variables (eg: NB_WIREGUARD_PORT)
command line flags (eg: --wireguard-port)
configuration file entries <profile>.json (formerly: config.json), eg: WgPort key

We are preserving the unusual priority of environment variables for backwards compatibility with existing deployments.

Global flags

netbird has a set of global flags that are available in every command. They specify settings that are core or shared between two or more commands, e.g. --setup-key is used by login and up to authenticate the client against a management service.

Below is the list of global flags:

      --admin-url string        Admin Panel URL [http|https]://[host]:[port] (default "https://app.netbird.io:443")
  -A, --anonymize               anonymize IP addresses and non-netbird.io domains in logs and status output
  -c, --config string           Overrides the default profile file location. Deprecated on `up` and `login`; use `--service-env NB_CONFIG=<path>` instead.
      --daemon-addr string      Daemon service address to serve CLI requests [unix|tcp]://[path|host:port] (default "unix:///var/run/netbird.sock")
  -n, --hostname string         Sets a custom hostname for the device
      --log-file console        Sets NetBird log paths written to simultaneously. If "console" is specified the log will be output to stdout. If "syslog" is specified the log will be sent to the syslog daemon. You can pass the flag multiple times or separate entries by comma (default [/var/log/netbird/client.log])
  -l, --log-level string        Sets NetBird log level (default "info")
  -m, --management-url string   Management Service URL [http|https]://[host]:[port] (default "https://api.netbird.io:443")
      --preshared-key string    Sets WireGuard PreSharedKey property. If set, then only peers that have the same key can communicate.
  -s, --service string          NetBird system service name (default "netbird")
  -k, --setup-key string        Setup key obtained from the Management Service Dashboard (used to register peer)
      --setup-key-file string   Path to a file containing a setup key (used to register peer). Ignored if --setup-key is provided.

Environment Variables

Every flag of a netbird command can be passed as an environment variable. We are using the following rule for the environment variables composition:

PREFIX_FLAGNAME and for flags with multiple parts: PREFIX_FLAGNAMEPART1_FLAGNAMEPART2
The prefix is always NB
The flag parts are separated by a dash ("-") when passing as flags and with an underscore ("_") when passing as an environment variable

For example, let's check how we can pass --config and --management-url as environment variables:

export NB_CONFIG="/opt/netbird/config.json"
export NB_MANAGEMENT_URL="https://api.self-hosted.com:443"
netbird up

The up command would process the variables, read the configuration file on /opt/netbird/config.json and attempt to connect to the management service running at https://api.self-hosted.com:443.

Here are some additional examples of environment variables:

# Disable profiles feature
export NB_DISABLE_PROFILES=true

# Disable update settings functionality
export NB_DISABLE_UPDATE_SETTINGS=true

# Set custom log level
export NB_LOG_LEVEL=debug

# Set custom daemon address
export NB_DAEMON_ADDR="tcp://localhost:8080"

Beyond flag-derived variables, the client also supports a number of advanced environment variables for tuning networking, firewall, ICE connectivity, and more. See the Client Environment Variables reference for the full list.

Commands

up

Single command to log in and start the NetBird client. It can send a signal to the daemon service or run in the foreground with the flag --foreground-mode.

The command will check if the peer is logged in and connect to the management service. If the peer is not logged in, by default, it will attempt to initiate an SSO login flow.

Flags

      --allow-server-ssh                    Allow SSH server on peer
      --block-inbound                       Block inbound connections. If enabled, the client will not allow any inbound connections to the local machine nor routed networks. This overrides any policies received from the management service.
      --block-lan-access                    Block access to local networks (LAN) when using this peer as a router or exit node
      --disable-auto-connect                Disables auto-connect feature. If enabled, then the client won't connect automatically when the service starts.
      --disable-client-routes               Disable client routes. If enabled, the client won't process client routes received from the management service.
      --disable-dns                         Disable DNS. If enabled, the client won't configure DNS settings.
      --disable-firewall                    Disable firewall configuration. If enabled, the client won't modify firewall rules.
      --disable-ipv6                        Disable IPv6 overlay. If enabled, the client won't request or use an IPv6 overlay address.
      --disable-server-routes               Disable server routes. If enabled, the client won't act as a router for server routes received from the management service.
      --disable-ssh-auth                    Disable SSH JWT authentication. If enabled, any peer with network access can connect without user authentication.
      --dns-resolver-address string         Sets a custom address for NetBird's local DNS resolver. If set, the agent won't attempt to discover the best IP and port to listen on. An empty string "" clears the previous configuration. E.g. --dns-resolver-address 127.0.0.1:5053 or --dns-resolver-address ""
      --dns-router-interval duration        DNS route update interval (default 1m0s)
      --enable-lazy-connection              [Experimental] Enable the lazy connection feature. If enabled, the client will establish connections on-demand. Note: this setting may be overridden by management configuration.
      --enable-rosenpass                    [Experimental] Enable Rosenpass feature. If enabled, the connection will be post-quantum secured via Rosenpass.
      --enable-ssh-local-port-forwarding    Enable local port forwarding for SSH server
      --enable-ssh-remote-port-forwarding   Enable remote port forwarding for SSH server
      --enable-ssh-root                     Enable root login for SSH server
      --enable-ssh-sftp                     Enable SFTP subsystem for SSH server
      --external-ip-map strings             Sets external IPs maps between local addresses and interfaces. You can specify a comma-separated list with a single IP and IP/IP or IP/Interface Name. An empty string "" clears the previous configuration. E.g. --external-ip-map 12.34.56.78/10.0.0.1 or --external-ip-map 12.34.56.200,12.34.56.78/10.0.0.1,12.34.56.80/eth1 or --external-ip-map ""
      --extra-dns-labels strings            Sets DNS labels. You can specify a comma-separated list of up to 32 labels. An empty string "" clears the previous configuration. E.g. --extra-dns-labels vpc1 or --extra-dns-labels vpc1,mgmt1 or --extra-dns-labels ""
      --extra-iface-blacklist strings       Extra list of default interfaces to ignore for listening
  -F, --foreground-mode                     Start service in foreground
      --interface-name string               WireGuard interface name (default "wt0")
      --mtu uint16                          Set MTU (Maximum Transmission Unit) for the WireGuard interface (default 1280)
  -N, --network-monitor                     Manage network monitoring. Defaults to true on Windows and macOS, false on Linux and FreeBSD. E.g. --network-monitor=false to disable or --network-monitor=true to enable.
      --no-browser                          Do not open the browser for SSO login
      --profile string                      Profile name to use for the login. If not specified, the last used profile will be used.
      --rosenpass-permissive                [Experimental] Enable Rosenpass in permissive mode to allow this peer to accept WireGuard connections without requiring Rosenpass functionality from peers that do not have Rosenpass enabled.
      --ssh-jwt-cache-ttl int               SSH JWT token cache TTL in seconds (default 0, disabled). When enabled, the client caches the JWT so repeated SSH connections skip the OIDC login flow. The receiving SSH server rejects tokens older than 10 minutes, so values above 600 will result in authentication failures for cached tokens.
      --wireguard-port uint16               WireGuard interface listening port (default 51820)