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

docs/cli/configuration.mdx

@@ -1,33 +1,21 @@
 ---
 title: "Configuration"
-description: ""
+description: "Reference for NeMo CLI configuration fields, precedence, telemetry, and shell completion."
 ---
-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.
+The NeMo CLI uses a configuration file to store connection settings, credentials, and preferences for one or more contexts.
 
-## Quick Setup
+## Prerequisites
 
-The quickest way to connect to an existing deployment is:
+- Install the NeMo CLI as described in [Setup](/documentation/get-started).
+- To create connections or switch contexts, follow [Connect the CLI to Deployments](/documentation/reference/cli-reference/connect-to-deployments).
 
-```bash
-# Set base URL and authenticate in one command
-nemo auth login --base-url https://nmp.example.com
-```
-
-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.
-
-To configure a named context:
-
-```bash
-nemo --context prod auth login --base-url https://nmp.prod.example.com
-```
-
-## Configuration File
+## 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):
 
@@ -38,36 +26,12 @@ 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.
 
-Inspect the currently active context and resolved references:
-
-```bash
-nemo config view
-```
-
-Or print only the current context name:
-
-```bash
-nemo config current-context
-```
-
-Switch to a different context:
-
-```bash
-nemo config use-context prod
-```
-
-Use a context for a single command without switching:
-
-```bash
-nemo --context prod workspaces list
-```
-
-### Modify Configuration
+### Modify configuration
 
 Set specific values:
 
@@ -79,7 +43,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.
 
@@ -99,13 +63,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):
 
@@ -231,3 +195,9 @@ On your first run, the CLI writes this notice to standard error:
 > NeMo Platform collects anonymous usage data to improve the product. No prompts, data, or personal information leave your machine. Turn it off at any time with NEMO_TELEMETRY_ENABLED=false.
 
 The notice appears only once, and you can opt out at any time using one of the methods above.
+
+## Next Steps
+
+- [Connect the CLI to one or more deployments](/documentation/reference/cli-reference/connect-to-deployments).
+- See the [full CLI reference](/documentation/reference/cli-reference/full-cli-reference) for every command and option.
+- Use [CLI troubleshooting](/documentation/reference/cli-reference/troubleshooting) if configuration does not resolve as expected.

docs/cli/connect-to-deployments.mdx

@@ -0,0 +1,97 @@
+---
+title: "Connect the CLI to Deployments"
+description: "Configure, authenticate, and switch between NeMo Platform deployments."
+---
+
+Use named CLI contexts to connect to one or more local or remote NeMo Platform deployments.
+
+## Prerequisites
+
+- Install the NeMo CLI as described in [Setup](/documentation/get-started).
+- Obtain the base URL for each deployment.
+- For an authenticated deployment, obtain an account that can complete its login flow.
+
+## Connect to a remote deployment
+
+Save the deployment URL in the current CLI context:
+
+```bash
+nemo config set --base-url https://nmp.example.com
+```
+
+Verify the saved URL:
+
+```bash
+nemo config view
+```
+
+If the deployment requires authentication, log in after configuring the URL:
+
+```bash
+nemo auth login
+```
+
+You can also run `nemo setup`. During interactive onboarding, setup offers to connect to a remote deployment when the configured platform is unreachable. It verifies and saves the URL, then runs the same authentication flow.
+
+## Connect to multiple deployments
+
+A context is a user-defined name for a set of connection settings. 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 deployment. Use `--activate` to make one of them current:
+
+```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
+```
+
+If the saved configuration has no current context, the next written context becomes current automatically. Otherwise, creating another context does not switch the current context.
+
+For authenticated deployments, log in to each context separately:
+
+```bash
+nemo auth login --context staging
+nemo auth login --context production
+```
+
+Switch the current context:
+
+```bash
+nemo config use-context staging
+```
+
+Verify the switch:
+
+```bash
+nemo config current-context
+nemo config view
+```
+
+Inspect all saved connections:
+
+```bash
+nemo config view --all-contexts
+```
+
+To target a context for one command without switching, use the global `--context` option:
+
+```bash
+nemo --context production models list
+```
+
+## Connect to a local deployment
+
+A local platform can coexist with remote contexts:
+
+```bash
+nemo config set --context local --base-url http://localhost:8080
+```
+
+<Note>
+`NMP_BASE_URL` and `NMP_CURRENT_CONTEXT` override saved configuration for all contexts. If switching contexts does not change the target deployment, unset those variables or update them for the current shell.
+</Note>
+
+## Next Steps
+
+- Review the [configuration reference](/documentation/reference/cli-reference/configuration) for fields and precedence.
+- Run `nemo workspaces list` to verify platform access.
+- Use [CLI troubleshooting](/documentation/reference/cli-reference/troubleshooting) if the connection fails.

docs/cli/reference.mdx

@@ -140,7 +140,7 @@ For quickstart, use **`--unsigned-token`** to generate an unsigned JWT.
 # Set base URL and log in
 nemo auth login --base-url https://nemo.example.com
 # Context-specific login
-nemo auth login --context dev --base-url https://nemo.dev.example.com
+nemo auth login --context staging --base-url https://nmp.staging.example.com
 # Device flow, open browser
 nemo auth login
 # Device flow, show code only

docs/fern/versions/latest.yml

@@ -489,6 +489,8 @@ navigation:
           - section: CLI Reference
             path: ../../cli/index.mdx
             contents:
+              - page: Connect to Deployments
+                path: ../../cli/connect-to-deployments.mdx
               - page: Configuration
                 path: ../../cli/configuration.mdx
               - page: Working with Resources

docs/get-started/setup.mdx

@@ -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, follow [Connect the CLI to Deployments](/documentation/reference/cli-reference/connect-to-deployments).
+
 ### 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.

packages/nemo_platform_ext/README.md

@@ -85,8 +85,7 @@ contexts:
 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
 ```
 
 ### Priority
@@ -146,10 +145,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)