netbird login

Overview

The netbird login command authenticates your device with the NetBird management server without establishing network connections. Use this to authenticate before connecting with netbird up.

netbird login [flags]

Description

This command performs authentication only:

Initiates SSO authentication flow (if no setup key provided)
Validates credentials with the management server
Stores authentication tokens locally
Does NOT bring up the WireGuard interface
Does NOT establish peer connections

Use netbird up after login to connect to the network, or use netbird up directly (which includes login if needed).

You want to authenticate without connecting immediately
Pre-authenticating in preparation for later connection
Testing authentication credentials
Separating authentication from connection in automation scripts

Use `netbird up` when:

You want to authenticate AND connect in one step (most common)
Starting NetBird for normal use

Flags

string

Profile name to use for the login. If not specified, the last used profile will be used.

boolean

default:"false"

Do not open the browser for SSO loginWhen enabled, displays the authentication URL for manual browser access. Useful for:

Headless servers
SSH sessions
Automated environments
Remote systems

All global flags are also available, including:

--setup-key - Authenticate with a setup key instead of SSO
--management-url - Specify management server URL
--hostname - Set custom hostname

Examples

netbird login

Output:

Please do the SSO login in your browser.
If your browser didn't open automatically, use this URL to log in:

https://auth.netbird.io/activate?user_code=ABCD-EFGH

Logging successfully

For servers or SSH sessions:

netbird login --no-browser

Output:

Use this URL to log in:

https://auth.netbird.io/activate?user_code=ABCD-EFGH and enter the code ABCD-EFGH to authenticate.

Logging successfully

Open the URL on another device to complete authentication. Non-interactive authentication using a setup key:

netbird login --setup-key YOUR_SETUP_KEY

Output:

Logging successfully

netbird login --management-url https://management.example.com

netbird login --hostname my-server-01

netbird login --profile work

Environment Variable Authentication

Use environment variables for automation:

export NB_SETUP_KEY="your-setup-key"
export NB_MANAGEMENT_URL="https://management.example.com"
netbird login

Authentication Methods

SSO (Single Sign-On)

Default authentication method for interactive sessions: Supported SSO Providers:

Google
Microsoft Azure AD / Entra ID
Okta
Auth0
Keycloak
Other OIDC providers

Flow:

Run netbird login
Browser opens to SSO provider
Login with your SSO credentials
Browser redirects back with success message
NetBird stores authentication token

Headless SSO:

netbird login --no-browser

Copy the displayed URL to a browser on any device.

Setup Key

Non-interactive authentication for automation:

netbird login --setup-key YOUR_SETUP_KEY

Setup key features:

Created in Management Dashboard
Can be reusable or one-time use
Can have expiration dates
Can auto-assign to groups
Ideal for scripting and automation

Generate setup keys:

Log into NetBird Management Dashboard
Navigate to Setup Keys
Click “Add Key”
Configure key properties
Copy the generated key

See: Register Machines Using Setup Keys

Daemon Mode (Default)

When the NetBird daemon is running:

netbird service start
netbird login

Authentication is handled by the daemon service.

Foreground Mode

Without daemon (standalone authentication):

netbird login

If log files are not configured, runs in standalone mode.

Profile Management

NetBird supports multiple profiles for different networks or accounts:

netbird login --profile work

If currently connected, will disconnect first:

netbird login --profile personal

Profiles are created automatically on first login:

netbird login --profile new-profile --setup-key YOUR_KEY

For profile management, use the --profile flag

Status Messages

Logging successfully - Authentication completed successfully
login failed - Authentication failed (check credentials or setup key)
failed to connect to daemon - NetBird daemon not running
NeedsSSOLogin - SSO authentication required

Common Issues

Daemon Not Running

failed to connect to daemon error: connection refused
If the daemon is not running please run:
netbird service install
netbird service start

Solution:

netbird service install
netbird service start
netbird login

Browser Not Opening

If browser doesn’t open automatically:

Copy the displayed URL
Open it manually in a browser
Complete authentication

Or use --no-browser explicitly:

netbird login --no-browser

Invalid Setup Key

login failed: invalid setup key

Causes:

Key has expired
Key was deleted
Key is one-time use and already consumed
Typo in key value

Solution: Generate a new setup key in the Management Dashboard

Authentication Timeout

If SSO authentication times out:

Run netbird login again
Complete authentication more quickly
Check network connectivity

Session Already Exists

If already logged in:

netbird logout
netbird login

Security Considerations

Token Storage

Authentication tokens are stored securely in:

Linux: /etc/netbird/config.json
macOS: /etc/netbird/config.json
Windows: %PROGRAMDATA%\Netbird\config.json

Permissions:

File should be readable only by root/administrator
Contains sensitive authentication data
Do not share or commit to version control

Setup Key Security

Best practices:

Use one-time keys for automated provisioning
Set expiration dates on keys
Delete unused keys
Use different keys for different environments
Never commit keys to source control
Use environment variables or secret managers

Environment variable example:

# In CI/CD pipeline
export NB_SETUP_KEY="$NETBIRD_SETUP_KEY"
netbird login

Automation Examples

Docker/Container Init

FROM ubuntu:22.04

# Install NetBird
RUN curl -sSL https://pkgs.netbird.io/install.sh | bash

# Login script
COPY entrypoint.sh /entrypoint.sh
RUN chmod +x /entrypoint.sh

ENTRYPOINT ["/entrypoint.sh"]

#!/bin/bash
# entrypoint.sh
netbird login --setup-key "$NETBIRD_SETUP_KEY" --hostname "$HOSTNAME"
netbird up
exec "$@"

CI/CD Pipeline

# GitHub Actions example
- name: Connect to NetBird
  env:
    NB_SETUP_KEY: ${{ secrets.NETBIRD_SETUP_KEY }}
    NB_HOSTNAME: "ci-runner-${{ github.run_id }}"
  run: |
    curl -sSL https://pkgs.netbird.io/install.sh | bash
    netbird login
    netbird up

Terraform/Ansible

# Terraform cloud-init
resource "aws_instance" "app" {
  user_data = <<-EOF
    #!/bin/bash
    curl -sSL https://pkgs.netbird.io/install.sh | bash
    export NB_SETUP_KEY="${var.netbird_setup_key}"
    netbird service install
    netbird service start
    netbird login
    netbird up
  EOF
}

Commands

Overview

Description

Use `netbird up` when:

Flags

Examples

Environment Variable Authentication

Authentication Methods

SSO (Single Sign-On)

Setup Key

Daemon Mode (Default)

Foreground Mode

Profile Management

Status Messages

Common Issues

Daemon Not Running

Browser Not Opening

Invalid Setup Key

Authentication Timeout

Session Already Exists

Security Considerations

Token Storage

Setup Key Security

Automation Examples

Docker/Container Init

CI/CD Pipeline

Terraform/Ansible

See Also

​Overview

​Description

​When to Use Login vs Up

​Use netbird login when:

​Use netbird up when:

​Flags

​Examples

​Interactive SSO Login

​Login Without Browser (Headless)

​Login with Setup Key

​Login to Self-Hosted Management Server

​Login with Custom Hostname

​Login to Specific Profile

​Environment Variable Authentication

​Authentication Methods

​SSO (Single Sign-On)

​Setup Key

​Login Flow

​Daemon Mode (Default)

​Foreground Mode

​Profile Management

​Login to Specific Profile

​Switch Profile During Login

​Create Profile and Login

​Status Messages

​Common Issues

​Daemon Not Running

​Browser Not Opening

​Invalid Setup Key

​Authentication Timeout

​Session Already Exists

​Security Considerations

​Token Storage

​Setup Key Security

​Automation Examples

​Docker/Container Init

​CI/CD Pipeline

​Terraform/Ansible

​See Also

Overview

Description

When to Use Login vs Up

Use `netbird login` when:

Use `netbird up` when:

Flags

Examples

Interactive SSO Login

Login Without Browser (Headless)

Login with Setup Key

Login to Self-Hosted Management Server

Login with Custom Hostname

Login to Specific Profile

Environment Variable Authentication

Authentication Methods

SSO (Single Sign-On)

Setup Key

Login Flow

Daemon Mode (Default)

Foreground Mode

Profile Management

Login to Specific Profile

Switch Profile During Login

Create Profile and Login

Status Messages

Common Issues

Daemon Not Running

Browser Not Opening

Invalid Setup Key

Authentication Timeout

Session Already Exists

Security Considerations

Token Storage

Setup Key Security

Automation Examples

Docker/Container Init

CI/CD Pipeline

Terraform/Ansible

See Also