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 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 — applies to all commands that need an organization context. Falls back 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
`-u, --user string`	Specify the user credentials to use (default: `"default"`)
`--format string`	Output audience: `human`, `agent`, `json`, `quiet`, or `script`. Detected when unset — see Output formats
`--no-truncate`	Show table values in full instead of clipping them to the terminal width
`-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_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

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, 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
`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.

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> and the command exits with status 1; success exits with 0.

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:

nscale instances create --file instance.json --dry-run

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. 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. If you omit it, the CLI opens an interactive picker, so always pass it in scripts. 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:

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
`filestorage`	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
`securitygroups`	Manage security groups
`serviceaccounts`	Manage service accounts
`ssh-cas`	Manage SSH certificate authorities
`users`	Manage users
`version`	Display the CLI version

​Installation

​Download binary

​Homebrew (for macOS users)

​Authentication

​Credential precedence

​Global flags

​Environment variables

​Contexts

​Output formats

​Choosing a format with --format

​Output streams and exit status

​Input formats

​Interactive mode

​Shell completion

​Bash

​Zsh

​Fish

​PowerShell

​Query output with -q

​Available commands