# 🚀 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.
[](https://badge.fury.io/py/polaris-cli)
[](https://www.python.org/downloads/)
**🎉 Now available on PyPI! Install with:** `pip install polaris-cli`
## 🏃♀️ Get Started in 30 seconds
```bash
# 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:
```bash
pip install polaris-cli
```
**Verify installation:**
```bash
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:**
```bash
git clone https://github.com/bigideaafrica/polariscloud-cli
cd polaris-cli
```
2. **Create virtual environment:**
```bash
python -m venv polaris-env
# Windows
.\polaris-env\Scripts\activate
# Linux/macOS
source polaris-env/bin/activate
```
3. **Install in development mode:**
```bash
pip install -e .
```
## 🚀 Quick Start
After installing with `pip install polaris-cli`:
```bash
# 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:
```bash
# 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:
```bash
# 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
```bash
# 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
```bash
# 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)
```bash
# 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
```bash
# 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:**
```bash
❌ Authentication required!
Please login first: polaris auth login
```
Solution: Run `polaris auth login --api-key YOUR_TOKEN`
**Resource Not Found:**
```bash
❌ Resource 'comp_999' not found!
💡 List available resources: polaris resources list
```
Solution: Use `polaris resources list` to find valid resource IDs
**Resource In Use:**
```bash
❌ 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:**
```bash
❌ Template 'invalid-template' not found!
💡 List available templates: polaris templates list
```
Solution: Use `polaris templates list` to find valid template IDs
### Getting Help
```bash
# 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.
Raw data
{
"_id": null,
"home_page": null,
"name": "polaris-cli",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "cloud, cli, infrastructure, polaris, resource-management",
"author": null,
"author_email": "Polaris Team <team@polaris.dev>",
"download_url": "https://files.pythonhosted.org/packages/42/3c/abd7837e9e9855f909ebfa41dc9b30ca35de9a77c85e57e510493d39fef8/polaris_cli-1.0.1.tar.gz",
"platform": null,
"description": "# \ud83d\ude80 Polaris CLI\r\n\r\nA beautiful and powerful command-line interface for cloud resource management with a stunning terminal UI, smart resource discovery, and streamlined instance deployment.\r\n\r\n[](https://badge.fury.io/py/polaris-cli)\r\n[](https://www.python.org/downloads/)\r\n\r\n**\ud83c\udf89 Now available on PyPI! Install with:** `pip install polaris-cli`\r\n\r\n## \ud83c\udfc3\u200d\u2640\ufe0f Get Started in 30 seconds\r\n\r\n```bash\r\n# Install\r\npip install polaris-cli\r\n\r\n# Verify installation\r\npolaris --help\r\n\r\n# Login \r\npolaris auth login --api-key pk_admin_your_key_here\r\n\r\n# List resources\r\npolaris resources list\r\n\r\n# Create instance\r\npolaris instances create my-instance --resource-id comp_001 --template-id pytorch-training\r\n```\r\n\r\n## \u2728 Features\r\n\r\n- **\ud83d\udd10 Token-based Authentication** - Secure API key management with multi-profile support\r\n- **\ud83d\udda5\ufe0f Smart Resource Discovery** - Find and filter GPU/CPU resources by provider, specs, and availability \r\n- **\ud83d\udccb Rich Template System** - Pre-configured environments for ML, development, and production\r\n- **\u26a1 Instance Management** - Complete lifecycle management with resource validation\r\n- **\ud83c\udfa8 Beautiful Interface** - Rich terminal UI with animations, loading spinners, and formatted tables\r\n- **\ud83d\udd0d Advanced Filtering** - Search resources by type, memory, region, and availability\r\n- **\ud83d\udcca Requirement Validation** - Smart template matching with resource compatibility checks\r\n\r\n## \ud83d\udce6 Installation\r\n\r\n### Quick Install from PyPI (Recommended)\r\n\r\nInstall Polaris CLI directly from PyPI:\r\n\r\n```bash\r\npip install polaris-cli\r\n```\r\n\r\n**Verify installation:**\r\n\r\n```bash\r\npolaris --help\r\n```\r\n\r\nYou should see the Polaris CLI help screen with all available commands. That's it! The `polaris` command is now available globally.\r\n\r\n### Development Installation (For Contributors)\r\n\r\nIf you want to contribute or modify the CLI:\r\n\r\n1. **Clone the repository:**\r\n ```bash\r\n git clone https://github.com/bigideaafrica/polariscloud-cli\r\n cd polaris-cli\r\n ```\r\n\r\n2. **Create virtual environment:**\r\n ```bash\r\n python -m venv polaris-env\r\n \r\n # Windows\r\n .\\polaris-env\\Scripts\\activate\r\n \r\n # Linux/macOS\r\n source polaris-env/bin/activate\r\n ```\r\n\r\n3. **Install in development mode:**\r\n ```bash\r\n pip install -e .\r\n ```\r\n\r\n## \ud83d\ude80 Quick Start\r\n\r\nAfter installing with `pip install polaris-cli`:\r\n\r\n```bash\r\n# 1. Verify installation\r\npolaris --help\r\n\r\n# 2. Login with your API token\r\npolaris auth login --api-key pk_admin_your_api_key_here\r\n\r\n# 3. Browse available resources\r\npolaris resources list\r\n\r\n# 4. Check available templates \r\npolaris templates list\r\n\r\n# 5. Create instance with resource ID and template\r\npolaris instances create my-training \\\r\n --resource-id comp_001 \\\r\n --template-id pytorch-training\r\n\r\n# 6. Check instance status\r\npolaris instances get inst_my_training\r\n```\r\n\r\n## \ud83d\udd10 Authentication\r\n\r\nPolaris CLI uses API tokens for secure authentication:\r\n\r\n```bash\r\n# Login with API key\r\npolaris auth login --api-key pk_prod_your_sample_token_here\r\n\r\n# Check authentication status \r\npolaris auth status\r\n\r\n# Logout when done\r\npolaris auth logout\r\n```\r\n\r\n## \ud83d\uddc2\ufe0f Command Structure\r\n\r\n```\r\npolaris [command] [subcommand] [options]\r\n```\r\n\r\n**Available Commands:**\r\n- `auth` - Authentication and session management\r\n- `resources` - Resource discovery and filtering\r\n- `instances` - Instance lifecycle management \r\n- `templates` - Template browsing and management\r\n- `ssh` - SSH key management and connections\r\n- `status` - System status and monitoring\r\n- `billing` - Usage and billing information\r\n- `config` - Configuration management\r\n\r\nUse `polaris [command] --help` for detailed usage information.\r\n\r\n## \u2699\ufe0f Configuration\r\n\r\nConfiguration is stored in `~/.polaris/config.json` with secure token management:\r\n\r\n```bash\r\n# View current configuration\r\npolaris config show\r\n\r\n# Set configuration values\r\npolaris config set default_region us-west-1\r\npolaris config set output_format table\r\n\r\n# Reset configuration\r\npolaris config reset\r\n```\r\n\r\n## \ud83d\udcda Examples\r\n\r\n### Resource Discovery\r\n```bash\r\n# List all available resources\r\npolaris resources list\r\n\r\n# Filter GPU resources by provider \r\npolaris resources gpu-list --provider nvidia\r\n\r\n# Filter by memory requirements\r\npolaris resources gpu-list --memory 24gb+\r\n\r\n# Search with natural language\r\npolaris resources search \"nvidia gpu 24gb singapore\"\r\n\r\n# Show only available resources\r\npolaris resources list --available-only\r\n```\r\n\r\n### Template Management\r\n```bash\r\n# Browse all templates\r\npolaris templates list\r\n\r\n# Filter templates by category\r\npolaris templates list --category \"Machine Learning\"\r\n\r\n# Search for specific templates\r\npolaris templates list --search pytorch\r\n\r\n# Get detailed template information\r\npolaris templates get pytorch-training\r\n```\r\n\r\n### Instance Creation (Step-by-Step)\r\n```bash\r\n# 1. Find an available resource\r\npolaris resources list --available-only\r\n\r\n# 2. Choose a template\r\npolaris templates list\r\n\r\n# 3. Create instance with both resource ID and template ID\r\npolaris instances create my-training \\\r\n --resource-id comp_001 \\\r\n --template-id pytorch-training \\\r\n --disk-size 100\r\n\r\n# 4. Check instance details\r\npolaris instances get inst_my_training\r\n\r\n# 5. Connect to instance\r\npolaris ssh connect inst_my_training\r\n```\r\n\r\n### Advanced Usage\r\n```bash\r\n# Get help for creating instances\r\npolaris instances create-help\r\n\r\n# List running instances\r\npolaris instances list --status running\r\n\r\n# Monitor system status\r\npolaris status overview\r\n\r\n# View billing information\r\npolaris billing overview\r\n```\r\n\r\n## \ud83d\udccb Available Templates\r\n\r\nOur CLI includes pre-configured templates for various use cases:\r\n\r\n| Template ID | Category | Description | Requirements |\r\n|-------------|----------|-------------|--------------|\r\n| `pytorch-training` | Machine Learning | PyTorch with CUDA support | GPU: 8GB, RAM: 8GB |\r\n| `tensorflow-jupyter` | Machine Learning | TensorFlow + Jupyter Lab | CPU+GPU, RAM: 4GB |\r\n| `stable-diffusion` | AI Art | Automatic1111 WebUI | GPU Required, RAM: 16GB |\r\n| `fastapi-serve` | Deployment | FastAPI inference server | CPU Only, RAM: 2GB |\r\n| `vscode-remote` | Development | VS Code remote environment | CPU Only, RAM: 2GB |\r\n| `ubuntu-desktop` | OS | Full Ubuntu desktop via VNC | CPU+GPU, RAM: 4GB |\r\n| `jupyter-datascience` | Data Science | Complete data science stack | CPU+GPU, RAM: 4GB |\r\n\r\n## \ud83d\udee0\ufe0f Features Highlights\r\n\r\n### Smart Resource Filtering\r\n- **GPU Provider Filtering**: `--provider nvidia` or `--provider amd`\r\n- **Memory Requirements**: `--memory 24gb+` or `--memory 8gb-32gb` \r\n- **Availability Status**: `--available-only` shows only free resources\r\n- **Resource IDs**: Clear identifiers like `comp_001`, `comp_002`\r\n\r\n### Rich Terminal UI\r\n- **Loading Spinners**: Beautiful animations during API calls\r\n- **Formatted Tables**: Clean, readable resource and template listings\r\n- **Error Handling**: Clear error messages with helpful suggestions\r\n- **Authentication Required**: Secure API access with token validation\r\n\r\n### Template System\r\n- **Requirement Validation**: Automatic compatibility checking\r\n- **Resource Requirements**: Clear RAM, storage, and GPU requirements\r\n- **Clickable Docker Links**: Direct access to Docker Hub repositories\r\n- **Category Organization**: OS, Development, Machine Learning, etc.\r\n\r\n## \ud83d\udea8 Troubleshooting\r\n\r\n### Common Issues\r\n\r\n**Authentication Error:**\r\n```bash\r\n\u274c Authentication required!\r\nPlease login first: polaris auth login\r\n```\r\nSolution: Run `polaris auth login --api-key YOUR_TOKEN`\r\n\r\n**Resource Not Found:**\r\n```bash\r\n\u274c Resource 'comp_999' not found!\r\n\ud83d\udca1 List available resources: polaris resources list\r\n```\r\nSolution: Use `polaris resources list` to find valid resource IDs\r\n\r\n**Resource In Use:**\r\n```bash\r\n\u274c Resource 'comp_001' is currently in use!\r\n\ud83d\udca1 Find available resources: polaris resources list --available-only\r\n```\r\nSolution: Choose a different resource or wait for it to become available\r\n\r\n**Template Not Found:**\r\n```bash\r\n\u274c Template 'invalid-template' not found!\r\n\ud83d\udca1 List available templates: polaris templates list \r\n```\r\nSolution: Use `polaris templates list` to find valid template IDs\r\n\r\n### Getting Help\r\n```bash\r\n# General help\r\npolaris --help\r\n\r\n# Command-specific help\r\npolaris instances --help\r\npolaris instances create --help\r\n\r\n# Step-by-step instance creation guide\r\npolaris instances create-help\r\n```\r\n\r\n### Dependencies\r\n- **typer**: CLI framework\r\n- **rich**: Beautiful terminal output\r\n- **httpx**: HTTP client for API calls\r\n- **keyring**: Secure token storage\r\n- **pydantic**: Data validation\r\n\r\n## \ud83d\udcc4 License\r\n\r\nMIT License - see LICENSE file for details.\r\n",
"bugtrack_url": null,
"license": null,
"summary": "A beautiful and powerful cloud resource management CLI for Polaris Cloud",
"version": "1.0.1",
"project_urls": {
"Bug Reports": "https://github.com/polaris-cloud/polaris-cli/issues",
"Documentation": "https://docs.polaris.cloud/cli",
"Homepage": "https://github.com/polaris-cloud/polaris-cli",
"Source": "https://github.com/polaris-cloud/polaris-cli"
},
"split_keywords": [
"cloud",
" cli",
" infrastructure",
" polaris",
" resource-management"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "d67aecab62841b72febcdcabc92c28b379a333ca0b1d9dc2c2dd5fece960f842",
"md5": "154df6a373d792b7e095a878e8baaae7",
"sha256": "d087619b8985ce527b98b9fe9ae0083f8eb363688322f62279dcc28fde138b1c"
},
"downloads": -1,
"filename": "polaris_cli-1.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "154df6a373d792b7e095a878e8baaae7",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 55116,
"upload_time": "2025-08-23T03:36:02",
"upload_time_iso_8601": "2025-08-23T03:36:02.714065Z",
"url": "https://files.pythonhosted.org/packages/d6/7a/ecab62841b72febcdcabc92c28b379a333ca0b1d9dc2c2dd5fece960f842/polaris_cli-1.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "423cabd7837e9e9855f909ebfa41dc9b30ca35de9a77c85e57e510493d39fef8",
"md5": "6e021c74e66fdba3b877fb0a7c8f1f6b",
"sha256": "c976effb37fc1deec1fb113e5596389cc8cbac7576e73239297318dec0c73e9e"
},
"downloads": -1,
"filename": "polaris_cli-1.0.1.tar.gz",
"has_sig": false,
"md5_digest": "6e021c74e66fdba3b877fb0a7c8f1f6b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 50914,
"upload_time": "2025-08-23T03:36:04",
"upload_time_iso_8601": "2025-08-23T03:36:04.673890Z",
"url": "https://files.pythonhosted.org/packages/42/3c/abd7837e9e9855f909ebfa41dc9b30ca35de9a77c85e57e510493d39fef8/polaris_cli-1.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-23 03:36:04",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "polaris-cloud",
"github_project": "polaris-cli",
"github_not_found": true,
"lcname": "polaris-cli"
}
JSON
