Netzilo client command-line interface (CLI)

Installing the Netzilo client adds a binary called netzilo. It runs as the service that connects the device to your Netzilo network, and it is also the command-line tool that controls that service. This page lists every command and flag of the current client.

The service is named Netzilo on Linux (systemd), macOS (launchd) and Windows. The CLI reaches it through unix:///var/run/netzilo.sock on Linux and macOS and tcp://127.0.0.1:40836 on Windows.

Syntax

netzilo [command] [subcommand] [flags]

• Commands: up, login, down, status, refresh, routes, ssh, service, debug, hook, deploy-user, version.
• Subcommands: for example service install|uninstall|start|stop|restart|run and routes list|select|deselect.
• Flags: global flags work with every command; others belong to one command. netzilo <command> --help prints them.

Privileges. On Linux and macOS the daemon socket is open to every local user, so most commands work without sudo. service, ssh and a foreground up -F with a network interface need root. On Windows, run service and ssh from an elevated terminal.

Global flags

Environment variables

Every flag can also be set as an environment variable: the prefix NB_, the flag name in upper case, and dashes replaced by underscores. The legacy prefix WT_ is still read; NB_ wins.

export NB_CONFIG="/opt/netzilo/config.json"
export NB_MANAGEMENT_URL="https://netzilo.example.com"
netzilo up

More variables are listed in Other environment variables.

Commands

up

Registers the device if needed, signs it in and connects. Without a setup key or access token, it starts an SSO sign-in: it prints Please do the SSO login in your browser. and a URL, and on a machine without a desktop also a code. If the client is already connected, it prints Already connected.

Flags you pass to up are saved in config.json. A logout rewrites that file with only the management and dashboard addresses, so pass the flags again at the next up, or bake global flags into the service with netzilo service install.

# Netzilo Cloud, SSO sign-in
netzilo up

# Self-hosted server
netzilo up --management-url https://netzilo.example.com

# Server or container with a setup key
netzilo up --setup-key AAAA-BBB-CCC-DDDDDD

login

Signs the device in without connecting. It takes the same sign-in options as up: --setup-key, --pat and --management-url.

netzilo login --setup-key AAAA-BBB-CCC-DDDDDD --management-url https://netzilo.example.com

down

Disconnects and logs the device out. It removes the tunnel, restores DNS, routes and firewall settings, signs the device out of the management server, deletes the session token and resets the WireGuard keys. The next up registers the device again. There is no way to stop the client without logging out.

netzilo down

status

Shows the state of the client and its connections.

netzilo status

The output looks like this:

OS: linux/amd64
Daemon version: 4.4.375
CLI version: 4.4.375
Management: Connected
Signal: Connected
Relays: 2/2 Available
Nameservers: 1/1 Available
FQDN: build-server.netzilo.network
Netzilo IP: 100.64.12.7/16
Interface type: Kernel
Quantum resistance: false
Routes: -
Peers count: 2/3 Connected

netzilo status -d adds a block for each peer:

 Peer:
  Netzilo IP: 100.64.20.4
  Status: Connected
  -- detail --
  Connection type: P2P
  Direct: true
  ICE candidate (Local/Remote): host/host
  Last connection update: 26 seconds ago
  Last WireGuard handshake: 25 seconds ago
  Transfer status (received/sent) 2.0 KiB/355 B
  Quantum resistance: false
  Routes: 10.0.0.0/24
  Latency: 20.14ms

• Connection type: P2P means a direct tunnel. Relayed means traffic goes through a relay because direct UDP is blocked; it works with higher latency.
• ICE candidate types are host, srflx, prflx and relay.
• When the device is not signed in, the output is Daemon status: NeedsLogin (or LoginFailed) with the command to run.

refresh

Fetches the network map now instead of waiting for the next sync (about 30 seconds). It sends the current device posture, applies the returned policies, routes and DNS, and never logs the device out. It does not rebuild tunnels that are already up.

netzilo refresh

It prints failed to refresh: client is not connected when the client is down.

routes

Chooses which routes this device uses when several routes cover the same network.

netzilo routes list                 # ID, network or domains, Selected / Not Selected
netzilo routes select <id> [<id>…]  # use these routes only
netzilo routes select <id> -a       # add to the current selection
netzilo routes select all
netzilo routes deselect <id>|all

The tray app has the same choice under Network Routes.

ssh

Opens an SSH shell on another peer over the tunnel.

sudo netzilo ssh [user@]host [-p 44338]

• Needs root (Administrator on Windows). The default user is root; the user must exist on the target.
• The target needs both netzilo up --allow-server-ssh and SSH Access turned on for the peer in the dashboard.
• The SSH server listens on the peer's Netzilo IP, TCP 44338. Only interactive shells are supported; no file copy or port forwarding.

version

netzilo version
4.4.375

service

Manages the OS service. Run it as root or from an elevated terminal.

sudo netzilo service install --log-level debug
sudo netzilo service start

debug

Collects diagnostics.

For a problem on a device you cannot sign in again yourself, raise the level and bundle instead of using debug for:

netzilo debug log level debug
# reproduce the problem
sudo netzilo debug bundle
netzilo debug log level info

hook

Installs, removes or checks the hooks that send coding-agent actions to the local client for evaluation.

netzilo hook install --framework=claude-code
netzilo hook verify --framework=claude-code
netzilo hook uninstall --framework=claude-code

--framework is claude-code, codex, gemini or openclaw. --url overrides the evaluation endpoint, http://localhost:41336/evaluate by default. See Coding Agents.

deploy-user

Creates a user and an access token for it, and stores the token on the device so that netzilo up signs in with it. Use it for headless devices that must act as a user.

netzilo deploy-user --fullname "Build Agent 01" --email build01@example.com \
  --groups "Agents" --tokenname build01 --tokenexp 180 \
  --servicetoken nzl_<token> --apiurl https://netzilo.example.com
netzilo up

Other environment variables

There is no environment variable for connection-setup (ICE) detail. Those lines appear in the client log at level debug; use netzilo debug log level debug.

Where the service reads its variables. Variables in your shell reach only a foreground run. The service reads its own environment, and a change takes effect at the next service start, which logs the device out.

• Linux: a systemd drop-in. Run sudo systemctl edit Netzilo and add [Service] and Environment=NB_FORCE_WS=1.

• macOS: an EnvironmentVariables dictionary in /Library/LaunchDaemons/Netzilo.plist.

• Windows: the Environment value (REG_MULTI_SZ, one NAME=value per line) at HKLM\SYSTEM\CurrentControlSet\Services\Netzilo:

  reg add HKLM\SYSTEM\CurrentControlSet\Services\Netzilo /v Environment /t REG_MULTI_SZ /d "NB_FORCE_WS=1" /f
  

  CopyCopied!

Files

On Windows, %PROGRAMDATA%\Netzilo Client holds the program files and %PROGRAMDATA%\Netzilo holds configuration, tokens and logs. A non-admin install has no service: a per-user client runs in userspace mode with %PROGRAMDATA%\netzilo\usservice<N>.json and .log, on per-user ports.

Logs rotate at 5 MB, keep 10 files for 30 days and are compressed.

Tray app

The tray app (netzilo-ui) menu: status line, Connect, Disconnect, Refresh, Record Session (Windows), Admin Panel, Workspaces (Windows: Terminate All, Reset Contents), Network Routes, Advanced (Allow SSH, Connect on Startup, Enable Quantum-Resistance, Server Settings), Support (Collect Data, Open Logs Folder), Version and Quit.

When the login expires, the app shows Netzilo Session Expired and netzilo status shows NeedsLogin. Click Connect or run netzilo up to sign in again.

Related Documentation

• Install Netzilo - install and enrol the client on every platform
• Troubleshooting client issues - read netzilo status and the log by symptom
• Report bugs and issues - collect and redact a debug bundle
• Enable post-quantum cryptography - Rosenpass flags
• Routes - the routes netzilo routes selects from