polaris-cli 1.0.1

A beautiful and powerful cloud resource management CLI for Polaris Cloud

🚀 Polaris CLI

A beautiful and powerful command-line interface for cloud resource management with a stunning terminal UI, smart resource discovery, and streamlined instance deployment.

🎉 Now available on PyPI! Install with: pip install polaris-cli

🏃‍♀️ Get Started in 30 seconds

# Install
pip install polaris-cli

# Verify installation
polaris --help

# Login 
polaris auth login --api-key pk_admin_your_key_here

# List resources
polaris resources list

# Create instance
polaris instances create my-instance --resource-id comp_001 --template-id pytorch-training

✨ Features

• 🔐 Token-based Authentication - Secure API key management with multi-profile support
• 🖥️ Smart Resource Discovery - Find and filter GPU/CPU resources by provider, specs, and availability
• 📋 Rich Template System - Pre-configured environments for ML, development, and production
• ⚡ Instance Management - Complete lifecycle management with resource validation
• 🎨 Beautiful Interface - Rich terminal UI with animations, loading spinners, and formatted tables
• 🔍 Advanced Filtering - Search resources by type, memory, region, and availability
• 📊 Requirement Validation - Smart template matching with resource compatibility checks

📦 Installation

Quick Install from PyPI (Recommended)

Install Polaris CLI directly from PyPI:

pip install polaris-cli

Verify installation:

polaris --help

You should see the Polaris CLI help screen with all available commands. That's it! The polaris command is now available globally.

Development Installation (For Contributors)

If you want to contribute or modify the CLI:

1. Clone the repository:

   git clone https://github.com/bigideaafrica/polariscloud-cli
   cd polaris-cli
   

2. Create virtual environment:

   python -m venv polaris-env
   
   # Windows
   .\polaris-env\Scripts\activate
   
   # Linux/macOS
   source polaris-env/bin/activate
   

3. Install in development mode:

   pip install -e .
   

🚀 Quick Start

After installing with pip install polaris-cli:

# 1. Verify installation
polaris --help

# 2. Login with your API token
polaris auth login --api-key pk_admin_your_api_key_here

# 3. Browse available resources
polaris resources list

# 4. Check available templates  
polaris templates list

# 5. Create instance with resource ID and template
polaris instances create my-training \
  --resource-id comp_001 \
  --template-id pytorch-training

# 6. Check instance status
polaris instances get inst_my_training

🔐 Authentication

Polaris CLI uses API tokens for secure authentication:

# Login with API key
polaris auth login --api-key pk_prod_your_sample_token_here

# Check authentication status  
polaris auth status

# Logout when done
polaris auth logout

🗂️ Command Structure

polaris [command] [subcommand] [options]

Available Commands:

• auth - Authentication and session management
• resources - Resource discovery and filtering
• instances - Instance lifecycle management
• templates - Template browsing and management
• ssh - SSH key management and connections
• status - System status and monitoring
• billing - Usage and billing information
• config - Configuration management

Use polaris [command] --help for detailed usage information.

⚙️ Configuration

Configuration is stored in ~/.polaris/config.json with secure token management:

# View current configuration
polaris config show

# Set configuration values
polaris config set default_region us-west-1
polaris config set output_format table

# Reset configuration
polaris config reset

📚 Examples

Resource Discovery

# List all available resources
polaris resources list

# Filter GPU resources by provider  
polaris resources gpu-list --provider nvidia

# Filter by memory requirements
polaris resources gpu-list --memory 24gb+

# Search with natural language
polaris resources search "nvidia gpu 24gb singapore"

# Show only available resources
polaris resources list --available-only

Template Management

# Browse all templates
polaris templates list

# Filter templates by category
polaris templates list --category "Machine Learning"

# Search for specific templates
polaris templates list --search pytorch

# Get detailed template information
polaris templates get pytorch-training

Instance Creation (Step-by-Step)

# 1. Find an available resource
polaris resources list --available-only

# 2. Choose a template
polaris templates list

# 3. Create instance with both resource ID and template ID
polaris instances create my-training \
  --resource-id comp_001 \
  --template-id pytorch-training \
  --disk-size 100

# 4. Check instance details
polaris instances get inst_my_training

# 5. Connect to instance
polaris ssh connect inst_my_training

Advanced Usage

# Get help for creating instances
polaris instances create-help

# List running instances
polaris instances list --status running

# Monitor system status
polaris status overview

# View billing information
polaris billing overview

📋 Available Templates

Our CLI includes pre-configured templates for various use cases:

Template ID	Category	Description	Requirements
pytorch-training	Machine Learning	PyTorch with CUDA support	GPU: 8GB, RAM: 8GB
tensorflow-jupyter	Machine Learning	TensorFlow + Jupyter Lab	CPU+GPU, RAM: 4GB
stable-diffusion	AI Art	Automatic1111 WebUI	GPU Required, RAM: 16GB
fastapi-serve	Deployment	FastAPI inference server	CPU Only, RAM: 2GB
vscode-remote	Development	VS Code remote environment	CPU Only, RAM: 2GB
ubuntu-desktop	OS	Full Ubuntu desktop via VNC	CPU+GPU, RAM: 4GB
jupyter-datascience	Data Science	Complete data science stack	CPU+GPU, RAM: 4GB

🛠️ Features Highlights

Smart Resource Filtering

• GPU Provider Filtering: --provider nvidia or --provider amd
• Memory Requirements: --memory 24gb+ or --memory 8gb-32gb
• Availability Status: --available-only shows only free resources
• Resource IDs: Clear identifiers like comp_001, comp_002

Rich Terminal UI

• Loading Spinners: Beautiful animations during API calls
• Formatted Tables: Clean, readable resource and template listings
• Error Handling: Clear error messages with helpful suggestions
• Authentication Required: Secure API access with token validation

Template System

• Requirement Validation: Automatic compatibility checking
• Resource Requirements: Clear RAM, storage, and GPU requirements
• Clickable Docker Links: Direct access to Docker Hub repositories
• Category Organization: OS, Development, Machine Learning, etc.

🚨 Troubleshooting

Common Issues

Authentication Error:

❌ Authentication required!
Please login first: polaris auth login

Solution: Run polaris auth login --api-key YOUR_TOKEN

Resource Not Found:

❌ Resource 'comp_999' not found!
💡 List available resources: polaris resources list

Solution: Use polaris resources list to find valid resource IDs

Resource In Use:

❌ Resource 'comp_001' is currently in use!
💡 Find available resources: polaris resources list --available-only

Solution: Choose a different resource or wait for it to become available

Template Not Found:

❌ Template 'invalid-template' not found!
💡 List available templates: polaris templates list  

Solution: Use polaris templates list to find valid template IDs

Getting Help

# General help
polaris --help

# Command-specific help
polaris instances --help
polaris instances create --help

# Step-by-step instance creation guide
polaris instances create-help

Dependencies

• typer: CLI framework
• rich: Beautiful terminal output
• httpx: HTTP client for API calls
• keyring: Secure token storage
• pydantic: Data validation

📄 License

MIT License - see LICENSE file for details.