CLI Overview & Authentication

The np command-line interface lets you manage compute nodes, SSH public keys, and authentication directly from your terminal.

Installation

You can install the np CLI using uv (recommended) or pip.

uv tool install nodepick-cli

pip install nodepick-cli

uv installs np into an isolated environment without modifying system Python packages.

Global Options

The np CLI supports global options that apply to all subcommands.

Option	Short	Description	Default
`--debug`	`-d`	Enable verbose DEBUG logging output	`false`
`--help`		Show help message and exit

Debug Logging

To output detailed diagnostic logs during command execution, pass the --debug flag before the subcommand:

np --debug node list

Output Formatting

Commands that list or display resources support output formatting via the --format (-f) option:

table: Render formatted interactive tables (default).
json: Return raw structured JSON output for scripting and pipe processing.

# Output as a formatted table (default)
np node list

# Output as JSON
np node list -f json

Environment Variables

You can configure CLI behavior using the following environment variables:

Variable	Description	Default
`NODEPICK_API_KEY`	Overrides the API key stored in the OS keyring	None
`NODEPICK_BASE_URL`	Overrides the default API base URL	`https://api.nodepick.ai`

Set NODEPICK_API_KEY in non-interactive CI/CD pipelines to authenticate without interactive logins.

Configuration File

The CLI stores non-sensitive configuration settings (such as base_url) in:

~/.nodepick/config.json

API keys are stored separately in your operating system’s secure keyring service (nodepick-cli).

Authentication (`np auth`)

Use np auth commands to store, test, and remove API authentication credentials.

Save Credentials (`np auth save`)

Save your API key securely in the OS keyring and set an optional base URL.

np auth save

Options

Option	Short	Description	Default
`--api-key`	`-k`	Nodepick API key or bearer token	Prompted securely if omitted
`--base-url`	`-u`	API base URL	`https://api.nodepick.ai`

Examples

# Prompts securely for API key without echoing input
np auth save

# Pass key directly as a flag
np auth save --api-key np_live_1234567890abcdef

# Specify custom API base URL
np auth save --api-key np_live_1234567890abcdef --base-url https://api.nodepick.ai

Test Access (`np auth test`)

Verify your stored API key against the nodepick.ai API and display your account details.

np auth test

Output Information

Authentication status: Confirms valid API access.
User email: Account email associated with the key.
Organization: Associated organization name.
Base URL: Target API base URL.
Key source: Indicates whether credentials came from OS keyring or env var NODEPICK_API_KEY.

Example Output

API access OK. User: dev@company.com | Org: Engineering | URL: https://api.nodepick.ai | Key source: OS keyring

Clear Credentials (`np auth clear`)

Remove the stored API key from your OS keyring.

np auth clear

Clearing credentials removes the stored key from your local OS keyring. You will need to run np auth save or set NODEPICK_API_KEY before running subsequent CLI commands.

Next Steps

Manage Nodes

Learn how to list, create, boot, shutdown, reboot, inspect, and delete compute nodes.

CLI Reference

Installation

Global Options

Debug Logging

Output Formatting

Environment Variables

Configuration File

Authentication (`np auth`)

Save Credentials (`np auth save`)

Options

Examples

Test Access (`np auth test`)

Output Information

Example Output

Clear Credentials (`np auth clear`)

Next Steps

Manage Nodes

SSH Keys

​Installation

​Global Options

​Debug Logging

​Output Formatting

​Environment Variables

​Configuration File

​Authentication (np auth)

​Save Credentials (np auth save)

​Options

​Examples

​Test Access (np auth test)

​Output Information

​Example Output

​Clear Credentials (np auth clear)

​Next Steps

Manage Nodes

SSH Keys

Installation

Global Options

Debug Logging

Output Formatting

Environment Variables

Configuration File

Authentication (`np auth`)

Save Credentials (`np auth save`)

Options

Examples

Test Access (`np auth test`)

Output Information

Example Output

Clear Credentials (`np auth clear`)

Next Steps