nimble-cli

Nimble CLI

The official CLI for the Nimble REST API.

It is generated with Stainless.

Installation

Installing with Go

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

go install 'github.com/Nimbleway/nimble-cli/cmd/nimble@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...

Authentication

Run nimble login once and the CLI stores your credentials, so later commands need no --api-key flag:

nimble login

Login offers two methods:

• Browser (default): opens your browser to approve access, then stores the API key it retrieves for your account.
• Paste an API key: enter a key directly. It is validated before it is saved.

Two related commands round this out:

nimble whoami   # show the active credential and where it came from
nimble logout   # remove the stored credential

Credentials are written to ~/.nimble/credentials.json with 0600 permissions. Set NIMBLE_CONFIG_DIR to store them elsewhere.

API keys created by browser login

Browser login creates an API key named after the user and machine that made it, for example CLI (omerm @ MacBook-Pro-8). The name is visible in the Nimble console, so you can tell whose key it is and where it came from. Long names are truncated to the 50 characters the API allows.

Logging in again from the same machine replaces that key, so keys do not pile up. Keys belonging to another machine, to a teammate on the same account, or to a CLI version older than this naming scheme are never touched. Accounts are shared, so a login here must not invalidate a key someone else is still using.

If you used the CLI before this naming scheme existed, a key named Nimble CLI may still be on your account. It is left alone on purpose, since it cannot be attributed to a machine. Remove it in the console once nothing depends on it.

Credential priority

When a command needs an API key, the CLI uses the first source available:

1. --api-key flag (explicit per-command override)
2. Stored credential (from nimble login)
3. NIMBLE_API_KEY environment variable

Note that a stored credential takes precedence over NIMBLE_API_KEY. If a command uses an unexpected key, run nimble whoami to see which source is active, and nimble logout to fall back to the environment variable.

Usage

The CLI follows a resource-based command structure:

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

nimble extract run --url https://example.com

To override the stored credential for a single command, pass --api-key:

nimble extract run \
  --api-key 'My API Key' \
  --url https://example.com

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

Environment variables

Global flags

• --api-key (can also be set with NIMBLE_API_KEY env var, or stored via nimble login)
• --client-source (can also be set with CLIENT_SOURCE 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:

nimble <command> --arg @abe.jpg

Files can also be passed inside JSON or YAML blobs:

nimble <command> --arg '{image: "@abe.jpg"}'
# Equivalent:
nimble <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.

nimble <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).

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

Linking different Go SDK versions

You can link the CLI against a different version of the Nimble 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/githubcomnimblewaynimblego-go

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