---
name: getting-started
description: Connect to NeMo Platform and configure the CLI
version: "0.1"
---

# Getting Started

## Authentication

### Log in to a cluster

```bash
nemo auth login --base-url https://nemo.example.com
```

This sets the base URL for the current context and opens a browser for OIDC device flow. After completing the browser flow, credentials are saved to the config file.

To skip the browser and show a device code instead:

```bash
nemo auth login --base-url https://nemo.example.com --no-browser
```

For CI/non-interactive environments using username and password:

```bash
nemo auth login --username user@example.com --password "$PASSWORD"
# Or use environment variables:
# NMP_OIDC_USERNAME and NMP_OIDC_PASSWORD
```

### Check authentication status

```bash
nemo auth status
```

Shows the current context, cluster URL, logged-in user, token expiry, granted scopes, and whether a refresh token is available.

### Get the current access token

```bash
nemo auth token
```

Prints the raw token to stdout. Useful for passing to the SDK or curl:

```bash
export TOKEN=$(nemo auth token)
curl -H "Authorization: Bearer $(nemo auth token)" https://nemo.example.com/api/...
```

### Use CLI auth in the Python SDK

The Python SDK does not read the CLI config file. Use `nemo auth token` to bridge:

```python
from nemo_platform import NeMoPlatform
import subprocess

token = subprocess.check_output(["nemo", "auth", "token"], text=True).strip()
client = NeMoPlatform(
    base_url="https://nmp.dev.aire.nvidia.com",
    access_token=token,
)
```

### Log out

```bash
nemo auth logout
```

Removes stored credentials from the config file for the current context.

### Agent auth flow

Do not run `nemo auth login` inside agent environments (Claude Code, Copilot, Codex, etc.) — it requires interactive terminal input that does not work reliably.

1. Check auth status: `nemo auth status`
2. If expired, tell the user: "Your NeMo auth has expired. Please run `nemo auth login` in a separate terminal, then let me know when done."
3. Verify after they confirm: `nemo auth status`

---

## Configuration

### Set the base URL

The most common first step. Sets the cluster URL in the current context:

```bash
nemo config set --base-url https://nemo.example.com
```

### View current configuration

```bash
nemo config view
```

Shows config for the current context only (cluster, user, settings). To see all contexts:

```bash
nemo config view --all-contexts
```

### Set a default workspace

```bash
nemo config set --workspace my-workspace
```

Once set, commands that require a workspace will use this default unless overridden with `--workspace`.

### Set default output format

```bash
nemo config set --output-format json
```

Supported formats: `table` (default), `json`, `yaml`, `markdown`.

---

## Context Management

Contexts let you switch between different clusters or configurations without re-running `nemo auth login`.

### View the current context name

```bash
nemo config current-context
```

### Switch to a different context

```bash
nemo config use-context dev
```

### Create a new named context and configure it

```bash
# Set the base URL for a new context named "staging"
nemo config set --context staging --base-url https://staging.nemo.example.com
# Log in to the staging cluster
nemo auth login --context staging
# Switch to the staging context
nemo config use-context staging
```

---

## Workspace Management

Most NeMo Platform resources are scoped to a workspace.

### List workspaces

```bash
nemo workspaces list
```

### Create a workspace

```bash
nemo workspaces create my-workspace
```

### Get details for a workspace

```bash
nemo workspaces get my-workspace
```

---

## Output Formatting

All list and get commands support output format flags.

### Output formats

```bash
nemo workspaces list -f json
nemo workspaces list -f yaml
nemo workspaces list -f markdown
nemo workspaces list -f table   # default
```

The `-f` flag can also be set as a default in config:

```bash
nemo config set --output-format json
```

### Show full values without truncation

Long field values are truncated in table output by default. To disable:

```bash
nemo workspaces list --no-truncate
```

### Timestamp formatting

Configure timestamp display across all commands:

```bash
nemo config set --timestamp-format iso8601
```

Supported values: `relative` (default, e.g., "2 hours ago"), `iso8601` (e.g., "2026-03-24T12:00:00").
