setup

The interactive setup guide walks you through initial NDCLI configuration.

ndcli setup

Overview

The setup guide provides a guided experience for configuring NDCLI, especially useful for first-time users. It handles:

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

Automatic Invocation

The setup guide runs automatically when:

• You run NDCLI for the first time (no config file exists)
• You run any command that requires configuration

You can also run it manually at any time to reconfigure settings.

What the Guide Configures

Authentication

• Initiates OAuth2 device authorization flow
• Opens browser for authentication
• Stores tokens securely in system keyring (or file fallback)

Organization

The guide offers three options:

1. Create a new organization - For users starting fresh
2. Select an existing organization - For users joining an existing org
3. Accept a pending invitation - For users who received an invite

Output Format

Choose your preferred default output format:

Format	Best For
detailed	Interactive terminal use (default)
table	Viewing lists and summaries
simple	Quick, compact output
json	Scripting and automation

Examples

ndcli setup

ndcli config show
ndcli auth show

Re-running Setup

You can run ndcli setup at any time to:

• Re-authenticate with a different account
• Change your default organization
• Update output preferences

The guide preserves existing settings where possible and only updates what you change.

Configuration Files Created

After setup completes, the following files are created:

Platform	Config File	Auth Storage
macOS	~/Library/Application Support/ndcli/config.yaml	Keychain
Linux	~/.config/ndcli/config.yaml	Secret Service
Windows	%APPDATA%\ndcli\config.yaml	Credential Manager

Manual Alternative

If you prefer to configure NDCLI manually instead of using the guide:

ndcli auth login

ndcli config set org my-organization

ndcli config set output detailed

Troubleshooting

Browser Doesn’t Open

If the browser doesn’t open automatically during authentication:

1. Copy the URL displayed in the terminal
2. Paste it into your browser manually
3. Complete authentication
4. Return to the terminal

Keyring Unavailable

If the system keyring is unavailable, NDCLI falls back to file-based token storage at:

• ~/.config/ndcli/auth.json (Linux)
• ~/Library/Application Support/ndcli/auth.json (macOS)

Organization Not Found

If your organization isn’t listed:

1. Ask an administrator to send you an invitation
2. Accept the invitation: ndcli org invite accept org-name
3. Re-run setup to select the organization