CLI Commands

Complete CLI command reference

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

Login

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: [e-mail]
  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