CLI Commands

Complete reference for all PolarGrid CLI commands.

Authentication

polargrid login              # Browser OAuth flow
polargrid login --headless   # Show CI/CD instructions
polargrid logout             # Clear stored credentials
polargrid whoami             # Show current user and organization

Opens browser for OAuth authentication:

polargrid login

For CI/CD, use environment variable instead:

export POLARGRID_API_KEY="pg_your_key"

Whoami

Shows your current authentication context:

polargrid whoami

Output:

User
  Email: you@example.com
  ID:    abc123

Current Organization
  Name: My Company
  ID:   org_xyz
  Plan: pro

Organizations

polargrid orgs list              # List organizations you belong to
polargrid orgs switch <org_id>   # Switch to a different organization
polargrid orgs current           # Show current organization

List Organizations

polargrid orgs list

Shows all organizations you’re a member of, with your role in each.

Switch Organization

# By ID
polargrid orgs switch org_abc123

# By partial ID
polargrid orgs switch abc

# By name (case-insensitive)
polargrid orgs switch "my company"

# By slug
polargrid orgs switch my-company

API Keys

polargrid keys list                    # List API keys
polargrid keys create <name>           # Create a new API key
polargrid keys revoke <key_id>         # Revoke an API key

Create Key

polargrid keys create my-app-key
polargrid keys create prod-key --permissions admin
polargrid keys create dev-key --permissions read-only
polargrid keys create project-key --project proj_123

Options:

-p, --permissions <level>: read-only, read-write, or admin (default: read-write)
--project <id>: Scope key to a specific project

Copy your API key immediately — you won’t be able to see it again!

Revoke Key

polargrid keys revoke key_abc123
polargrid keys revoke key_abc123 --yes  # Skip confirmation

Inference

Chat

Interactive streaming chat with edge models:

# Interactive mode (multi-turn conversation)
polargrid chat

# Single-shot mode
polargrid chat "What is the capital of France?"
polargrid chat "Explain quantum computing" --no-interactive

# With options
polargrid chat --model qwen-3.5-27b --region yto-01 --system "You are a helpful assistant"

Options:

-r, --region <region>: Edge region
-m, --model <model>: Model (default: qwen-3.5-27b)
-s, --system <prompt>: System prompt
-t, --temperature <n>: Temperature 0.0-2.0 (default: 0.7)
--no-interactive: Single-shot mode, no follow-up

In interactive mode, type /exit or /quit to end the conversation.

Completions

Generate text completions:

polargrid completions "The capital of Canada is"
polargrid completions "Once upon a time" --max-tokens 500 --temperature 0.9

Options:

-r, --region <region>: Edge region
-m, --model <model>: Model (default: qwen-3.5-27b)
--max-tokens <n>: Maximum tokens (default: 200)
-t, --temperature <n>: Temperature 0.0-2.0 (default: 0.7)

Text-to-Speech

Convert text to audio:

polargrid tts "Hello from PolarGrid"
polargrid tts "Welcome to our platform" --voice af_bella --output welcome.mp3
polargrid tts "Quick announcement" --format wav --speed 1.2

Options:

-r, --region <region>: Edge region
-m, --model <model>: TTS model (default: kokoro-82m)
-v, --voice <voice>: Voice (default: af_bella)
-f, --format <format>: mp3, wav, opus, flac (default: mp3)
-o, --output <file>: Output file (default: output.<format>, e.g., output.mp3)
--speed <n>: Speed 0.25-4.0 (default: 1.0)

Available voices: alloy, echo, fable, onyx, nova, shimmer, af_bella, af_sarah, am_adam, am_michael, bf_emma, bf_isabella, bm_george, bm_lewis

Transcribe

Transcribe audio to text:

polargrid transcribe recording.mp3
polargrid transcribe meeting.wav --language en --format srt --output subtitles.srt
polargrid transcribe audio.mp3 --format verbose_json

Options:

-r, --region <region>: Edge region
-m, --model <model>: STT model (default: whisper-large-v3-turbo)
-l, --language <lang>: Language code (e.g., en, fr, es)
-f, --format <format>: text, json, srt, vtt, verbose_json (default: text)
-o, --output <file>: Output file (default: stdout)

Translate

Translate audio to English:

polargrid translate french-audio.mp3
polargrid translate interview.wav --format json --output translation.json

Options:

-r, --region <region>: Edge region
-m, --model <model>: STT model (default: whisper-large-v3-turbo)
-f, --format <format>: text, json (default: text)
-o, --output <file>: Output file (default: stdout)

Models

Manage models on edge servers. Requires POLARGRID_API_KEY.

polargrid models list            # List available models
polargrid models status          # Show model loading status

List Models

polargrid models list --region yto-01

Model Status

polargrid models status --region yto-01

Shows which models are loaded, loading, or failed with colored status indicators.

GPU

Monitor and manage GPU resources. Requires POLARGRID_API_KEY.

polargrid gpu status             # GPU utilization and info
polargrid gpu memory             # GPU memory usage

GPU Status

polargrid gpu status --region yto-01

Shows GPU name, utilization %, memory usage, temperature, and running processes.

GPU Memory

polargrid gpu memory --region yto-01

Visual bar chart of memory usage per GPU.

Regions

polargrid regions list           # List available regions with latency
polargrid regions ping           # Ping all regions, show RTT

List Regions

polargrid regions list

Shows all regions with current latency from your location.

Ping Regions

polargrid regions ping
polargrid regions ping --count 5  # 5 pings per region (default: 3)

Shows min/avg/max latency to each region.

Testing

polargrid test                   # Health check (default)
polargrid test health            # Check edge infrastructure health
polargrid test inference         # Run a quick inference test

Health Check

# Check all regions
polargrid test health

# Check specific region
polargrid test health --region yto-01

Inference Test

polargrid test inference \
  --region yto-01 \
  --model qwen-3.5-27b \
  --prompt "What is the capital of France?"

Options:

-r, --region <region>: Target region (required unless default set)
-m, --model <model>: Model to use (default: qwen-3.5-27b)
-p, --prompt <prompt>: Prompt to send (default: “Hello, how are you?”)

Shell Completions

This is polargrid completion (singular) — not to be confused with polargrid completions (text inference).

polargrid completion bash        # Generate bash completions
polargrid completion zsh         # Generate zsh completions
polargrid completion fish        # Generate fish completions

Install completions for your shell:

# Bash
eval "$(polargrid completion bash)" >> ~/.bashrc

# Zsh
eval "$(polargrid completion zsh)" >> ~/.zshrc

# Fish
polargrid completion fish > ~/.config/fish/completions/polargrid.fish

Configuration

polargrid config list            # Show current config
polargrid config get <key>       # Get a config value
polargrid config set <key> <val> # Set a config value
polargrid config unset <key>     # Remove a config value

Available Config Options

Key	Description
`default_region`	Default edge region for requests
`output_format`	Output format: `json`, `table`, or `plain`
`api_base_url`	Override API base URL
`supabase_url`	Supabase project URL
`supabase_anon_key`	Supabase anonymous key

Examples

# Set default region
polargrid config set default_region yto-01

# Check default region
polargrid config get default_region

# Clear default region
polargrid config unset default_region

# View all config
polargrid config list

Configuration Files

The CLI stores configuration in ~/.polargrid/:

File	Description
OS keychain entry	Auth tokens, encrypted at rest (macOS Keychain / Windows Credential Manager / Linux Secret Service)
`credentials.enc`	AES-256-GCM encrypted token fallback (mode 0600) — used only where no keychain is available, e.g. headless Linux/CI
`config.json`	CLI configuration (non-secret)

Set POLARGRID_DISABLE_KEYCHAIN=1 to force the encrypted-file backend. An existing plaintext credentials.json from an older CLI is migrated into the encrypted store on first use and then deleted.

CI/CD Example

#!/bin/bash
# ci-test.sh

export POLARGRID_API_KEY="${POLARGRID_API_KEY}"

# Health check
polargrid test health --region yto-01

# Run inference test
polargrid test inference \
  --region yto-01 \
  --model qwen-3.5-27b \
  --prompt "Integration test: respond with OK"

# Single-shot chat
polargrid chat "Summarize: PolarGrid is an edge AI platform" --no-interactive --region yto-01

​CLI Commands

​Authentication

​Login

​Whoami

​Organizations

​List Organizations

​Switch Organization

​API Keys

​Create Key

​Revoke Key

​Inference

​Chat

​Completions

​Text-to-Speech

​Transcribe

​Translate

​Models

​List Models

​Model Status

​GPU

​GPU Status

​GPU Memory

​Regions

​List Regions

​Ping Regions

​Testing

​Health Check

​Inference Test

​Shell Completions

​Configuration

​Available Config Options

​Examples

​Configuration Files

​CI/CD Example

CLI Commands

Authentication

Login

Whoami

Organizations

List Organizations

Switch Organization

API Keys

Create Key

Revoke Key

Inference

Chat

Completions

Text-to-Speech

Transcribe

Translate

Models

List Models

Model Status

GPU

GPU Status

GPU Memory

Regions

List Regions

Ping Regions

Testing

Health Check

Inference Test

Shell Completions

Configuration

Available Config Options

Examples

Configuration Files

CI/CD Example