> ## Documentation Index > Fetch the complete documentation index at: https://docs.xpander.ai/llms.txt > Use this file to discover all available pages before exploring further. # CLI Reference > Complete reference for all Xpander CLI commands, options, and workflows ## 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+ ```bash theme={"dark"} npm install -g xpander-cli xpander login ``` ## Command Structure All commands support shortcuts for faster usage: ```bash theme={"dark"} # 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 ```bash theme={"dark"} xpander login # Authenticate with xpander.ai (opens browser) xpander configure # Set up API credentials manually xpander profile --list # List all profiles xpander profile --switch # 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: ```bash theme={"dark"} 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: ```bash theme={"dark"} 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: ```bash theme={"dark"} 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: ```bash theme={"dark"} 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 "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:** ```bash theme={"dark"} # 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 ```bash theme={"dark"} # 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 ```yaml theme={"dark"} 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 ```bash theme={"dark"} # 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 ```bash theme={"dark"} # 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? * **Join our Slack**: [https://join.slack.com/t/xpandercommunity/shared\_invite/zt-2mt2xkxkz-omM7f\~\_h2jcuzFudrYtZQQ](https://join.slack.com/t/xpandercommunity/shared_invite/zt-2mt2xkxkz-omM7f~_h2jcuzFudrYtZQQ) * **Schedule free AI agent consultation**: [https://e.xpander.ai/meetings/xpander/book-a-demo-website](https://e.xpander.ai/meetings/xpander/book-a-demo-website)