> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nodepick.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI Overview & Authentication

> Install the nodepick.ai CLI (np) and manage API authentication and global configuration.

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

<CodeGroup>
  ```bash uv theme={null}
  uv tool install nodepick-cli
  ```

  ```bash pip theme={null}
  pip install nodepick-cli
  ```
</CodeGroup>

<Note>
  `uv` installs `np` into an isolated environment without modifying system Python packages.
</Note>

## 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:

```bash theme={null}
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.

```bash theme={null}
# 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` |

<Tip>
  Set `NODEPICK_API_KEY` in non-interactive CI/CD pipelines to authenticate without interactive logins.
</Tip>

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

```bash theme={null}
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

<CodeGroup>
  ```bash Interactive theme={null}
  # Prompts securely for API key without echoing input
  np auth save
  ```

  ```bash Non-interactive theme={null}
  # Pass key directly as a flag
  np auth save --api-key np_live_1234567890abcdef
  ```

  ```bash Custom API URL theme={null}
  # Specify custom API base URL
  np auth save --api-key np_live_1234567890abcdef --base-url https://api.nodepick.ai
  ```
</CodeGroup>

***

### Test Access (`np auth test`)

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

```bash theme={null}
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

```text theme={null}
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.

```bash theme={null}
np auth clear
```

<Warning>
  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.
</Warning>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Manage Nodes" icon="server" href="/cli-reference/nodes">
    Learn how to list, create, boot, shutdown, reboot, inspect, and delete compute nodes.
  </Card>

  <Card title="SSH Keys" icon="key" href="/cli-reference/ssh">
    Register public SSH keys for automatic injection into new compute nodes.
  </Card>
</CardGroup>