Gravi CLI

Command-line tool for Gravitate infrastructure management. Provides CLI access to mom infrastructure, allowing developers to authenticate, manage tokens, and access instance configurations and credentials.

For agents: there's a sister command, gravi-axi — an AXI surface over the same burner tooling with TOON output, pre-computed aggregates, structured errors, and one-call up/wait. Ships from this same package. See AXI.md.

Features

OAuth-style device authorization - Secure browser-based authentication
Automatic token refresh - Tokens auto-renew when <7 days remaining
Token management - List, revoke, and manage CLI tokens
Instance access - Get configurations and credentials for Gravitate instances
Python library API - Use programmatically in scripts and applications
CI/CD support - Environment variable-based authentication

Installation

From Source (Development)

Using uv (recommended):

cd /home/jvogel/src/work/tools/mom/cli
uv pip install -e ".[test]"

Or with traditional pip:

cd /home/jvogel/src/work/tools/mom/cli
pip install -e ".[test]"

From PyPI (Future)

pip install gravi-cli
# or
uv pip install gravi-cli

Quick Start

Note: If you installed with uv pip install -e ., you can run the CLI using uvx --from . gravi or just gravi if it's in your PATH.

1. Login

gravi login
# or with uvx:
uvx --from . gravi login

This will:

Open your browser to mom authorization page
Display a user code (e.g., ABCD-1234)
Wait for you to authorize in the browser
Save credentials to ~/.config/gravi/config.json

2. Check Status

gravi status

Shows:

Current user email
Mom URL
Device name
Token ID
Token expiry

3. Get Instance Configuration

# Get config as JSON
gravi config dev

# Get config as environment variables
gravi config prod --format=env

4. Logout

gravi logout

Revokes token on server and clears local credentials.

CLI Commands

Authentication

gravi login                          # Authenticate via browser
gravi logout                         # Clear credentials and revoke token
gravi status                         # Show login status and token expiry
gravi whoami                         # Show current user info

Token Management

gravi tokens list                    # List all CLI tokens
gravi tokens revoke <token_id>       # Revoke a specific token
gravi tokens revoke --all            # Revoke all tokens

Instance Access

gravi config <instance_key>          # Get instance configuration
gravi config <instance_key> --format=env    # Get as environment variables

Seed Datasets

A dataset version is the whole payload, not a patch — publishing one that omits a tab publishes a dataset without that tab, and the burner it seeds still boots ready. So push sends everything and refuses a payload missing tanks, supply or drivers; --merge layers the tabs you edited onto the latest version instead.

gravi dataset list [--q costco] [--tag e2e]
gravi dataset show <name> [--version 3]      # counts, services, version history
gravi dataset diff <name> [--against 8]      # row-level, per tab

gravi dataset clone <name> <new-name>        # never edit a shared dataset in place
gravi dataset pull <name> [-o dir]           # one JSON file per tab, sorted keys
$EDITOR <name>/drivers.json
gravi dataset push <name> --notes "why"      # append a new version
gravi dataset push <name> --merge            # only the tabs present on disk
gravi dataset push <name> --dry-run          # report the shape, send nothing

gravi dataset sheet export <name> --open     # edit in Sheets instead
gravi dataset sheet import <name> <sheet-id>

pull writes stable, sorted JSON with one file per tab, so a dataset can live in a repo and a rename across it reviews as an ordinary diff. Non-row keys (title, service_config, seeding_config, env_overrides) land in _meta.json, and push reassembles them — the round trip is lossless.

Python Library API

Use gravi_cli programmatically in Python scripts:

from gravi_cli.api import get_instance_config, get_instance_token

# Get database credentials
config = get_instance_config("prod")
db_url = config["config"]["database_url"]

# Get ServiceNow access token
token_response = get_instance_token("dev")
sn_token = token_response["access_token"]

# Get mom access token directly
from gravi_cli.api import get_mom_token
mom_token = get_mom_token()  # Auto-refreshes if needed

Example: Database Connection

from gravi_cli.api import get_instance_config
import psycopg2

# Get prod database credentials
config = get_instance_config("prod")
conn = psycopg2.connect(config["config"]["database_url"])

# Use database
cursor = conn.cursor()
cursor.execute("SELECT * FROM users LIMIT 10")

Example: ServiceNow API

from gravi_cli.api import get_instance_config, get_instance_token
import requests

# Get ServiceNow config and token
config = get_instance_config("dev")
token_response = get_instance_token("dev")

# Make ServiceNow API call
response = requests.get(
    f"{config['api_url']}/api/now/table/incident",
    headers={"Authorization": f"Bearer {token_response['access_token']}"}
)
incidents = response.json()

CI/CD Usage

For automated scripts and CI/CD pipelines:

# Set refresh token as environment variable
export GRAVI_REFRESH_TOKEN="your_refresh_token_here"

# Commands will automatically use the env var
gravi config prod

Getting a CI/CD token:

Run gravi login on your local machine
Run gravi tokens list to see your token ID
Copy the refresh token from ~/.config/gravi/config.json
Set as GRAVI_REFRESH_TOKEN in your CI/CD system

Security Note: Treat GRAVI_REFRESH_TOKEN like a password. Use secret management systems (GitHub Secrets, AWS Secrets Manager, etc.) to store it securely.

Configuration

Config File Location

~/.config/gravi/config.json

Config File Format

{
  "version": 1,
  "user_email": "john.doe@gravitate.com",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token_expires_at": "2025-11-09T10:30:00Z",
  "token_id": "507f1f77bcf86cd799439011",
  "device_name": "John's MacBook"
}

Environment Variables

GRAVI_MOM_URL - Override mom API URL (default: https://mom.gravitate.energy)
GRAVI_REFRESH_TOKEN - CI/CD refresh token (bypasses config file)

File Permissions

Config file is automatically set to 0600 (owner read/write only) for security.

Token Auto-Renewal

Refresh tokens are automatically renewed when <7 days remaining:

CLI checks expiry on each use
If <7 days: requests new 14-day token
Config file updated automatically
Seamless for users - no re-login needed

Development

Setup

cd /home/jvogel/src/work/tools/mom/cli
pip install -e ".[test]"

Run Tests

# All tests
pytest

# With coverage
pytest --cov=gravi_cli --cov-report=term-missing

# Specific test file
pytest tests/test_config.py

# Verbose
pytest -v

Project Structure

cli/
├── gravi_cli/
│   ├── __init__.py          # Package metadata
│   ├── api.py               # Public Python API
│   ├── auth.py              # Token refresh and auth logic
│   ├── cli.py               # CLI commands (Click)
│   ├── client.py            # Mom API client
│   ├── config.py            # Config file management
│   └── exceptions.py        # Custom exceptions
├── tests/
│   ├── conftest.py          # Pytest fixtures
│   ├── test_config.py       # Config tests
│   └── test_client.py       # API client tests
├── pyproject.toml           # Package configuration
└── README.md                # This file

Troubleshooting

"Not logged in" Error

gravi login

"Token expired" Error

Tokens auto-renew, but if expired:

gravi login

Rate Limiting

If you hit rate limits, wait and retry. Rate limits reset every minute.

Mom URL Override (Development)

# Temporary override
GRAVI_MOM_URL=https://mom.dev gravi login

# Or with flag
gravi login --mom-url=https://mom.dev

Security

Refresh tokens stored in config file with 0600 permissions
Access tokens never persisted (in-memory only)
No tokens in CLI arguments (prevents shell history exposure)
HTTPS only for all API calls
Audit logging - All token operations logged in mom

Support

For issues or questions:

GitHub Issues: https://github.com/gravitate/mom/issues
Internal Slack: #engineering

License

MIT

Metadata

Release files for gravi-cli 0.15.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Built distribution (wheel)

Table of built distributions (wheels) for gravi-cli 0.15.0
File	Interpreter	ABI	Platform	Reset
gravi_cli-0.15.0-py3-none-any.whl 90.3 kB Sep 7, 2026	Python 3	none	any	Details

Release files / gravi_cli-0.15.0-py3-none-any.whl

Download URL	gravi_cli-0.15.0-py3-none-any.whl
Size	90.3 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`38caf1786996bb44db95109e78ac1282f0b5de0160eb9a99a2b47a12f48d4f31`
BLAKE2b-256 checksum How to use checksums	`5d9a93b42613f6f453089718be4320a07fc14bbe0517b3f249133511f06a6236`
Upload date	Sep 7, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/gravitate-energy/bb_tools
Publishing commit: github.com/gravitate-energy/bb_tools/tree/36d6521e45c31039157e010336b90e3d637cbfaf

Workflow

Publishing configuration: github.com/gravitate-energy/bb_tools/blob/36d6521e45c31039157e010336b90e3d637cbfaf/.github/workflows/publish-gravi-cli.yml
Publishing logs: github.com/gravitate-energy/bb_tools/actions/runs/34153607438/attempts/1

Artifact

Subject: gravi_cli-0.15.0-py3-none-any.whl
SHA-256 checksum: 38caf1786996bb44db95109e78ac1282f0b5de0160eb9a99a2b47a12f48d4f31 Verifying attestations