Configuration Reference

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

Configuration File Location

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

~/.config/ndcli/config.yaml

%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

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

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

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`

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):

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

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
Windows

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

notepad $env:APPDATA\ndcli\config.yaml