Skip to content

feat(cli): improve multi-context UX and Config.write API #1072

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
anastasia-nesterenko wants to merge 1 commit into
base: main
Choose a base branch
from
Open

feat(cli): improve multi-context UX and Config.write API #1072

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
101 changes: 79 additions & 22 deletions docs/cli/configuration.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,33 +1,88 @@
---
title: "Configuration"
description: ""
description: "Configure multiple NeMo Platform connections and switch between them."
---
The NeMo CLI uses a configuration file to store connection settings, credentials, and preferences. This allows you to work with multiple environments and switch between them easily.

## Quick Setup
## Connect to a remote deployment

The quickest way to connect to an existing deployment is:
Save the deployment URL in the current CLI context:

```bash
# Set base URL and authenticate in one command
nemo auth login --base-url https://nmp.example.com
nemo config set --base-url https://nmp.example.com
```

Verify the saved URL before running other commands:

```bash
nemo config view
```

If the deployment requires authentication, log in after configuring the URL:

```bash
nemo auth login
```

During interactive onboarding, `nemo setup` also offers to connect to a remote deployment when the currently configured platform is unreachable. It verifies and saves the new URL in the active context, then runs the same authentication flow.
You can also run `nemo setup`. During interactive onboarding, setup offers to connect to a remote deployment when the currently configured platform is unreachable. It verifies and saves the URL, then runs the same authentication flow.

To configure a named context:
## Connect to multiple deployments

A context is a user-defined name for a set of connection settings. The name has no built-in meaning: names such as `staging`, `production`, and `local` are labels you choose. Each context keeps its own URL, authentication credentials, workspace, and output preferences.

Create a context for each remote deployment. Use `--activate` to make one of them the current context:

```bash
nemo config set --context staging --base-url https://nmp.staging.example.com
nemo config set --context production --base-url https://nmp.example.com --activate
```

The first context becomes current automatically. After a current context exists, creating another named context does not switch it. Use `--activate` when creating the context or run `nemo config use-context <name>` later to switch.

For authenticated deployments, log in to each context separately so its credentials are saved with the correct connection:

```bash
nemo --context prod auth login --base-url https://nmp.prod.example.com
nemo auth login --context staging
nemo auth login --context production
```

## Configuration File
Switch the current context at any time:

```bash
nemo config use-context staging
nemo config use-context production
```

Confirm which context is current and inspect all saved connections:

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

To target a context for only one command without changing the current context, use the global `--context` option:

```bash
nemo --context staging models list
```

A local platform is configured the same way and can coexist with any number of remote contexts:

```bash
nemo config set --context local --base-url http://localhost:8080
```

<Note>
`NMP_BASE_URL` and `NMP_CURRENT_CONTEXT` override saved configuration. If switching contexts does not change the target deployment, unset those variables or update them for the current shell.
</Note>
Comment on lines +7 to +77

@coderabbitai coderabbitai Bot Aug 4, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

📐 Maintainability & Code Quality | 🟠 Major | 🏗️ Heavy lift

Split workflow and reference content.

This page mixes HOW-TO workflows with REFERENCE content. Move connection workflows to a HOW-TO page. Keep configuration fields, precedence, telemetry, and completion in REFERENCE pages. Add prerequisites and a Next Steps section.

As per coding guidelines, “Each documentation page should fit ONE Diataxis quadrant” and “Always list prerequisites at the top of documentation pages before other content.”

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/cli/configuration.mdx` around lines 7 - 77, Split the connection
workflows from the configuration reference: move the remote and multi-deployment
setup instructions, including authentication, context switching, and
verification commands, into a dedicated HOW-TO page. Keep this reference page
focused on configuration fields, precedence, telemetry, and completion content;
add a prerequisites section at the top and a Next Steps section at the end,
following the documentation structure guidelines.

Source: Coding guidelines


## Configuration file

The configuration is stored in `~/.config/nmp/config.yaml`. If the `XDG_CONFIG_HOME` environment variable is set, the file is stored in `$XDG_CONFIG_HOME/nmp/config.yaml` instead. You can also specify a custom location with the `NMP_CONFIG_FILE` environment variable.

## Managing Configuration
## Manage configuration

### View Configuration
### View configuration

Display configuration for the current context (secrets are redacted):

Expand All @@ -38,36 +93,38 @@ nemo config view
Display all contexts:

```bash
nemo config view --all-contexts
nemo config view --all-contexts --output-format json
```

### Switch Contexts
The full view includes every saved context, cluster, and user. JSON output is useful for scripts and configuration audits; omit `--output-format json` for the default table view shown in the [multiple-deployment workflow](#connect-to-multiple-deployments).

Inspect the currently active context and resolved references:
### Switch contexts

Inspect the current context and resolved references:

```bash
nemo config view
```

Or print only the current context name:
Or capture only the current context name for use in a shell script:

```bash
nemo config current-context
active_context="$(nemo config current-context)"
```

Switch to a different context:

```bash
nemo config use-context prod
nemo config use-context production
```

Use a context for a single command without switching:

```bash
nemo --context prod workspaces list
nemo --context production workspaces list
```

### Modify Configuration
### Modify configuration

Set specific values:

Expand All @@ -79,7 +136,7 @@ nemo config set --access-token -

When setting an access token, you'll be prompted to enter it securely (input is hidden).

## Environment Variables
## Environment variables

Environment variables override configuration file settings. This is useful for CI/CD pipelines or temporary overrides.

Expand All @@ -99,13 +156,13 @@ Example:

```bash
# Use a different context for this command
NMP_CURRENT_CONTEXT=prod nemo workspaces list
NMP_CURRENT_CONTEXT=production nemo workspaces list

# Override base URL
NMP_BASE_URL=https://nmp.example.com nemo models list
```

## Configuration Precedence
## Configuration precedence

Settings are resolved in this order (highest priority first):

Expand Down
2 changes: 2 additions & 0 deletions docs/get-started/setup.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -91,6 +91,8 @@ Choose the remote option and enter the deployment's base URL. Setup verifies the

This connects the local CLI to an existing deployment; it does not install the platform on a remote host.

To configure remote access without rerunning setup, or to keep separate local and remote targets, use [`nemo config`](/documentation/reference/cli-reference/configuration).

### Auth and OIDC source installs

`nemo setup` and `nemo services run` do not create authorization role bindings by themselves. If you enable auth in source config with `auth.enabled: true` and set `auth.admin_email`, run the platform seed task so the bootstrap IAM bindings exist.
Expand Down
14 changes: 7 additions & 7 deletions packages/nemo_platform_ext/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -50,22 +50,22 @@ The CLI reads configuration from `~/.config/nmp/config.yaml`:
current_context: production

clusters:
- name: prod-cluster
- name: production-cluster
base_url: https://nmp.example.com
- name: local
base_url: http://localhost:8080

users:
- name: prod-admin
- name: production-admin
type: api-key
api_key: your-api-key-here
- name: local-user
type: no-auth

contexts:
- name: production
cluster: prod-cluster
user: prod-admin
cluster: production-cluster
user: production-admin
workspace: default
preferences:
output_format: table
Expand All @@ -86,7 +86,7 @@ Configure a context with `nemo config set`:

```bash
nemo config set --base-url https://nmp.example.com
nemo config set --context prod --base-url https://nmp.prod.example.com --activate
nemo config set --context production --base-url https://nmp.example.com --activate

@coderabbitai coderabbitai Bot Aug 4, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win

Do not modify the current context before creating production.

Line 88 and Line 89 run sequentially. The first command can overwrite the current context URL before the second command creates production. Remove the first command or present the commands as alternatives.

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/nemo_platform_ext/README.md` at line 89, Update the README command
examples so creating the production context does not first modify the current
context; remove the preceding context-setting command or present it as an
alternative to the production creation command.

Source: Coding guidelines

```

### Priority
Expand Down Expand Up @@ -146,10 +146,10 @@ nemo config set --api-key YOUR_API_KEY
nemo config set --workspace my-workspace --output-format json

# Configure and activate a named context in one step
nemo config set --context prod --base-url https://api.prod.example.com --activate
nemo config set --context production --base-url https://nmp.example.com --activate

# Switch to an existing context
nemo config use-context prod
nemo config use-context production
```

## Setup (Local Development)
Expand Down
Loading
Loading