​
Overview

The xpander.ai CLI is your command-line interface for building and managing AI agents. It handles three core functions:
  1. 🎛️ Control Plane - Create, edit, delete agents in xpander.ai’s cloud platform
  2. 🏗️ Local Development - Download framework templates and run agents locally
  3. ☁️ Cloud Deployment - Deploy Docker containers, stream logs, manage containers

​
Installation

Requirements: Node.js 20+, Python 3.12+ 
npm install -g xpander-cli
xpander login

​
Command Structure

All commands support shortcuts for faster usage: 
# Full commands
xpander agent new
xpander agent deploy my-agent

# Shortcuts  
x a n                       # xpander agent new
x a d my-agent              # xpander agent deploy

​
Authentication & Profiles

xpander login                         # Authenticate with xpander.ai (opens browser)
xpander configure                     # Set up API credentials manually
xpander profile --list                # List all profiles
xpander profile --switch <name>       # Switch between organizations
Purpose: Manage authentication and switch between different xpander.ai organizations or environments (production, staging, etc.).

​
🎛️ Control Plane - Agent Management

These commands manage agents in Xpander’s cloud platform: 
xpander agent new                     # Create new agent in xpander.ai cloud
xpander agent new --name "bot" --folder "." --framework "agno"  # Non-interactive
xpander agent list                    # List all your agents (newest first)
xpander agent edit [agent]            # Edit agent configuration in browser
xpander agent delete [agent]          # Permanently delete agent from cloud
xpander agent invoke [agent] "message" # Test agent with a message via webhook
Purpose: Create, configure, and manage your AI agents in xpander.ai’s control plane. These operations affect the agent definitions stored in xpander.ai’s cloud. Key Features:
  • Agent lists are sorted by creation date (newest first)
  • Optional [agent] parameters show selection list if omitted
  • edit opens the agent configuration in your browser
  • delete requires confirmation to prevent accidental deletion
  • invoke tests deployed agents via webhook with real-time responses

​
🏗️ Local Development - Framework Templates

These commands work with agent code on your local machine: 
xpander agent init [agent]            # Download agent files to current folder
xpander agent dev [agent]             # Run agent locally for testing
Purpose: Download pre-built framework templates (agno, agno-team, base) to your local development environment and test agents locally before deployment. What happens:
  • init downloads the agent’s framework files (Dockerfile, requirements.txt, xpander_handler.py, .env)
  • dev runs the agent locally using your local Python environment

​
☁️ Cloud Deployment - Container Management

These commands manage deployed agent containers in Xpander’s cloud: 
xpander agent deploy [agent]          # Build & deploy agent as Docker container
xpander agent logs [agent]            # Stream real-time logs from cloud
xpander agent restart [agent]         # Restart deployed container
xpander agent stop [agent]            # Stop running container
xpander secrets-sync                  # Upload .env variables to deployed agents
Purpose: Deploy your local agent code as Docker containers to xpander.ai’s cloud infrastructure and manage running containers. Deployment Process:
  1. Uploads your local agent code
  2. Builds a new Docker image
  3. Deploys and runs the container instantly
  4. Each deploy creates a NEW version
Required files for deployment:
  • Dockerfile - Container definition
  • requirements.txt - Python dependencies
  • xpander_handler.py - Your agent logic
  • .env - Environment variables

​
🧪 Agent Testing - Invoke Command

Test your deployed agents directly via webhook with real-time responses: 
xpander agent invoke                  # Interactive agent selection + message prompt
xpander agent invoke "Hello world"   # Interactive agent selection with message
xpander agent invoke my-agent "Hi"   # Test specific agent by name
xpander agent invoke --agent-name my-agent "Hi"    # Old syntax (backward compatible)
xpander agent invoke --agent-id <id> "Hi"          # Test specific agent by ID
Purpose: Test deployed agents instantly without building chat UIs or API clients. Perfect for development, debugging, and validation. Key Features:
  • Real-time responses - Get immediate webhook responses with timing
  • Smart agent resolution - Resolves agent names to IDs automatically
  • Agent caching - Caches agent list for 24 hours for faster performance
  • Interactive selection - Shows agent list if no agent specified
  • Multiple input methods - Support for agent names, IDs, and interactive selection
  • Clean output format - Formatted responses with response time tracking
Examples: 
# Quick testing workflow
x a invoke "test my new feature"      # Pick agent, test quickly
x a invoke notebook-agent "analyze data.csv"  # Direct agent testing
x a invoke --agent-id abc123 "status check"   # Test by exact ID

# Development workflow
x a d my-agent                        # Deploy updated code
x a invoke my-agent "test changes"    # Immediately test changes

​
Command Shortcuts Reference

# Authentication
x l                         # xpander login
x c                         # xpander configure

# Control Plane (Agent Management)
x a n                       # xpander agent new
x a e [agent]               # xpander agent edit (shows list if no agent)
x a del [agent]             # xpander agent delete (shows list if no agent)
x a invoke [agent] "msg"    # xpander agent invoke (shows list if no agent)

# Local Development
x a i [agent]               # xpander agent init (shows list if no agent)

# Cloud Deployment
x a d [agent]               # xpander agent deploy (shows list if no agent)
x a l [agent]               # xpander agent logs (shows list if no agent)

​
Advanced Workflows

​
CI/CD Pipeline

name: Deploy with Xpander
on:
  push:
    branches: [ main ]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v4
    - uses: actions/setup-node@v4
      with:
        node-version: '20'
    - uses: actions/setup-python@v4
      with:
        python-version: '3.12'
    - run: npm install -g xpander-cli
    - run: |
        xpander deploy --agent-id "${{ secrets.XPANDER_AGENT_ID }}" --api-key "${{ secrets.XPANDER_API_KEY }}" --confirm

​
Multi-Organization Setup

# Login to different profiles/orgs
xpander login --profile production
xpander login --profile staging

# Use specific organization
xpander agent list --profile staging
xpander deploy --profile production

​
Non-Interactive Mode

# Skip all prompts
xpander agent new --name "bot" --framework "agno" --folder "."
xpander init abc123 --framework "agno" --folder "."
Auth Priority: --api-key > XPANDER_API_KEY > ~/.xpander/credentials

​
Available Frameworks

agno - Basic agent framework with core functionality agno-team - Multi-agent team framework for collaborative agents
base - Minimal framework for custom implementations

​
Need Help?