amentum-cli

amentum-cli is a cross-platform command line client for the Amentum APIs:

• https://ocean.amentum.io/openapi.json
• https://atmosphere.amentum.io/openapi.json
• https://avrad.amentum.io/openapi.json
• https://geomag.amentum.io/openapi.json
• https://gravity.amentum.io/openapi.json

Features

• Shared API key stored in a local config file
• Disk-backed response cache
• --refresh flag to bypass cache
• Latitude/longitude range sweeps for atmosphere, geomag, gravity, and ocean
• Coordinate-grid expansion when both latitude and longitude ranges are supplied
• Async multi-request execution with CLI progress output on stderr
• Dynamic command help sourced from OpenAPI parameter descriptions
• Required/optional parameter markers generated from OpenAPI metadata
• Pure Python runtime for easy packaging on Windows, macOS, and Linux

Install

Use uv to install the CLI.

uv tool install "amentum-cli @ git+https://github.com/amentumspace/amentum-cli.git@main"

For a pinned release, replace main with a tag:

uv tool install "amentum-cli @ git+https://github.com/amentumspace/amentum-cli.git@v0.1.0"

Standalone binaries are produced by GitHub Actions releases for:

• Windows
• macOS
• Linux

To use a standalone binary instead of installing via uv:

1. Open the latest GitHub Release and download the archive for your operating system and CPU architecture. Examples: amentum-Linux-X64.tar.gz, amentum-macOS-ARM64.tar.gz, amentum-Windows-X64.zip.
2. Extract the archive if needed.
3. Put the binary somewhere on your PATH, or run it directly from the extracted directory.

Examples:

# macOS / Linux
./amentum --help

# Windows PowerShell
.\amentum.exe --help

On macOS, standalone release binaries are currently unsigned and not notarized. Gatekeeper may block the first launch with a warning that Apple cannot verify the binary.

If that happens, either:

1. Open System Settings -> Privacy & Security, find the blocked amentum message, and click Open Anyway.
2. Or remove the quarantine attribute from the extracted binary and run it again:

xattr -d com.apple.quarantine ./amentum
./amentum --help

The standalone binaries use the same config file and AMENTUM_API_KEY environment variable as the uv-installed CLI.

API Key

Create an API key through the Amentum developer portal, at https://developer.amentum.io , then either store it in the CLI config or provide it through the environment.

Configuration

Store the shared API key:

amentum config set-api-key YOUR_API_KEY

Show the config file location:

amentum config path

Environment override:

AMENTUM_API_KEY=YOUR_API_KEY amentum gravity egm2008 geoid-height --latitude 10 --longitude 20

Usage

List available commands:

amentum --help
amentum ocean --help
amentum gravity egm2008 geoid-height --help

Generated command help marks each option as required or optional from the vendored OpenAPI spec. For range-capable services, help text also documents that multi-request runs emit objects with parameters, response, and from_cache.

Example request:

amentum gravity egm2008 geoid-height \
  --latitude -33.86 \
  --longitude 151.21

Latitude sweep:

amentum geomag wmmhr \
  --longitude 151.21 \
  --altitude 10 \
  --year 2026 \
  --month 3 \
  --day 29 \
  --range latitude:-90:90:30

Latitude/longitude grid sweep:

amentum gravity egm2008 geoid-height \
  --range latitude:-20:20:20 \
  --range longitude:140:160:20

--range is only supported for latitude and longitude on atmosphere, geomag, gravity, and ocean. avrad operations do not support range expansion.

Bypass the cache:

amentum ocean gebco --latitude 0 --longitude 120 --refresh

JSON lines output for sweeps:

amentum geomag wmmhr \
  --longitude 151.21 \
  --altitude 10 \
  --year 2026 \
  --month 3 \
  --day 29 \
  --range latitude:-90:90:30 \
  --format jsonl

Single requests print the raw API response body. Multi-request runs print envelopes that include:

• parameters: the request parameters used for that call
• response: the API response payload
• from_cache: whether that item came from the local cache

When at least one response is served from cache, the CLI also prints a cache notice on stderr.

Development

Repository maintenance, test commands, CI behavior, OpenAPI spec refresh, and release operations are documented in DEVELOPING.md