spx-cli 1.0.0
Spritz CLI (spx) - Deploy and manage AI agents
Requires Python: >=3.7
Keywords: cli agent deployment ai spritz management spx

# Spritz CLI (spx)

Command-line interface for deploying and managing Spritz AI agents across dev and production environments.

## 🚀 Installation

Install via pip:
```bash
pip install spritz-cli
```

## 📋 Quick Start

### 1. Configure Environment

```bash
# Configure dev environment
spx configure --profile dev
# Spritz URL: https://app.dev.spritz.activate.bar

# Configure prod environment
spx configure --profile prod
# Spritz URL: https://spritz.activate.bar
```

### 2. Login

```bash
# Login to dev
spx login --profile dev

# Login to prod
spx login --profile prod
```

### 3. Onboard Agents

```bash
# Onboard to dev
spx agent-onboarding --profile dev --url https://config.example.com/agents.json

# Onboard to prod
spx agent-onboarding --profile prod --url https://config.example.com/agents.json

# Preview without deploying (dry run)
spx agent-onboarding --profile dev --url https://config.example.com/agents.json --dry-run
```

## 📖 Commands

### `spx configure`

Configure Spritz URL for different environments.

```bash
spx configure [--profile PROFILE]
```

**Options:**
- `--profile` - Profile name (default, dev, prod)

**Example:**
```bash
spx configure --profile dev
# Spritz URL [https://app.dev.spritz.activate.bar]: 
# ✓ Profile 'dev' configured successfully
# Do you want to login now? [Y/n]: y
```

---

### `spx login`

Authenticate with Spritz via browser.

```bash
spx login [--profile PROFILE]
```

**Options:**
- `--profile` - Profile to login (default: default)

**Example:**
```bash
spx login --profile prod

# Output:
# → Opening browser for authentication...
#    Spritz URL: https://spritz.activate.bar
#    Waiting for authentication...
#    Please login in the browser window.
# 
# [Browser opens, user logs in, window closes]
# 
# → Verifying token...
# ✓ Authentication successful!
#    Logged in as: pradeep@incaendo.com
```

**How it works:**
1. Opens browser to Spritz dashboard
2. Extracts token from localStorage automatically
3. Verifies token with API
4. Saves token for future use
5. Browser window closes automatically

---

### `spx agent-onboarding`

Deploy agents from a configuration URL.

```bash
spx agent-onboarding --profile PROFILE --url URL [--dry-run]
```

**Options:**
- `--profile` - Environment profile (default, dev, prod)
- `--url` - URL that returns agent configuration JSON (required)
- `--dry-run` - Preview without deploying

**Example:**
```bash
spx agent-onboarding --profile prod --url https://config.example.com/agents.json

# Output:
# Using profile: prod
# Spritz URL: https://spritz.activate.bar
# API URL: https://api.spritz.activate.bar
# 
# → Loading agent configuration...
#    Fetching from: https://config.example.com/agents.json
# ✓ Found 3 agent(s) to onboard
# 
# → Agent configurations:
#   [1] Customer Support Agent (type: chat)
#   [2] Sales Assistant (type: voice)
#   [3] Analytics Bot (type: automation)
# 
# → Creating agents...
#   ✓ [1/3] Customer Support Agent onboarded successfully
#     Agent ID: agent_abc123
#   ✓ [2/3] Sales Assistant onboarded successfully
#     Agent ID: agent_def456
#   ✓ [3/3] Analytics Bot onboarded successfully
#     Agent ID: agent_ghi789
# 
# ==================================================
# Onboarding complete!
#   Success: 3/3
# 
# ✓ All agents onboarded successfully!
```

---

### `spx whoami`

Show current user information.

```bash
spx whoami [--profile PROFILE]
```

**Example:**
```bash
spx whoami --profile prod

# Output:
# Profile: prod
# Spritz URL: https://spritz.activate.bar
# Email: pradeep@incaendo.com
# Auth0 ID: email|64e8a0485efd44509ed20f06
# Organization ID: 64a54a30899afb66425722fc
# Last Login: 2025-10-13T09:20:00.988Z
```

---

### `spx list-profiles`

List all configured profiles.

```bash
spx list-profiles
```

**Example:**
```bash
spx list-profiles

# Output:
# Configured profiles:
#   - default (https://spritz.activate.bar) ✓ logged in
#   - dev (https://app.dev.spritz.activate.bar) ✓ logged in
#   - prod (https://spritz.activate.bar) ✗ not logged in
```

---

### `spx validate`

Validate profile configuration.

```bash
spx validate [--profile PROFILE]
```

**Example:**
```bash
spx validate --profile prod

# Output:
# ✓ Profile 'prod' is valid
#   Spritz URL: https://spritz.activate.bar
#   Token: ****************************************...tQuDQ
#   User: pradeep@incaendo.com
#   Organization: 64a54a30899afb66425722fc
```

## 🌐 Configuration URL Format

The `--url` parameter should point to a JSON endpoint that returns agent configuration(s).

### Single Agent
```json
{
  "name": "Customer Support Agent",
  "type": "chat",
  "agentType": "conversational",
  "description": "Handles customer inquiries",
  "config": {
    "model": "gpt-4",
    "temperature": 0.7
  },
  "prompts": {
    "system": "You are a helpful assistant."
  }
}
```

### Multiple Agents
```json
[
  {
    "name": "Support Agent",
    "type": "chat",
    "config": {...}
  },
  {
    "name": "Sales Agent",
    "type": "voice",
    "config": {...}
  }
]
```

## 📂 Configuration Storage

CLI stores configuration in `~/.spx/`:

```
~/.spx/
├── config          # Profile URLs
├── credentials     # Auth tokens (chmod 600)
└── user.json       # User data
```

### config
```ini
[profile default]
spritz_url = https://spritz.activate.bar

[profile dev]
spritz_url = https://app.dev.spritz.activate.bar

[profile prod]
spritz_url = https://spritz.activate.bar
```

### credentials
```ini
[default]
token = eyJhbGciOiJSUzI1NiIs...

[dev]
token = eyJhbGciOiJSUzI1NiIs...

[prod]
token = eyJhbGciOiJSUzI1NiIs...
```

## 🔄 Complete Workflow

### Development Workflow

```bash
# 1. Configure dev
spx configure --profile dev
# Spritz URL: https://app.dev.spritz.activate.bar
# Do you want to login now? [Y/n]: y
# ✓ Authentication successful!

# 2. Deploy to dev
spx agent-onboarding \
  --profile dev \
  --url https://config-dev.example.com/agents.json

# 3. Test agents in dev environment
# ... test your agents ...

# 4. Deploy to prod
spx agent-onboarding \
  --profile prod \
  --url https://config-prod.example.com/agents.json
```

### Multi-Environment Management

```bash
# Check all profiles
spx list-profiles

# Validate specific profile
spx validate --profile dev

# Check who's logged in
spx whoami --profile dev
spx whoami --profile prod

# Re-login if token expired
spx login --profile prod
```

## 🔐 Authentication Flow

1. **CLI opens browser** → `https://spritz.activate.bar/?cli_callback=http://localhost:8765/token`
2. **Spritz dashboard checks localStorage** → Extracts token from `persist:auth`
3. **Token sent to CLI** → POST to localhost:8765/token
4. **CLI verifies token** → Calls `/verifyToken` API
5. **Token saved** → Stored in `~/.spx/credentials`
6. **Browser closes** → Automatically after 2 seconds

**User sees:**
- ⏳ "Checking for authentication token..."
- ✓ "Authentication successful! You can close this window."
- [Window closes automatically]

## ⚡ Auto Re-authentication

CLI automatically handles expired tokens:

```bash
spx agent-onboarding --profile prod --url https://config.example.com/agents

# If token expired:
# ⚠ Token expired or invalid. Re-authenticating...
# → Opening browser for authentication...
# [Browser opens, authenticates, closes]
# → Verifying token...
# ✓ Authentication successful!
# → Creating agents...
```

## 🎯 Use Cases

### Deploy to Multiple Environments

```bash
# Deploy same config to dev and prod
for env in dev prod; do
  spx agent-onboarding \
    --profile $env \
    --url https://config.example.com/agents.json
done
```

### Preview Before Deploy

```bash
# Check what will be deployed
spx agent-onboarding \
  --profile prod \
  --url https://config.example.com/agents.json \
  --dry-run

# If looks good, deploy
spx agent-onboarding \
  --profile prod \
  --url https://config.example.com/agents.json
```

### CI/CD Integration

```bash
#!/bin/bash
# deploy.sh

PROFILE=$1
CONFIG_URL=$2

echo "Deploying to $PROFILE..."

# Validate profile
spx validate --profile $PROFILE || exit 1

# Deploy agents
spx agent-onboarding \
  --profile $PROFILE \
  --url $CONFIG_URL

echo "Deployment complete!"
```

Usage:
```bash
./deploy.sh dev https://config-dev.example.com/agents.json
./deploy.sh prod https://config-prod.example.com/agents.json
```

## 🐛 Troubleshooting

### "Profile not found"
```bash
# Configure the profile first
spx configure --profile prod
```

### "Token expired"
```bash
# Re-login
spx login --profile prod
```

### "Browser doesn't close automatically"
Close it manually after seeing success message.

### "Cannot connect to localhost:8765"
Check if port is available:
```bash
lsof -i :8765
```

### Reset everything
```bash
rm -rf ~/.spx
spx configure
```

## 📝 Requirements

- Python 3.7+
- Browser with localStorage support
- Internet connection
- Access to Spritz dashboard

## 🤝 Support

For issues and questions:
- GitHub Issues: <repo-url>/issues
- Email: support@incaendo.com

## 💻 Development

The codebase is organized into a modular structure for better maintainability.

- **Entry Point**: `spritz.py`
- **Package**: `src/`
  - **Commands**: `src/commands/`
  - **Core**: `config.py`, `auth.py`, `utils.py`

For detailed information about the code architecture, see [CODE_STRUCTURE.md](CODE_STRUCTURE.md).

## 📄 License

MIT License - see LICENSE file for details