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

# Contexts

> Manage CLI contexts to switch between organizations and user configurations.

Contexts let you store named configurations — including organization, project, region, and user credentials — so you don't need to pass these flags on every command.

Contexts are persisted in the user configuration folder. For example, on macOS they are stored in `~/.config/nscale/contexts.yaml`.

To use a context for a whole shell session without changing the saved current context, set the `NSCALE_CONTEXT` environment variable. The `--context` flag wins over it.

**Aliases:** `context`, `ctx`

## Subcommands

* [set](#set) — Create or update a context
* [use](#use) — Set the current active context
* [list](#list) — List all contexts
* [delete](#delete) — Delete a context
* [clear](#clear) — Clear the current context

***

## set

Create or update a context with a given name, organization, and user.

The `--org`, `--project`, and `--region` flags take a name or an ID; the context saves the ID. Use `nscale organizations list`, `nscale projects list`, and `nscale regions list` to see them. Any flag that is omitted will be prompted for interactively.

The context name can be passed as a positional argument or with `--name`; passing both is an error unless they match. If you omit it, the CLI prompts for it.

```bash theme={null}
nscale contexts set <name> --org <organization-id> [--project <project-id>] [--region <region-id>] [--user <user>]
```

### Flags

| Flag | Description |
| - | - |
| `--name string` | Context name |
| `--org string` | Organization ID or name (global flag) |
| `--project string` | Project ID or name |
| `--region string` | Region ID or name |
| `--user string` | Keyring user credentials to use |

### Examples

```bash theme={null}
nscale contexts set prod --org <organization-id> --user default --project <project-id> --region <region-id>

# Names work too
nscale --org acme contexts set prod --user default --project web --region no-glo1

# Update one field of an existing context
nscale contexts set staging --project <project-id>
```

For interactive mode (prompts for all values):

```bash theme={null}
nscale contexts set
```

***

## use

Set the current active context. All subsequent commands will use this context unless overridden with `--context`. If you omit the name, the CLI prompts you to pick one of your contexts.

```bash theme={null}
nscale contexts use <name>
```

### Example

```bash theme={null}
nscale contexts use prod
```

If `NSCALE_CONTEXT` is set, it keeps selecting its context until you unset it; the CLI prints a note on stderr to remind you.

***

## list

List all configured contexts. The context in effect is marked in the `Active` column.

**Aliases:** `list`, `ls`

```bash theme={null}
nscale contexts list [flags]
```

### Flags

| Flag | Description |
| - | - |
| `--json` | Emit the full JSON payload (mutually exclusive with `-q`) |
| `--limit int` | Show at most N results. `0` for all |
| `-q, --query stringArray` | jq filter for value extraction (see [Query output with `-q`](https://docs.nscale.com/docs/cli/query-output)) |

Contexts are read from local configuration rather than the API, so each context is a flat object (`name`, `user`, `organizationId`, `organizationName`, `projectId`, `projectName`, `regionId`, `regionName`, `active`) rather than the usual `metadata`/`spec`/`status` envelope.

### Examples

```bash theme={null}
nscale contexts list --json

# Print the name of the active context
nscale contexts list -q '.[] | select(.active) | .name'
```

***

## delete

Delete a context by name. The CLI asks for confirmation before deleting, and warns you if the context is currently active (deleting it leaves no context active). Pass `--yes` to skip the prompt, for example in scripts or under `--ci`. Declining the prompt exits with an error.

**Aliases:** `delete`, `rm`, `remove`

```bash theme={null}
nscale contexts delete <name> [flags]
```

### Flags

| Flag | Description |
| - | - |
| `-y, --yes` | Automatically confirm context deletion |

### Examples

```bash theme={null}
nscale contexts delete staging
nscale contexts delete staging --yes
```

***

## clear

Clear the current active context. After clearing, commands will require explicit flags for organization, project, etc. `clear` never asks for confirmation, so it runs unattended as is.

```bash theme={null}
nscale contexts clear
```
