CLI Overview & Authentication - nodepick.ai Documentation

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 bash.

curl -sSL https://raw.githubusercontent.com/nodepick/developer/main/cli/install.sh | bash

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

Configuration

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).

Environment Variables

You can also 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`

Authentication (`np auth`)

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

Configure Credentials (`np auth configure`)

Save your API key securely in the OS keyring and set an optional base URL. If you don’t have an API key yet:

Register at nodepick.ai and log in.
Set up your credit card in the dashboard.
In the left-hand navigation, open Developer, then go to API Keys.
Click Generate, give the key a name, and copy and save the key immediately — it won’t be shown again.

Configure the CLI by saving your API key securely in the OS keyring. When prompted, enter your API key:

np auth configure

You can also set the NODEPICK_API_KEY environment variable in your shell or CI environment to authenticate without storing credentials in the keyring.

Options

Option	Short	Description	Default
`--base-url`	`-u`	API base URL	`https://api.nodepick.ai`

Examples

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

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

# Set the key in an environment variable (for CI/CD or scripts)
export NODEPICK_API_KEY="np_live_1234567890abcdef"

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 configure or set NODEPICK_API_KEY before running subsequent CLI commands.

AI Agent Integration (`np ai mcp`)

Configure Model Context Protocol (MCP) servers on AI development agents to interact with your compute nodes.

Configure MCP Server (`np ai mcp configure`)

Register the MCP server endpoints of one or more compute nodes into your AI agent’s configuration using HTTP stream transport with self-signed certificate verification bypassed.

np ai mcp configure <agent> [node_id_1 node_id_2 ...]

Arguments

Argument	Description	Default
`<agent>`	Target AI agent (`antigravity`)	Required
`[nodes]`	Node IDs or display names to configure	All available nodes

Examples

# Configure Antigravity to connect to a specific node by name
np ai mcp configure antigravity dev

# Configure Antigravity to connect to multiple nodes
np ai mcp configure antigravity dev prod staging

# Configure Antigravity for all compute nodes in your account
np ai mcp configure antigravity

Next Steps

Manage Nodes

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

​Installation

​Global Options

​Debug Logging

​Output Formatting

​Configuration

​Environment Variables

​Authentication (np auth)

​Configure Credentials (np auth configure)

​Options

​Examples

​Test Access (np auth test)

​Output Information

​Example Output

​Clear Credentials (np auth clear)

​AI Agent Integration (np ai mcp)

​Configure MCP Server (np ai mcp configure)

​Arguments

​Examples

​Next Steps

Manage Nodes

SSH Keys

Installation

Global Options

Debug Logging

Output Formatting

Configuration

Environment Variables

Authentication (`np auth`)

Configure Credentials (`np auth configure`)

Options

Examples

Test Access (`np auth test`)

Output Information

Example Output

Clear Credentials (`np auth clear`)

AI Agent Integration (`np ai mcp`)

Configure MCP Server (`np ai mcp configure`)

Arguments

Examples

Next Steps