Skip to navigation
DocumentationReferenceCLI Reference

Connect with CLI Contexts

View as Markdown

A CLI context is a named set of connection settings: the deployment URL, your credentials, a default workspace, and output preferences. The NeMo CLI and the Python SDK both read the current context, so you configure a deployment once and every nemo command and SDK client targets it.

Tutorials and guides in this documentation assume that your current context points at the deployment you want to use.

Prerequisites

  • Install the NeMo CLI as described in Setup.
  • Obtain the base URL for each deployment.
  • For an authenticated deployment, obtain an account that can complete its login flow.

How contexts work

Contexts are saved in the CLI configuration file, ~/.config/nhx/config.yaml by default. A single file can hold contexts for any number of local and remote deployments. Each context references a cluster entry (the base URL) and a user entry (the credentials), and stores its own default workspace:

current_context: local
clusters:
- name: local-cluster
  base_url: http://localhost:8080/
- name: production-cluster
  base_url: https://nhx.example.com/
users:
- name: local-user
  type: no-auth
- name: production-user
  type: oauth
  token: <saved by nemo auth login>
contexts:
- name: local
  cluster: local-cluster
  user: local-user
  workspace: default
- name: production
  cluster: production-cluster
  user: production-user
  workspace: team-a

You don’t need to edit this file by hand. nemo setup, nemo config set, and nemo auth login write it for you. Context names such as local, staging, and production are labels you choose.

current_context is the default. Commands and SDK clients use it unless you select another context explicitly. For file location options, see the configuration reference.

Connect to a remote deployment

Save the deployment URL in the current CLI context:

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

Verify the saved URL:

nemo config view

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

nemo auth login

The login stores credentials in the context, and the CLI and Python SDK refresh them as needed.

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 a local deployment

A local platform can coexist with remote contexts:

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

For a local HTTPS deployment with a private certificate authority, save the CA bundle with the cluster:

nemo config set --context local-tls --base-url https://localhost:8443 --certificate-authority /path/to/ca.crt

The saved cluster entry uses the certificate_authority key.

Manage multiple contexts

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

nemo config set --context staging --base-url https://nhx.staging.example.com
nemo config set --context production --base-url https://nhx.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:

nemo auth login --context staging
nemo auth login --context production

Switch the current context

Switch the default context for all later commands and SDK clients:

nemo config use-context staging

Verify the switch:

nemo config current-context
nemo config view

Inspect all saved connections:

nemo config view --all-contexts

Use a context for one command

To target a context for one command without switching, use the global --context option:

nemo --context production models list

To target a context for every command in the current shell, set NHX_CURRENT_CONTEXT:

export NHX_CURRENT_CONTEXT=production

Set the default workspace

Each context stores a default workspace, which starts as default. Commands and SDK clients use it for workspace-scoped resources unless you pass a workspace explicitly. Change it for the current context:

nemo config set --workspace my-workspace

Unless an example says otherwise, examples in this documentation use the default workspace. Some tutorials create a dedicated workspace and set it as the default this way. To return to the original workspace afterward, run nemo config set --workspace default.

Use contexts from the Python SDK

NemoClient.from_config() builds a client from the current context, including its base URL, default workspace, and credentials from nemo auth login:

from nemo_helix_plugin.client.client import NemoClient
client = NemoClient.from_config()
for workspace in client.workspaces.list_workspaces().items():
    print(workspace.name)

To use a specific context without switching the current one, pass its name:

from nemo_helix_plugin.client.client import NemoClient
client = NemoClient.from_config(context="production")

AsyncNemoClient.from_config() accepts the same arguments. Because the client reads the same configuration as the CLI, switching contexts with nemo config use-context changes the target of both. For all connection options, see Client APIs.

When to use NHX_BASE_URL

The NHX_BASE_URL environment variable overrides the base URL of every context. Most workflows don’t need it. Use the following guidelines:

  • The NeMo CLI and NemoClient.from_config(): leave NHX_BASE_URL unset. Setting it, even to a local default, overrides the deployment saved in your context.

  • Tools that need a URL directly, such as curl or an OpenTelemetry exporter: these can’t read the CLI configuration. Examples in this documentation use ${NHX_BASE_URL:-http://localhost:8080}, which falls back to a local deployment only when the variable is unset. If your context points at a remote deployment, export its URL first. For an authenticated deployment, pass a token from the current context with nemo auth token:

    export NHX_BASE_URL=https://nhx.example.com
    curl -H "Authorization: Bearer $(nemo auth token)" \
      "${NHX_BASE_URL:-http://localhost:8080}/apis/entities/v2/workspaces"

  • Environments without a configuration file, such as CI jobs, containers, and hosted notebooks like Google Colab: set NHX_BASE_URL, and NHX_ACCESS_TOKEN for an authenticated deployment. The CLI and NemoClient.from_config() both read these variables.

NHX_BASE_URL and NHX_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.

Delete a context

Delete a context when you no longer need it:

nemo config delete-context local-tls

This follows the same convention as kubectl config delete-context: the context is removed, but cluster and user records remain. To also remove unreferenced cluster and user records, pass --prune-orphans.

Next Steps