PolarGrid CLI

Command-line interface for PolarGrid Edge AI Infrastructure.

Installation

npm install -g @polargrid/cli

Quick Start

# Login to PolarGrid
polargrid login

# List your organizations
polargrid orgs list

# Create an API key
polargrid keys create my-app-key

# Test inference
polargrid test inference --region yto-01 --prompt "Hello world"

Commands

Authentication

polargrid login              # Browser OAuth flow
polargrid login --headless   # API key authentication (for CI/CD)
polargrid logout             # Clear stored credentials
polargrid whoami             # Show current user and organization

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

API Keys

polargrid keys list              # List API keys
polargrid keys create <name>     # Create a new API key
  --permissions <level>          # read-only, read-write, or admin
  --project <id>                 # Scope to a specific project
polargrid keys revoke <key_id>   # Revoke an API key

Regions

polargrid regions list           # List available regions with latency
polargrid regions ping           # Ping all regions, show RTT
  --count <n>                    # Number of pings per region (default: 3)

Inference

polargrid chat [prompt]          # Interactive chat (streaming)
  --model <model>                # Model (default: qwen-3.5-9b)
  --region <region>              # Edge region
  --system <prompt>              # System prompt
  --temperature <n>              # Temperature (0.0-2.0)
  --no-interactive               # Single-shot mode

polargrid completions <prompt>   # Text completion (streaming)
  --model <model>                # Model (default: qwen-3.5-9b)
  --max-tokens <n>               # Max tokens (default: 200)

polargrid tts <text>             # Text-to-speech
  --voice <voice>                # Voice (default: af_bella)
  --model <model>                # TTS model (default: kokoro-82m)
  --format <fmt>                 # mp3, wav, opus, flac (default: mp3)
  --output <file>                # Output file (default: output.mp3)
  --speed <n>                    # Speed 0.25-4.0 (default: 1.0)

polargrid transcribe <file>      # Transcribe audio to text
  --model <model>                # STT model (default: whisper-large-v3-turbo)
  --language <lang>              # Language code (e.g., en, fr)
  --format <fmt>                 # text, json, srt, vtt, verbose_json
  --output <file>                # Output file (default: stdout)

polargrid translate <file>       # Translate audio to English
  --model <model>                # STT model
  --format <fmt>                 # text, json
  --output <file>                # Output file

Models & GPU

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

polargrid gpu status             # GPU utilization and info
polargrid gpu memory             # GPU memory usage (visual bar chart)

Testing

polargrid test                   # Health check (default)
polargrid test health            # Check edge infrastructure health
  --region <region>              # Specific region or all
polargrid test inference         # Run a quick inference test
  --region <region>              # Required: target region
  --model <model>                # Model to use (default: qwen-3.5-9b)
  --prompt <prompt>              # Prompt to send

Shell Completions

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

# Install (e.g., for zsh):
eval "$(polargrid completion zsh)" >> ~/.zshrc

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

Config options:

• 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

CI/CD Usage

For CI/CD pipelines, use the --headless flag with an API key:

# Set API key as environment variable
export POLARGRID_API_KEY="pg_your_api_key_here"

# Login in headless mode
polargrid login --headless

# Or pass the key directly
polargrid login --headless --api-key "pg_your_api_key_here"

Configuration Files

The CLI stores configuration in ~/.polargrid/:

• Authentication tokens are stored encrypted at rest in your OS keychain (macOS Keychain, Windows Credential Manager, or Linux Secret Service). Where no keychain is available (e.g. headless Linux/CI), they fall back to an AES-256-GCM encrypted file at ~/.polargrid/credentials.enc (mode 0600). Set POLARGRID_DISABLE_KEYCHAIN=1 to force the encrypted-file backend.
• config.json - CLI configuration (non-secret)

Upgrading from an older CLI: an existing plaintext ~/.polargrid/credentials.json is migrated into the encrypted store on first use and then deleted — you stay logged in.

Development

# Install dependencies
npm install

# Build
npm run build

# Run locally
npm start -- --help

# Watch mode
npm run dev

License

MIT