Skip to main content
The NetBird CLI provides a powerful command-line interface for managing your NetBird network connections, peers, and services.

​
Installation

The netbird CLI is automatically installed with the NetBird client. See the installation guide for platform-specific instructions.

​
Basic Usage

netbird [command] [flags]

​
Available Commands

  • netbird up - Connect to the NetBird network
  • netbird down - Disconnect from the NetBird network
  • netbird status - Display connection status and peer information
  • netbird login - Authenticate with the management server
  • netbird logout - Log out from the NetBird network
  • netbird service - Manage the NetBird daemon service
  • netbird networks (alias: routes) - Manage network routes and resources
  • netbird ssh - Connect to NetBird peers via SSH
  • netbird version - Display version information

​
Global Flags

These flags can be used with any command:
​
--daemon-addr
string
Daemon service address for CLI requests. Format: [unix|tcp]://[path|host:port]
​
--management-url
string
default:"https://api.netbird.io"
Management Service URL. Format: [http|https]://[host]:[port]Short form: -m
​
--admin-url
string
default:"https://app.netbird.io"
Admin Panel URL. Format: [http|https]://[host]:[port]
​
--log-level
string
default:"info"
Sets NetBird log level. Options: trace, debug, info, warn, errorShort form: -l
​
--log-file
string
default:"/var/log/netbird/client.log"
Sets NetBird log file paths. Can be specified multiple times or as comma-separated list.Special values:
  • console - Output to stdout
  • syslog - Send to syslog daemon
​
--setup-key
string
Setup key obtained from the Management Service Dashboard (used to register peer)Short form: -k
​
--setup-key-file
string
Path to a file containing the setup key. Ignored if --setup-key is provided.
​
--hostname
string
Sets a custom hostname for the deviceShort form: -n
​
--preshared-key
string
Sets WireGuard PreSharedKey property. If set, only peers with the same key can communicate.
​
--anonymize
boolean
default:"false"
Anonymize IP addresses and non-netbird.io domains in logs and status outputShort form: -A
​
--config
string
default:"/etc/netbird/config.json"
Overrides the default profile file locationShort form: -cDefault paths:
  • Linux/FreeBSD: /etc/netbird/config.json
  • macOS: /etc/netbird/config.json
  • Windows: %PROGRAMDATA%\Netbird\config.json
​
--service
string
default:"netbird (Windows: Netbird)"
NetBird system service nameShort form: -s

​
Environment Variables

All flags can be set via environment variables using the NB_ or WT_ prefix (for backwards compatibility):
  • Flag names are converted to uppercase
  • Dashes are replaced with underscores
  • Prefixed with NB_ or WT_
Examples: 
# Set management URL
export NB_MANAGEMENT_URL="https://management.example.com"

# Set log level
export NB_LOG_LEVEL="debug"

# Set setup key
export NB_SETUP_KEY="your-setup-key-here"

# Disable browser for SSO
export NB_NO_BROWSER=true

​
Configuration File

The NetBird configuration file is stored at:
  • Linux/FreeBSD: /etc/netbird/config.json
  • macOS: /etc/netbird/config.json
  • Windows: %PROGRAMDATA%\Netbird\config.json
This file contains:
  • Management server URL
  • Private key
  • WireGuard interface configuration
  • Network settings
  • SSH settings
The configuration file contains sensitive information including your private key. Ensure proper file permissions are set.

​
Daemon Socket

The NetBird CLI communicates with the NetBird daemon service via:
  • Linux/macOS: Unix socket at /var/run/netbird.sock
  • Windows: TCP socket at 127.0.0.1:41731
Most commands require the daemon to be running: 
netbird service install
netbird service start

​
Exit Codes

  • 0 - Success
  • 1 - General error
  • Non-zero - Command-specific error

​
Getting Help

Get help for any command: 
netbird --help
netbird [command] --help

​
Examples

Connect to NetBird network: 
netbird up
Connect with a setup key: 
netbird up --setup-key YOUR_SETUP_KEY
Check connection status: 
netbird status
View detailed status: 
netbird status --detail
Disconnect from network: 
netbird down

Build docs developers (and LLMs) love

Get started for freeTalk to us