spritz-cli 1.0.1

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

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

🔄 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

🔐 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

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

🐛 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

💻 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

Publishing to PyPI

Quick Publish

# Make script executable (first time only)
chmod +x publish.sh

# Publish to PyPI
./publish.sh

Manual Publishing

# Install build tools
pip install --upgrade pip build twine

# Clean and build
rm -rf dist/ build/ *.egg-info
python -m build

# Check package
twine check dist/*

# Upload to PyPI
twine upload dist/*

Troubleshooting

Package Name Already Taken

If the package name is already taken, rename it in setup.py:

setup(
    name='spritz-ai-cli',  # Or 'incaendo-spritz-cli'
    version='1.0.0',
    # ... rest of the configuration
)

Then rebuild and publish:

rm -rf dist/ build/ *.egg-info
python -m build
twine upload dist/*

Re-upload with Verbose Output

If upload fails, try with verbose logging:

rm -rf dist/ build/ *.egg-info
python -m build
twine upload dist/* --verbose

Clear pip Cache

If the package isn't found after publishing:

# Clear cache
pip cache purge

# Wait 1-2 minutes, then install
pip install spritz-cli --no-cache-dir

Verify Package

# Check if package exists on PyPI
curl -I https://pypi.org/project/spritz-cli/ | grep HTTP

# Visit package page
open https://pypi.org/project/spritz-cli/

PyPI Credentials

Create a PyPI API token at https://pypi.org/manage/account/token/ and save it:

cat > ~/.pypirc << 'EOF'
[pypi]
username = __token__
password = pypi-YOUR-TOKEN-HERE
EOF

chmod 600 ~/.pypirc

For detailed information about the code architecture, see CODE_STRUCTURE.md.

📄 License

MIT License - see LICENSE file for details