Getting Started

This guide walks you through installing, configuring, and using NDCLI for the first time.

Installation

brew tap netdefense-io/tap
brew install ndcli

curl -L https://github.com/netdefense-io/ndcli/releases/latest/download/ndcli_linux_amd64.tar.gz | tar xz

sudo mv ndcli /usr/local/bin/

scoop bucket add netdefense https://github.com/netdefense-io/scoop-bucket
scoop install ndcli

Initial Setup

Using the Setup Guide

The easiest way to configure NDCLI is with the interactive setup guide:

ndcli setup

The wizard guides you through:

Authentication - Login and credential storage preferences
Organization - Create a new organization or select an existing one
Preferences - Set your default output format

Manual Setup

If you prefer manual configuration:

Authenticate with NetDefense
Terminal window
```
ndcli auth login
```
This opens your browser for OAuth2 authentication.

Set your default organization

# List available organizations
ndcli org list

# Set default
ndcli config set org my-organization

Optionally set output format preference
Terminal window
```
ndcli config set output detailed
```

Verify Your Setup

Check that everything is configured correctly:

ndcli auth show

ndcli auth me

ndcli config show

Your First Commands

List Devices

ndcli device list

ndcli device list --status PENDING

ndcli device list --ou production

Approve a Pending Device

When a new device registers, it appears with PENDING status:

ndcli device list --status PENDING

ndcli device approve my-new-firewall

ndcli device approve-all

View Device Details

ndcli device describe my-firewall

Trigger Configuration Sync

ndcli sync status

ndcli sync apply --device my-firewall

ndcli sync apply --ou production

Configuration Storage

Configuration Files

NDCLI stores configuration in platform-specific locations:

Platform	Config Path
macOS	`~/Library/Application Support/ndcli/config.yaml`
Linux	`~/.config/ndcli/config.yaml`
Windows	`%APPDATA%\ndcli\config.yaml`

Credential Storage

By default, NDCLI stores OAuth2 tokens in your system keyring:

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

If the system keyring is unavailable, credentials fall back to file storage (auth.json).

Environment Variables

All configuration options can be overridden with environment variables using the NDCLI_ prefix:

export NDCLI_ORGANIZATION_NAME=my-org
export NDCLI_OUTPUT_FORMAT=json
export NDCLI_CONTROLPLANE_HOST=https://control.example.com

Shell Completion

Enable tab completion for your shell:

source <(ndcli completion bash)

source <(ndcli completion zsh)

ndcli completion fish | source

ndcli completion powershell | Out-String | Invoke-Expression