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

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-dev.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://dev-control.netdefense.io	API host URL
controlplane.ssl_verify	bool	true	Verify SSL certificates

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.

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

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

Override 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

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

All configuration options can be set via environment variables with the NDCLI_ prefix:

Environment Variable	Config Key
NDCLI_OAUTH2_PROVIDER	oauth2.provider
NDCLI_OAUTH2_DOMAIN	oauth2.domain
NDCLI_OAUTH2_CLIENT_ID	oauth2.client_id
NDCLI_OAUTH2_AUDIENCE	oauth2.audience
NDCLI_OAUTH2_SCOPES	oauth2.scopes
NDCLI_CONTROLPLANE_HOST	controlplane.host
NDCLI_CONTROLPLANE_SSL_VERIFY	controlplane.ssl_verify
NDCLI_ORGANIZATION_NAME	organization.name
NDCLI_OUTPUT_FORMAT	output.format
NDCLI_TOKEN	(no config key — auth override, see below)

NDCLI_TOKEN doesn’t map to a config.yaml key. It’s read directly at authentication time and never written to the config file or keyring, so it isn’t part of the flags → env → file → defaults precedence chain that governs the rest of this table. See Authentication precedence.

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

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