Skip to content
NetDefense Docs

Getting Started

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

Installation

Section titled “Installation”
Terminal window
brew tap netdefense-io/tap
brew install ndcli

Initial Setup

Section titled “Initial Setup”

Using the Setup Guide

Section titled “Using the Setup Guide”

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

Terminal window
ndcli setup

The wizard guides you through:

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

Manual Setup

Section titled “Manual Setup”

If you prefer manual configuration:

  1. Authenticate with NetDefense

    Terminal window
    ndcli auth login

    This opens your browser for OAuth2 authentication.

  2. Set your default organization

    Terminal window
    # List available organizations
    ndcli org list
    

    # Set default
    ndcli config set org my-organization

  3. Optionally set output format preference

    Terminal window
    ndcli config set output detailed

Verify Your Setup

Section titled “Verify Your Setup”

Check that everything is configured correctly:

Terminal window
ndcli auth show


ndcli auth me


ndcli config show

Your First Commands

Section titled “Your First Commands”

List Devices

Section titled “List Devices”
Terminal window
ndcli device list


ndcli device list --status PENDING


ndcli device list --ou production

Approve a Pending Device

Section titled “Approve a Pending Device”

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

Terminal window
ndcli device list --status PENDING


ndcli device approve my-new-firewall


ndcli device approve-all

View Device Details

Section titled “View Device Details”
Terminal window
ndcli device describe my-firewall

Trigger Configuration Sync

Section titled “Trigger Configuration Sync”
Terminal window
ndcli sync status


ndcli sync apply --device my-firewall


ndcli sync apply --ou production

Configuration Storage

Section titled “Configuration Storage”

Configuration Files

Section titled “Configuration Files”

NDCLI stores configuration in platform-specific locations:

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

Credential Storage

Section titled “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

Section titled “Environment Variables”

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

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

Shell Completion

Section titled “Shell Completion”

Enable tab completion for your shell:

Terminal window
source <(ndcli completion bash)

Next Steps

Section titled “Next Steps”