Overview - Nscale

Installation

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

Download binary

Download the binary for your operating system from the releases page.

Homebrew (for macOS users)

You can install the CLI using Homebrew:

# Tap our Homebrew repository
brew tap nscaledev/nscale

# Install the CLI
brew install nscale

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

brew install nscaledev/tap/nscale

Authentication

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

nscale login

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

nscale logout

Credential precedence

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

NSCALE_SERVICE_TOKEN environment variable — when set, the token is used directly and every source below is ignored (no keyring lookup happens at all).
-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.
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.
default keyring entry — the fallback when no context is active and -u was not passed.

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:

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
`--no-truncate`	Show table values in full instead of clipping them to the terminal width
`--version`	Display the CLI version, same as `nscale 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.

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

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:

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, which extracts fields with a jq filter:

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 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 runs, so a select filter only sees the first N results. To cap the number of matches instead, slice inside the filter:

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):

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:

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:

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

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

Instances create with interactive field prompts

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, contexts clear, and the s3api commands delete-bucket-tagging, delete-object-tagging, delete-bucket-lifecycle, and abort-multipart-upload.

nscale instances delete <instance-id> --yes --ci

Shell completion

Bash

# 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

# 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

# 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

# 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 filter so you can extract a field or reshape the output without piping into a second process. See Query output with -q for examples.

Available commands

These pages track the latest CLI release. If a command below is not recognized, check your version with nscale version and upgrade — brew upgrade nscale, or download a newer binary from the releases page.

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

CLI

Reference

​Installation

​Download binary

​Homebrew (for macOS users)

​Authentication

​Credential precedence

​Global flags

​Environment variables

​Contexts

​Command structure

​IDs and names

​Output formats

​Choosing a format with --format

​Limiting list output

​Output streams and exit status

​Input formats

​Waiting for asynchronous operations

​Interactive mode

​Shell completion

​Bash

​Zsh

​Fish

​PowerShell

​Query output with -q

​Available commands