> ## 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.

# Overview

> The CLI provides a powerful, automation-friendly interface to all Nscale resources and services.

## Installation

You can install the CLI using any of the following methods:

> [!TIP]
>
> The install scripts for macOS and Linux (`install.sh`) and for Windows (`install.ps1`) work the same way. Both install the latest release unless you pick a version, verify the download against the release checksums, and also read the `NSCALE_VERSION` and `NSCALE_INSTALL_DIR` environment variables, which is convenient in CI. You can read both scripts in the [nscaledev/homebrew-tap](https://github.com/nscaledev/homebrew-tap) repository before running them.

### Install script (macOS and Linux)

Run the install script:

```bash theme={null}
curl -fsSL https://docs.nscale.com/cli/install.sh | sh
```

The script installs `nscale` into `/usr/local/bin` if it is writable, otherwise into `~/.local/bin`. If `nscale` there was installed with Homebrew, the script stops and leaves it alone; use `brew upgrade nscale` instead. Pass `-v` to install a specific version and `-b` to choose the directory:

```bash theme={null}
curl -fsSL https://docs.nscale.com/cli/install.sh | sh -s -- -v 6.2.0 -b ~/.local/bin
```

### PowerShell (Windows)

Run the install script in PowerShell:

```powershell theme={null}
irm https://docs.nscale.com/cli/install.ps1 | iex
```

The script installs `nscale.exe` into `%LOCALAPPDATA%\Programs\nscale` and adds that directory to your user `PATH`; open a new terminal afterwards. To install a specific version or choose the directory, pass `-Version` and `-InstallDir`:

```powershell theme={null}
& ([scriptblock]::Create((irm https://docs.nscale.com/cli/install.ps1))) -Version 6.2.0 -InstallDir C:\Tools\nscale
```

Pass `-NoPathUpdate` to leave your `PATH` unchanged.

### Homebrew (macOS and Linux)

You can install the CLI using Homebrew:

```bash theme={null}
# Tap our Homebrew repository
brew tap nscaledev/nscale

# Install the CLI
brew install nscale
```

Alternatively, you can combine both steps into a single command:

```bash theme={null}
brew install nscaledev/tap/nscale
```

### Download binary

Download the archive for your operating system from the [releases page](https://github.com/nscaledev/homebrew-tap/releases), extract it, and put `nscale` on your `PATH`.

## Authentication

Before using any commands that interact with Nscale resources, authenticate with:

```bash theme={null}
nscale login
```

This opens a browser window to complete authentication. On success, your credentials are stored locally.

To log out:

```bash theme={null}
nscale logout
```

### Credential precedence

The CLI resolves which credentials to use in this order, from highest to lowest priority:

1. **`NSCALE_SERVICE_TOKEN` environment variable** — when set, the token is used directly and every source below is ignored (no keyring lookup happens at all).
2. **`-u, --user` flag, when explicitly passed** — selects that named entry from the local keyring (the one created by `nscale login`) and takes precedence over any active context.
3. **Active context's user** — the `user` field of the context selected via `--context`, the `NSCALE_CONTEXT` environment variable, or previously set with `nscale contexts use`. Used whenever `-u` is not passed on the command line.
4. **`default` keyring entry** — the fallback when no context is active and `-u` was not passed.

> [!WARNING]
>
> If `NSCALE_SERVICE_TOKEN` is set in your shell, it silently overrides `nscale login`, `--user`, and any context — even if the token belongs to a different organization than you expect. When a command behaves unexpectedly (wrong org, "unauthorized", missing resources), check this first:
>
> ```bash theme={null}
> echo "$NSCALE_SERVICE_TOKEN"
> ```
>
> Unset it with `unset NSCALE_SERVICE_TOKEN` to fall back to your stored credentials.

## Global flags

These flags are available on every command:

| Flag | Description |
| - | - |
| `--org string` | Organization ID or name — applies to all commands that need an organization. Falls back to `NSCALE_ORG` (unless `--context` is passed), then to the active context |
| `--ci` | Indicates the CLI is running in a CI environment (also set via `CI` env var). Prompts and confirmations fail instead of waiting for input |
| `--context string` | Specify the context to use. Falls back to `NSCALE_CONTEXT` |
| `-u, --user string` | Specify the user credentials to use (default: `"default"`) |
| `--format string` | Output audience: `human`, `agent`, `json`, `yaml`, `quiet`, or `script`. Detected when unset — see [Output formats](#output-formats) |
| `--no-truncate` | Show table values in full instead of clipping them to the terminal width |
| `--version` | Display the CLI version, same as [`nscale version`](https://docs.nscale.com/docs/cli/version) |
| `-h, --help` | Show help for any command |

## Environment variables

| Variable | Description |
| - | - |
| `CI` | Set to `true` or `1` to behave as if `--ci` were passed. An explicit `--ci` flag takes precedence |
| `NSCALE_CONTEXT` | Select the saved context to use; `--context` wins |
| `NSCALE_ORG` | Select the organization ID or name, ahead of the saved context's; `--org` and `--context` win |
| `NSCALE_OUTPUT_FORMAT` | Override the detected output audience. Same values as `--format`; `--format` wins |
| `NSCALE_SERVICE_TOKEN` | Service token for authorization — bypasses stored credentials, useful for CI/CD |

## Contexts

Contexts let you switch between different organizations and user configurations without re-specifying flags on every command.

```bash theme={null}
# Create or update a context
nscale contexts set my-context --org <org-id>

# Switch to a context
nscale contexts use my-context

# List all contexts
nscale contexts list
```

To pick a context or organization for a whole shell session without switching the saved context, set `NSCALE_CONTEXT` or `NSCALE_ORG` instead.

## Command structure

Commands take the shape `nscale <resource> [<sub-resource>] <verb> [flags]`. Resources are named in kebab-case (`file-storage`, `security-groups`, `service-accounts`), and resources that belong to another resource are nested under it as a sub-resource, for example:

```bash theme={null}
nscale object-storage access-key list <endpoint-id>
nscale placements server reboot <placement-id> --server <server-id>
nscale file-storage snapshot list <file-storage-id>
```

These are the canonical names since v7. The earlier names, such as `filestorage`, `securitygroups`, `serviceaccounts`, `instances consoleoutput`, `object-storage create-access-key`, `placements servers`, and `inferencing list-models`, are kept as aliases, so existing scripts keep working; these pages use the new names. Every `list` command also answers to `ls`, and every `delete` to `rm`.

### IDs and names

Commands that act on one resource take its ID either as a positional argument (`nscale instances get <instance-id>`) or with `--id`; passing both is an error unless they match. Every flag or argument that takes an ID also accepts the resource's name, including `--org`, `--project`, and `--region`:

```bash theme={null}
nscale instances list --org acme --project web --region no-glo1
```

A name that matches no resource, or more than one, fails with exit status 2 and lists the candidates, so pass an ID when names may be ambiguous.

## Output formats

By default, `list` commands print a table and commands that return one resource print it as JSON. Most commands that return data also accept `--json`, which emits the full JSON payload (the same as `--format json` for that one command), and [`-q`](https://docs.nscale.com/docs/cli/query-output), which extracts fields with a jq filter:

```bash theme={null}
nscale instances list --org <org-id> --json
```

`--json` and `-q` are mutually exclusive — pick whichever fits your downstream tooling. Both take precedence over `--format`.

### Choosing a format with `--format`

`--format` (or the `NSCALE_OUTPUT_FORMAT` environment variable; `--format` wins) sets how every command in the invocation renders its output:

| Format | Output |
| - | - |
| `human` | Styled tables and pretty-printed, highlighted JSON. The default at a terminal |
| `agent` | Lists as TSV with a lowercase header row, nothing truncated. The default when the CLI detects it is running under a coding agent |
| `json` | Every command emits JSON, as if `--json` were passed to each |
| `yaml` | The same document as `json`, rendered as YAML |
| `quiet` | Plain output with all decoration dropped |
| `script` | Plain text with no ANSI styling and compact JSON. The default when output is piped or `--ci` is set |

When `--format` is unset, the CLI detects the audience from the agent harness, the terminal, or the pipe. Detection only picks how output is rendered: it never implies `--yes`, skips a confirmation, or changes what a command does.

A human table clips long values to the terminal width. Pass `--no-truncate` to show them in full, at the cost of a table wider than the terminal. Only tables clip: `agent`, `json`, and `-q` output never does.

A list is always a bare JSON array of resources under `--json`, `--format json`, and `--format yaml`, with no wrapper object. The exceptions are the [`s3api`](https://docs.nscale.com/docs/cli/s3api) commands, which return the AWS response object as-is.

### Limiting list output

Every `list` command accepts `--limit N` to show at most N results, in every format. The limit is applied client-side, so every result is still fetched; when it cuts the list, the CLI prints a `Note:` on stderr. `--limit 0` (the default) shows all results.

`--limit` cuts the list before [`-q`](https://docs.nscale.com/docs/cli/query-output) runs, so a `select` filter only sees the first N results. To cap the number of matches instead, slice inside the filter:

```bash theme={null}
nscale instances list -q '[.[] | select(.status.powerState == "Running")][:5]'
```

### Output streams and exit status

Data goes to stdout; diagnostics, prompts, and warnings go to stderr, so `nscale ... --json | jq` is always safe. Errors are printed to stderr as `Error: <message>`.

After a successful mutation, the CLI may print one `Hint:` line on stderr naming the command you most likely want to run next, such as the `get` that checks a new resource's status. `--format quiet` drops it.

The exit status tells scripts what went wrong without parsing stderr:

| Status | Meaning |
| - | - |
| `0` | Success |
| `1` | Any other failure |
| `2` | Usage error: unknown command, bad flag or argument, invalid `-q` filter, or a name that matches no resource or several |
| `4` | Credentials are missing or were refused. Run `nscale login`, or provide a new service token |

## Input formats

`create` and `update` commands accept input from a JSON file (`--file`) or standard input (`--stdin`):

```bash theme={null}
nscale instances create --file instance.json
cat instance.json | nscale instances create --stdin
```

Use `--dry-run` to preview the request payload without making any changes. The payload is always printed as JSON, whatever `--format` is, since that is what is sent to the API:

```bash theme={null}
nscale instances create --file instance.json --dry-run
```

## Waiting for asynchronous operations

Creating, deleting, starting, or stopping some resources returns before the operation finishes. Commands that do this accept `--wait`, which blocks until the resource is ready, reaches the requested power state, or is gone:

```bash theme={null}
nscale instances create --file instance.json --wait
nscale instances stop <instance-id> --wait --wait-timeout 10m
```

The CLI polls every 2 seconds, backing off to 15 seconds. `--wait-timeout` sets how long to wait (default `30m`). When output is piped, progress goes to stderr only. If the resource enters a failure state, the timeout passes, or you press Ctrl-C, the command exits with status 1 and names the `get` command to check on it; the operation itself keeps running.

## Interactive mode

When running at a terminal outside of a CI environment, the CLI falls back to interactive prompts for any missing parameters. This means you can run commands without flags and be guided through the required inputs step by step.

If you omit the ID of the resource a command acts on, the CLI opens an interactive picker, so always pass it in scripts. Without a terminal, or under `--ci`, the error names the missing flag and, where there is one, a `list` command that prints valid values.

For example, `list` commands will present an organization picker if `--org` is not provided:

![Instances list with interactive org picker](https://mintcdn.com/nscale/eHooAh3A-xA3WCln/images/cli/instances-list.gif?s=6a271748239898f8261cf6877cf51e23)

`create` commands will prompt for each required field when no `--file` or `--stdin` input is given:

![Instances create with interactive field prompts](https://mintcdn.com/nscale/eHooAh3A-xA3WCln/images/cli/instances-create.gif?s=349f3ced9c40879c7ab662dd94a01340)

To suppress interactive prompts (e.g. in scripts), pass `--ci` or set the `CI` environment variable. With prompts suppressed, a missing value is an error, and so is a confirmation: commands that ask before acting (most deletes and other mutations) fail unless you also pass `--yes`. Every command that asks for confirmation accepts `--yes`, so any of them can run unattended. A few never ask, and so take no `--yes`: [`logout`](https://docs.nscale.com/docs/cli/logout), [`contexts clear`](https://docs.nscale.com/docs/cli/contexts#clear), and the `s3api` commands `delete-bucket-tagging`, `delete-object-tagging`, `delete-bucket-lifecycle`, and `abort-multipart-upload`.

```bash theme={null}
nscale instances delete <instance-id> --yes --ci
```

## Shell completion

### Bash

```bash theme={null}
# Load completions for current session
source <(nscale completion bash)

# To load completions for every new session, execute once:

# Linux:
sudo nscale completion bash > /etc/bash_completion.d/nscale

# macOS:
# First, ensure bash-completion is installed
# brew install bash-completion
nscale completion bash > $(brew --prefix)/etc/bash_completion.d/nscale
# Then add to ~/.bash_profile:
# [[ -r "$(brew --prefix)/etc/profile.d/bash_completion.sh" ]] && . "$(brew --prefix)/etc/profile.d/bash_completion.sh"
```

### Zsh

```bash theme={null}
# Load completions for current session
source <(nscale completion zsh)

# To load completions for every session, execute once:
# First, check your fpath directories to find the right location:
echo $fpath

# Then, create a directory for completions if it doesn't exist:
mkdir -p ~/.zsh/completions
nscale completion zsh > ~/.zsh/completions/_nscale

# If shell completion is not already enabled in your environment,
# you will need to enable it. You can execute the following once:
echo 'fpath=(~/.zsh/completions $fpath)' >> ~/.zshrc
echo 'autoload -Uz compinit && compinit' >> ~/.zshrc

# You will need to source your ~/.zshrc or start a new shell for this setup to take effect.
source ~/.zshrc
```

### Fish

```bash theme={null}
# Load completions for current session
nscale completion fish | source

# To load completions for every session, execute once:
mkdir -p ~/.config/fish/completions
nscale completion fish > ~/.config/fish/completions/nscale.fish
```

### PowerShell

```powershell theme={null}
# Load completions for current session
nscale completion powershell | Out-String | Invoke-Expression

# To load completions for every new session, run:
nscale completion powershell > nscale.ps1
# and source this file from your PowerShell profile.
```

## Query output with `-q`

Most commands that return data accept `-q, --query`, which runs the JSON response through a [jq](https://jqlang.github.io/jq/) filter so you can extract a field or reshape the output without piping into a second process. See [Query output with `-q`](https://docs.nscale.com/docs/cli/query-output) for examples.

## Available commands

These pages track the latest CLI release. If a command below is not recognized, check your version with [`nscale version`](https://docs.nscale.com/docs/cli/version) and upgrade — `brew upgrade nscale`, or download a newer binary from the [releases page](https://github.com/nscaledev/homebrew-tap/releases).

| Command | Description |
| - | - |
| [`contexts`](https://docs.nscale.com/docs/cli/contexts) | Manage CLI contexts |
| [`docs`](https://docs.nscale.com/docs/cli/docs) | Print the CLI's own documentation |
| [`file-storage`](https://docs.nscale.com/docs/cli/file-storage) | Manage file storage resources |
| [`flavors`](https://docs.nscale.com/docs/cli/flavors) | List available compute flavors |
| [`groups`](https://docs.nscale.com/docs/cli/groups) | Manage groups |
| [`images`](https://docs.nscale.com/docs/cli/images) | Manage compute images |
| [`inferencing`](https://docs.nscale.com/docs/cli/inferencing) | Manage inferencing resources |
| [`instances`](https://docs.nscale.com/docs/cli/instances) | Manage compute instances |
| [`kubernetes`](https://docs.nscale.com/docs/cli/kubernetes) | Manage Kubernetes clusters, node pools, and kubeconfigs |
| [`load-balancers`](https://docs.nscale.com/docs/cli/load-balancers) | Manage load balancers |
| [`login`](https://docs.nscale.com/docs/cli/login) | Authenticate with Nscale |
| [`logout`](https://docs.nscale.com/docs/cli/logout) | Log out of the CLI |
| [`networks`](https://docs.nscale.com/docs/cli/networks) | Manage VPC networks |
| [`object-storage`](https://docs.nscale.com/docs/cli/object-storage) | Manage object storage endpoints, policies, and access keys |
| [`organizations`](https://docs.nscale.com/docs/cli/organizations) | List organizations |
| [`placements`](https://docs.nscale.com/docs/cli/placements) | Manage GPU placements |
| [`projects`](https://docs.nscale.com/docs/cli/projects) | Manage projects |
| [`regions`](https://docs.nscale.com/docs/cli/regions) | List available regions |
| [`reservations`](https://docs.nscale.com/docs/cli/reservations) | Manage GPU reservations |
| [`roles`](https://docs.nscale.com/docs/cli/roles) | List available roles |
| [`s3api`](https://docs.nscale.com/docs/cli/s3api) | Manage buckets and objects on object storage endpoints |
| [`security-groups`](https://docs.nscale.com/docs/cli/security-groups) | Manage security groups |
| [`service-accounts`](https://docs.nscale.com/docs/cli/service-accounts) | Manage service accounts |
| [`ssh-cas`](https://docs.nscale.com/docs/cli/ssh-cas) | Manage SSH certificate authorities |
| [`users`](https://docs.nscale.com/docs/cli/users) | Manage users |
| [`version`](https://docs.nscale.com/docs/cli/version) | Display the CLI version |
