Getting Started

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

Installation

brew tap netdefense-io/tap
brew trust netdefense-io/tap
brew install ndcli

Homebrew 6.0+ requires you to explicitly trust a third-party tap before installing packages from it.

Release assets carry the version in their filename, so there is no fixed latest/download/... URL. Ask the releases API for the current asset first:

curl -s https://api.github.com/repos/netdefense-io/ndcli-releases/releases/latest \
  | grep "browser_download_url.*linux_amd64.tar.gz" \
  | cut -d '"' -f 4 | xargs curl -L -o ndcli.tar.gz

tar xzf ndcli.tar.gz && sudo install -m0755 ndcli /usr/local/bin/ndcli

On arm64 machines, swap linux_amd64 for linux_arm64 in the grep pattern.

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 to complete 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 authentication 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

Some configuration options can be overridden with an NDCLI_-prefixed environment variable:

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

Not every setting has one — see the complete list of environment variables in the Configuration Reference. If you set an NDCLI_ variable that isn’t recognised, ndcli warns you and the setting has no effect.

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