alphai 0.1.2

A CLI tool and Python package for the runalph.ai platform

alphai

A beautiful and powerful CLI tool and Python package for the runalph.ai platform, built with Click and Rich.

Depends on the alph-sdk Python SDK for seamless API integration.

Installation

The CLI is automatically installed when you install the Python package:

pip install alphai

Quick Start

1. Authenticate with your runalph.ai account:

   alphai login
   

2. View your status:

   alphai status
   

3. List organizations:

   alphai orgs list
   

4. List projects:

   alphai projects list
   

5. Run a Docker container:

   alphai run --image quay.io/jupyter/base-notebook:latest
   

Commands

Authentication

alphai login

Authenticate with the runalph.ai API using browser-based authentication or a bearer token.

Smart authentication checking: The login command automatically checks if you're already authenticated and validates your existing credentials. If you're already logged in with a valid token, it will skip the login process.

# Interactive login (browser-based, recommended)
alphai login

# Browser-based login (explicit)
alphai login --browser

# Login with token directly
alphai login --token YOUR_BEARER_TOKEN

# Force re-authentication even if already logged in
alphai login --force

# Login with custom API URL
alphai login --api-url https://runalph.ai/api --token YOUR_TOKEN

# Force browser login even if already authenticated
alphai login --browser --force

Authentication methods:

1. Browser login (recommended): Opens your browser for secure OAuth authentication
2. Token login: Manually enter a bearer token from https://runalph.ai/account/tokens

Options:

• --token: Provide a bearer token directly (bypasses authentication check)
• --browser: Use browser-based authentication explicitly
• --force: Force re-authentication even if already logged in
• --api-url: Set a custom API base URL

You can also set the ALPHAI_BEARER_TOKEN environment variable to authenticate automatically.

alphai logout

Log out and clear authentication credentials.

alphai logout

alphai status

Show current configuration and authentication status.

alphai status

Organizations

alphai orgs list

List all organizations you have access to.

alphai orgs list

alphai orgs create

Create a new organization.

# Create with name only
alphai orgs create --name "My Organization"

# Create with name and description
alphai orgs create --name "My Org" --description "A sample organization"

alphai orgs select

Select an organization as your current context.

alphai orgs select ORG_ID

Projects

alphai projects list

List all projects, optionally filtered by organization.

# List all projects
alphai projects list

# List projects in a specific organization
alphai projects list --org ORG_ID

# List projects in current organization context
alphai orgs select ORG_ID
alphai projects list

alphai projects select

Select a project as your current context.

alphai projects select PROJECT_ID

Docker Container Management

alphai run

Launch and manage local Docker containers with beautiful progress indicators.

# Basic usage - run Jupyter notebook
alphai run --image quay.io/jupyter/base-notebook:latest

# Custom ports
alphai run --image quay.io/jupyter/base-notebook:latest --app-port 3000 --jupyter-port 9999

# Run in background (detached)
alphai run --image quay.io/jupyter/base-notebook:latest --detach

# With custom name
alphai run --image python:3.11 --name my-python-env

# With environment variables
alphai run --image python:3.11 --env "DEBUG=true" --env "API_KEY=secret"

# With volume mounts
alphai run --image python:3.11 --volume "/host/path:/container/path" --volume "/data:/app/data"

# Complex example
alphai run \
  --image quay.io/jupyter/base-notebook:latest \
  --name jupyter-dev \
  --app-port 5000 \
  --jupyter-port 8888 \
  --env "JUPYTER_ENABLE_LAB=yes" \
  --volume "$(pwd):/home/jovyan/work" \
  --detach

Supported options:

• --image: Docker image to run (required)
• --app-port: Application port (default: 5000)
• --jupyter-port: Jupyter port (default: 8888)
• --name: Container name (auto-generated if not specified)
• --env: Environment variables (format: KEY=VALUE, can be used multiple times)
• --volume: Volume mounts (format: HOST_PATH:CONTAINER_PATH, can be used multiple times)
• --detach, -d: Run container in background

Configuration Management

alphai config show

Show current configuration.

alphai config show

alphai config set

Set configuration values.

# Set API URL
alphai config set api_url https://runalph.ai/api

# Enable debug mode
alphai config set debug true

# Set current organization
alphai config set current_org ORG_ID

# Set current project
alphai config set current_project PROJECT_ID

alphai config reset

Reset configuration to defaults.

alphai config reset

Global Options

• --debug: Enable debug mode for the current command
• --version: Show version information

# Enable debug mode
alphai --debug orgs list

# Show version
alphai --version

Environment Variables

• ALPHAI_BEARER_TOKEN: Bearer token for authentication
• ALPHAI_API_URL: Custom API base URL
• ALPHAI_DEBUG: Enable debug mode (set to true, 1, yes, or on)

Configuration

Configuration is stored in ~/.alphai/config.json. Bearer tokens are securely stored in your system's keyring.

Example configuration:

{
  "api_url": "https://runalph.ai/api",
  "current_org": "org_123",
  "current_project": "proj_456",
  "debug": false
}

Features

Beautiful CLI Interface

• 🎨 Rich terminal UI with colors and formatting
• 📊 Beautiful tables for data display
• ⏳ Progress indicators for long-running operations
• 🔐 Secure credential storage with keyring

Docker Integration

• 🐳 Seamless Docker container management
• 📦 Automatic image pulling with progress
• 🔧 Support for custom ports, environment variables, and volumes
• 🚀 Background and interactive modes

Smart Configuration

• 💾 Persistent configuration with secure token storage
• 🏢 Organization and project context management
• 🔧 Environment variable support
• 🔄 Easy configuration reset

Error Handling

• 🛡️ Comprehensive error handling and user feedback
• 🔍 Debug mode for troubleshooting
• ⚡ Connection testing and validation

Development

To set up for development:

# Clone the repository
git clone https://github.com/americandatascience/alphai.git
cd alphai

# Install in development mode
pip install -e ".[dev]"

# Run tests
pytest

# Run linting
ruff check src/
black src/

# Type checking
mypy src/

API Integration

This CLI uses the alph-sdk to interact with the runalph.ai API. All API operations are wrapped with beautiful progress indicators and error handling.

The CLI automatically:

• Validates bearer tokens before making API calls
• Provides helpful error messages for common issues
• Handles connection timeouts and network errors gracefully
• Uses secure credential storage

Examples

Complete Workflow

# 1. Login
alphai login

# 2. List organizations and select one
alphai orgs list
alphai orgs select org_abc123

# 3. List projects in the organization
alphai projects list

# 4. Run a development environment
alphai run \
  --image quay.io/jupyter/datascience-notebook:latest \
  --name datascience-env \
  --volume "$(pwd):/home/jovyan/work" \
  --env "JUPYTER_ENABLE_LAB=yes" \
  --detach

# 5. Check status
alphai status

Multiple Containers

# Start a web application
alphai run --image nginx:latest --app-port 80 --name web-server --detach

# Start a database
alphai run --image postgres:13 --app-port 5432 --name database \
  --env "POSTGRES_PASSWORD=secret" --detach

# Start a development environment
alphai run --image python:3.11 --name dev-env \
  --volume "$(pwd):/app" --env "PYTHONPATH=/app"

Support

• Documentation: https://docs.runalph.ai
• Issues: https://github.com/americandatascience/alphai/issues
• Website: https://runalph.ai