Nirvana Labs CLI

The official CLI for the Nirvana Labs REST API.

Installation

Installing with Homebrew

brew install nirvana-labs/tap/nirvana

Installing with Go

To test or install the CLI locally, you need Go version 1.22 or later installed.

go install 'github.com/nirvana-labs/nirvana-cli/cmd/nirvana@latest'

Once you have run go install, the binary is placed in your Go bin directory:

Default location: $HOME/go/bin (or $GOPATH/bin if GOPATH is set)
Check your path: Run go env GOPATH to see the base directory

If commands aren’t found after installation, add the Go bin directory to your PATH:

# Add to your shell profile (.zshrc, .bashrc, etc.)
export PATH="$PATH:$(go env GOPATH)/bin"

Running Locally

After cloning the git repository for this project, you can use the scripts/run script to run the tool locally:

./scripts/run args...

Usage

The CLI follows a resource-based command structure:

nirvana [resource] <command> [flags...]

nirvana compute:vms create \
  --api-key 'My API Key' \
  --boot-volume '{size: 100, type: abs}' \
  --instance-type n1-standard-2 \
  --name my-vm \
  --os-image-name ubuntu-noble-2025-10-01 \
  --project-id 123e4567-e89b-12d3-a456-426614174000 \
  --public-ip-enabled \
  --region us-sva-2 \
  --ssh-key '{public_key: ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIDBIASkmwNiLcdlW6927Zjt1Hf7Kw/PpEZ4Zm+wU9wn2}' \
  --subnet-id 123e4567-e89b-12d3-a456-426614174000

For details about specific commands, use the --help flag.

Environment variables

Environment variable	Required
`NIRVANA_LABS_API_KEY`	yes

Global flags

--api-key (can also be set with NIRVANA_LABS_API_KEY env var)
--help - Show command line usage
--debug - Enable debug logging (includes HTTP request/response details)
--version, -v - Show the CLI version
--base-url - Use a custom API backend URL
--format - Change the output format (auto, explore, json, jsonl, pretty, raw, yaml)
--format-error - Change the output format for errors (auto, explore, json, jsonl, pretty, raw, yaml)
--transform - Transform the data output using GJSON syntax
--transform-error - Transform the error output using GJSON syntax

Passing files as arguments

To pass files to your API, you can use the @myfile.ext syntax:

nirvana <command> --arg @abe.jpg

Files can also be passed inside JSON or YAML blobs:

nirvana <command> --arg '{image: "@abe.jpg"}'
# Equivalent:
nirvana <command> <<YAML
arg:
  image: "@abe.jpg"
YAML

If you need to pass a string literal that begins with an @ sign, you can escape the @ sign to avoid accidentally passing a file.

nirvana <command> --username '\@abe'

Explicit encoding

For JSON endpoints, the CLI tool does filetype sniffing to determine whether the file contents should be sent as a string literal (for plain text files) or as a base64-encoded string literal (for binary files). If you need to explicitly send the file as either plain text or base64-encoded data, you can use @file://myfile.txt (for string encoding) or @data://myfile.dat (for base64-encoding). Note that absolute paths will begin with @file:// or @data://, followed by a third / (for example, @file:///tmp/file.txt).

nirvana <command> --arg @data://file.txt

Linking different Go SDK versions

You can link the CLI against a different version of the Nirvana Labs Go SDK for development purposes using the ./scripts/link script.

To link to a specific version from a repository (version can be a branch, git tag, or commit hash):

./scripts/link github.com/org/repo@version

To link to a local copy of the SDK:

./scripts/link ../path/to/nirvana-go

If you run the link script without any arguments, it will default to ../nirvana-go.