spx-cli 1.0.0

Spritz CLI (spx) - Deploy and manage AI agents

Spritz CLI (spx)

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

🚀 Installation

Install via pip:

pip install spritz-cli

📋 Quick Start

1. Configure Environment

# 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

# Login to dev
spx login --profile dev

# Login to prod
spx login --profile prod

3. Onboard Agents

# 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.

spx configure [--profile PROFILE]

Options:

• --profile - Profile name (default, dev, prod)

Example:

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.

spx login [--profile PROFILE]

Options:

• --profile - Profile to login (default: default)

Example:

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: [e-mail]

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.

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:

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.

spx whoami [--profile PROFILE]

Example:

spx whoami --profile prod

# Output:
# Profile: prod
# Spritz URL: https://spritz.activate.bar
# Email: [e-mail]
# Auth0 ID: email|64e8a0485efd44509ed20f06
# Organization ID: 64a54a30899afb66425722fc
# Last Login: 2025-10-13T09:20:00.988Z

---

spx list-profiles

List all configured profiles.

spx list-profiles

Example:

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.

spx validate [--profile PROFILE]

Example:

spx validate --profile prod

# Output:
# ✓ Profile 'prod' is valid
#   Spritz URL: https://spritz.activate.bar
#   Token: ****************************************...tQuDQ
#   User: [e-mail]
#   Organization: 64a54a30899afb66425722fc

🌐 Configuration URL Format

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

Single Agent

{
  "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

[
  {
    "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

[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

[default]
token = eyJhbGciOiJSUzI1NiIs...

[dev]
token = eyJhbGciOiJSUzI1NiIs...

[prod]
token = eyJhbGciOiJSUzI1NiIs...

🔄 Complete Workflow

Development Workflow

# 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

# 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:

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

# 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

# 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

#!/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:

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

🐛 Troubleshooting

"Profile not found"

# Configure the profile first
spx configure --profile prod

"Token expired"

# 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:

lsof -i :8765

Reset everything

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: /issues
• Email: [e-mail]

💻 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.

📄 License

MIT License - see LICENSE file for details