Configuration Reference

NDCLI uses a YAML configuration file and supports environment variable overrides. This reference covers all configuration options.

Configuration File Location

macOS

~/Library/Application Support/ndcli/config.yaml

Linux

~/.config/ndcli/config.yaml

Windows

%APPDATA%\ndcli\config.yaml

Use --conf to specify a custom config file path:

ndcli --conf /path/to/config.yaml device list

Configuration File Structure

oauth2:
  provider: netdefense
  domain: auth.netdefense.io
  client_id: your-client-id
  audience: authcli
  scopes: openid profile email offline_access

controlplane:
  host: https://control.netdefense.io
  ssl_verify: true

organization:
  name: my-organization

output:
  format: detailed
  timezone: America/Sao_Paulo

auth:
  storage: keyring
  account: user@example.com
  path: ""

Configuration Options

OAuth2 Settings

Settings for OAuth2 authentication provider.

Key	Type	Default	Description
oauth2.provider	string	(built-in)	OAuth2 provider type
oauth2.domain	string	auth.netdefense.io	OAuth2 domain
oauth2.client_id	string	(built-in)	OAuth2 client ID
oauth2.audience	string	authcli	OAuth2 audience
oauth2.scopes	string	openid profile email offline_access	OAuth2 scopes

Note

OAuth2 settings are typically pre-configured. Only modify if using a custom authentication setup.

Control Plane Settings

Settings for the NetDefense API connection.

Key	Type	Default	Description
controlplane.host	string	https://control.netdefense.io	API host URL
controlplane.ssl_verify	bool	true	Verify SSL certificates

This default is compiled into the binary and is the same in every ndcli build — there is no separate development default. A fresh install with no config.yaml writes one containing host: https://control.netdefense.io.

It is also a different hostname from the one the device-side agent uses, by design. See Service Endpoints for every NetDefense hostname and which component talks to which.

Custom API Host

To use a different API host (e.g., self-hosted or staging):

controlplane:
  host: https://control.example.com
  ssl_verify: true

Caution

Only set ssl_verify: false for development/testing environments with self-signed certificates.

PathFinder Settings

The relay that carries remote access sessions opened with ndcli device connect. Note the wss:// scheme — this is a WebSocket endpoint, not the HTTPS API host above.

Key	Type	Default	Description
pathfinder.host	string	wss://pathfinder.netdefense.io	PathFinder relay URL
pathfinder.ssl_verify	bool	true	Verify SSL certificates

The device has its own copy of this setting, configured separately in the OPNsense plugin. Both ends must point at the same relay — see Service Endpoints.

Organization Settings

Default organization for commands.

Key	Type	Default	Description
organization.name	string	""	Default organization name

Set via command:

ndcli config set org my-organization

Override per-command:

ndcli device list --org other-organization

Output Settings

Output formatting preferences.

Key	Type	Default	Description
output.format	string	detailed	Default output format
output.timezone	string	(system local)	IANA timezone used to render timestamps and to read --at values typed without an offset

Valid formats:

Format	Description
table	Tabular format, good for lists
simple	Compact bullet-point format
detailed	Rich Unicode box drawing
json	Machine-readable JSON

Set via command:

ndcli config set output json

ndcli config set timezone America/Sao_Paulo

Override the format per-command:

ndcli device list -f table

Authentication Storage

Settings for credential storage.

Key	Type	Default	Description
auth.storage	string	keyring	Storage backend: keyring or file
auth.account	string	""	Account email for keyring lookup
auth.path	string	""	Custom path for file storage

Changing the storage backend

There is no ndcli config set auth.storage — config set only accepts org, output and timezone. Two routes work instead.

Edit config.yaml by hand and add a nested auth block:

auth:
  storage: file

Or set the environment variable, which takes precedence over the file and is the easier option for a single command, a container, or a CI job:

export NDCLI_AUTH_STORAGE=file

Caution

In the file, write it nested, as above. If NDCLI prints a warning that mentions auth.storage: file, that is the dotted key name it uses internally, not a line you can paste into config.yaml — a flat auth.storage: file line creates a key literally named auth.storage, which NDCLI never reads. The dotted form is only meaningful as the environment variable NDCLI_AUTH_STORAGE, which the same warning points to.

Keyring Storage (Default)

Credentials are stored in the system keyring:

• macOS: Keychain
• Linux: Secret Service (GNOME Keyring, KWallet)
• Windows: Credential Manager

auth:
  storage: keyring
  account: user@example.com

File Storage

If keyring is unavailable, credentials are stored in a file:

auth:
  storage: file
  path: /custom/path/auth.json

Default file locations:

• macOS: ~/Library/Application Support/ndcli/auth.json
• Linux: ~/.config/ndcli/auth.json
• Windows: %APPDATA%\ndcli\auth.json

NDCLI_TOKEN (non-interactive auth)

NDCLI_TOKEN is a special case, separate from the auth.storage keyring/file choice above. Set it to a Personal Access Token (PAT) — a credential with an ndpat_ prefix, minted with ndcli auth token create — and ndcli skips keyring/file lookup and interactive login entirely for that invocation:

export NDCLI_TOKEN=ndpat_your_token_here
ndcli device list

This is the mechanism for CI/CD pipelines, headless servers, and any script that runs without a human present to click through a browser login. See the Personal Access Tokens guide for how to create, scope, and rotate tokens, and the full precedence order below.

Environment Variables

Thirteen configuration keys can be overridden with an NDCLI_-prefixed environment variable. Each one sets the config.yaml key beside it, taking precedence over the file:

Environment Variable	Config Key
NDCLI_CONTROLPLANE_HOST	controlplane.host
NDCLI_CONTROLPLANE_SSL_VERIFY	controlplane.ssl_verify
NDCLI_PATHFINDER_HOST	pathfinder.host
NDCLI_PATHFINDER_SSL_VERIFY	pathfinder.ssl_verify
NDCLI_ORGANIZATION_NAME	organization.name
NDCLI_OUTPUT_FORMAT	output.format
NDCLI_OUTPUT_TIMEZONE	output.timezone
NDCLI_AUTH_STORAGE	auth.storage
NDCLI_AUTH_PATH	auth.path
NDCLI_AUTH_ACCOUNT	auth.account
NDCLI_UPDATE_CHECK_ENABLED	update.check_enabled
NDCLI_DEBUG_ENABLED	debug.enabled
NDCLI_DEBUG_LOG_FILE	debug.log_file

Variables read directly

These are also recognised, but they are not config keys: ndcli reads them at the moment it needs them, they have no config.yaml equivalent, and they are outside the flags → env → file → defaults precedence chain that governs the table above.

Environment Variable	Effect
NDCLI_TOKEN	Authenticate with a Personal Access Token — see NDCLI_TOKEN above
NDCLI_NO_UPDATE_CHECK	Skip the check for a newer ndcli on this invocation
NDCLI_IGNORE_MIN_VERSION	Proceed even if the control plane reports a higher minimum client version
NDCLI_TUI_REFRESH	Refresh interval for interactive full-screen views
NDCLI_DEBUG	Dump goroutine state when an ndcli device connect session tears down

`NDCLI_DEBUG` is not `NDCLI_DEBUG_ENABLED`

These are two different variables driving two different features, not two spellings of one.

• NDCLI_DEBUG_ENABLED sets the debug.enabled config key — general debug output, and it has a config.yaml equivalent.
• NDCLI_DEBUG is the goroutine dump above. It is read directly, has no config key, and setting debug.enabled does not turn it on.

Setting one does not give you the other.

Unrecognised variables

If you set an NDCLI_-prefixed variable that is not in either table above, ndcli prints a warning to standard error naming the variable. The setting has no effect — the warning is there so a typo, or a variable that never existed, does not look like a silent failure.

The warning appears when you run a command. Shell completion stays silent by design, so an unrecognised variable will not disrupt your tab-completion with a warning on every keystroke — if you notice the difference, nothing is broken.

`oauth2.*` has no environment variable, by design

The oauth2.provider, oauth2.domain, oauth2.client_id, oauth2.audience and oauth2.scopes keys are deliberately config-file-only.

ndcli fetches these settings from the control plane when you log in, and checks that the login domain it is handed is the one it expects. Allowing an environment variable to replace that value would weaken the check — a stray or hostile variable in your shell could point a login somewhere else. Leaving them out of the environment keeps the login destination something you set once, on purpose, in a file you control.

Setting NDCLI_OAUTH2_DOMAIN or any of its siblings warns like any other unrecognised variable, and changes nothing.

Examples

export NDCLI_ORGANIZATION_NAME=production

export NDCLI_OUTPUT_FORMAT=json

export NDCLI_CONTROLPLANE_HOST=https://api.example.com

Precedence

Configuration values are resolved in this order (highest to lowest priority):

1. Command-line flags (--org, -f)
2. Environment variables (NDCLI_*)
3. Config file (config.yaml)
4. Built-in defaults

Authentication precedence

Authentication is resolved separately from the general config precedence above, in this order:

1. NDCLI_TOKEN — if set and it validates as an ndpat_... token, it is used for every request and the keyring/file/interactive paths below are skipped entirely, even if a valid cached session also exists.
2. Cached session — the tokens stored by a prior ndcli auth login (keyring or file, per auth.storage).
3. Interactive login — if neither of the above is available, ndcli prompts you to run ndcli auth login.

Caution

PATs do not refresh. A browser-login session carries a refresh token and renews itself silently; a PAT does not — when it hits its --expiry, requests fail until you create a replacement with ndcli auth token create and update NDCLI_TOKEN. See Personal Access Tokens for the rotation sequence.

Example Configurations

Development Setup

Overriding the built-in controlplane.host to point at a development control plane instead of the production default:

controlplane:
  host: https://dev-control.netdefense.io
  ssl_verify: true

organization:
  name: dev-environment

output:
  format: detailed

auth:
  storage: keyring

CI/CD Pipeline

controlplane:
  host: https://control.netdefense.io
  ssl_verify: true

organization:
  name: production

output:
  format: json

auth:
  storage: file
  path: /secrets/ndcli-auth.json

Multi-Organization User

controlplane:
  host: https://control.netdefense.io

organization:
  name: ""

output:
  format: table

Managing Configuration

View Current Configuration

ndcli config show

Reset to Defaults

ndcli config reset

Manually Edit

Open the config file directly:

macOS/Linux

$EDITOR ~/.config/ndcli/config.yaml
code ~/Library/Application\ Support/ndcli/config.yaml

Windows

notepad $env:APPDATA\ndcli\config.yaml