@scalar/galaxy-cli

v0.3.2

Published

10 days ago

The Scalar Galaxy is an example OpenAPI document to test OpenAPI tools and libraries. It's a fictional universe with fictional planets and fictional data.

0High
0Medium
0Low

Scalar Galaxy

This library provides convenient access to the Scalar Galaxy REST API from the command line.

The full API of this library can be found in api.md.

Installation

# npm (requires Node.js)
npm install -g @scalar/galaxy-cli

# Homebrew — standalone binary, no Node.js required
brew install --cask scalar/galaxy-cli-tap/galaxy
# Had the `galaxy` formula installed? Run `brew uninstall --formula galaxy` before the install above.

# Direct download — standalone binary, no Node.js required
curl -fsSL "https://github.com/scalar/galaxy-cli/releases/latest/download/galaxy-$(uname -s | tr '[:upper:]' '[:lower:]')-$(uname -m | sed 's/x86_64/x64/;s/aarch64/arm64/').tar.gz" | tar xz galaxy
sudo mv galaxy /usr/local/bin/

# Windows — download and extract galaxy-windows-x64.zip, then add it to PATH
# https://github.com/scalar/galaxy-cli/releases/latest/download/galaxy-windows-x64.zip

Usage

galaxy [resource] [command] [flags]

galaxy planets list-all-data --bearer-auth "$BEARER_AUTH" --limit '10' --offset '0'

Every command accepts the global flags below, so the examples that follow show only what is specific to them.

See the API reference for every available operation.

Signing In

galaxy login signs you in and saves the credential for later commands, so it does not have to be passed every time. It goes into your operating system's credential store — the Keychain on macOS, the system keyring on Linux, Credential Manager on Windows — and falls back to a file in your state directory, readable only by you, when no such store is available. Either way it is filed under the base URL it was captured for, so a credential saved for one host is never sent to another. galaxy logout forgets it. A credential passed with a flag, or set in the environment, still takes precedence over a saved one. Both act on the environment selected with --environment <name> or SCALAR_ENVIRONMENT, so sign in to each environment you call. Sign-in methods: bearer-auth, basic, api-key-header, api-key-query, api-key-cookie, oauth-client-credentials, oauth-password, open-id-connect. Pass --flow <name> to pick one without being asked.

galaxy login
galaxy login --flow bearer-auth
galaxy logout
galaxy logout --all

Environments

This API declares more than one environment. Pass --environment <name> to any command to choose one, or leave it off for production. --base-url sets a URL directly and cannot be combined with it, since each names where the request goes. galaxy environments prints the list for reading and takes --format json for parsing. Set SCALAR_ENVIRONMENT to choose one for every command in a shell; --environment and --base-url both take precedence over it, and it cannot be set together with the base URL environment variable.

production — https://galaxy.scalar.com (default)
void — https://void.scalar.com/

# read them; --format json when a script is parsing
galaxy environments

# call an endpoint against one
galaxy --environment production COMMAND

File Arguments

Any command flag or credential reads its value from a file when the value begins with @, so a body field holding a whole document does not have to survive shell quoting. @file:// always sends the file as text and @data:// always sends it base64-encoded; a bare @ lets the file decide. A flag that uploads a file takes its path with or without the @. Escape a literal value that begins with @ as \@. The global options (--base-url, --timeout, --format and the rest) are read exactly as written.

galaxy COMMAND --FLAG @./body.json
galaxy COMMAND --FLAG @file://./notes.txt
galaxy COMMAND --FLAG @data://./logo.png
galaxy COMMAND --FLAG '\@not-a-file'

Shell Completion

galaxy completion <shell> prints a completion script for bash, zsh, and fish. Add the matching line to your shell startup file to complete commands, subcommands, and flags with Tab.

# bash (~/.bashrc)
eval "$(galaxy completion bash)"

# zsh (~/.zshrc)
eval "$(galaxy completion zsh)"

# fish (~/.config/fish/config.fish)
galaxy completion fish | source

Manual Pages

Installing the package globally also installs man pages. man galaxy lists every command, and each command has its own page named after the command with spaces and : replaced by -.

man galaxy
man galaxy-<resource>-<command>

Authentication

Pass credentials to the generated client constructor. Environment variables are read automatically when supported by the target runtime.

| Option | Type | Default | Description | | --- | --- | --- | --- | | --bearer-auth | <value> | - | JWT Bearer token authentication Defaults to BEARER_AUTH. | | --basic-auth-username | <value> | - | Basic HTTP authentication Defaults to BASIC_AUTH_USERNAME. | | --basic-auth-password | <value> | - | Basic HTTP authentication Defaults to BASIC_AUTH_PASSWORD. | | --api-key-header | <value> | - | API key request header Defaults to API_KEY_HEADER. | | --api-key-query | <value> | - | API key query parameter Defaults to API_KEY_QUERY. | | --api-key-cookie | <value> | - | API key browser cookie Defaults to API_KEY_COOKIE. | | --o-auth2 | <value> | - | OAuth 2.0 authentication Defaults to SCALAR_O_AUTH2. | | --open-id-connect | <value> | - | OpenID Connect Authentication Defaults to SCALAR_OPEN_ID_CONNECT. |

Declared schemes:

bearerAuth bearer token
basicAuth basic authentication
apiKeyHeader API key in header X-API-Key
apiKeyQuery API key in query api_key
apiKeyCookie API key in cookie api_key
oAuth2 OAuth2/OpenID Connect
openIdConnect OAuth2/OpenID Connect

Errors

Failed requests print a structured error to standard error and exit with a status that identifies the failure class. The error body carries the API's own message plus a stable code, the HTTP status, the requestId, and — where one applies — an actionable hint. Usage errors (exit 2) are reported as a plain message instead, since no request was made. Exit statuses: 0 success, 1 error, 2 usage, 10 auth-failed, 11 not-found, 12 rate-limited, 13 client-error, 14 server-error, 15 connection-error.

Documented error statuses: 400, 401, 403, 404, 409, 422, 429.

Client Options

Configure the generated client by setting any of these options when you create it.

| Option | Type | Default | Description | | --- | --- | --- | --- | | --base-url | <url> | - | Override the base URL for API requests. | | --timeout | <ms> | - | Request timeout in milliseconds. | | --max-retries | <count> | - | Number of retries for retryable failures. | | --debug | flag | - | Enable SDK debug logging. | | --environment | <name> | production | Named environment to target: production, void (can also be set with SCALAR_ENVIRONMENT env var). Cannot be combined with --base-url. |

Retries and Timeouts

Generated clients support request timeouts and retry temporary failures such as network errors, 408, 409, 429, and 5xx responses. Retry delays honor Retry-After headers when present. Tune the retry and timeout client options shown above, or override them per request.

Helpers

--format <format> — output format: auto, json, jsonl, pretty, raw, toon, or yaml.
--format-error <format> — error output format: auto, json, jsonl, pretty, raw, toon, or yaml.
--format toon — token-efficient structured output for AI agents; uniform lists collapse into one header plus a row per item, with a definitive item count.
--transform <path> and --transform-error <path> — dot-path transform for data/error output.
--raw-output, -r — print transformed string values without JSON quotes.
--max-items <count> — bound iterator, streaming, and WebSocket command output.
Errors carry a stable code and an actionable hint beside the API's own message, and each failure class exits with its own status: 1 error, 2 usage, 10 auth-failed, 11 not-found, 12 rate-limited, 13 client-error, 14 server-error, 15 connection-error.

Logging

Pass --debug to any command to enable SDK debug logging on stderr.

Requirements

Node.js 20 or newer — for the npm install only; the standalone binaries bundle their own runtime.