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.
The xpander agent namespace covers the full agent lifecycle plus graph editing, agentic-tool discovery, and NeMo model-config sync. Most lifecycle commands also exist as top-level shortcuts (xpander deploy ≡ xpander agent deploy).
xpander agent <command> [agent] [options]
[agent] is omitted, most commands show an interactive selection list of your agents. Use --no-interactive to fail instead of prompting.
Discovery
xpander agent list
List all agents in your organization, sorted by creation date (newest first).
xpander agent list
xpander agent list --all --full --json
| Flag | Description |
|---|
--json | Output JSON instead of a table. |
--all | Include inactive agents. |
--full | Show the full API response (every field). |
--profile <n> | Profile to use. |
xpander agent list-json
Same as agent list --json, kept as a separate command for backwards compatibility.
xpander agent list-json
xpander agent list-json --all
| Flag | Description |
|---|
--all | Include inactive agents. |
--profile <name> | Profile to use. |
xpander agent get <agent> (alias g)
Get details for a single agent.
xpander agent get my-agent
xpander agent g my-agent --json
xpander agent get --agent-id abc123
| Flag | Description |
|---|
--agent-id <id> | Look up by ID. |
--agent-name <name> | Look up by name. |
--json | Output JSON. |
--profile <name> | Profile to use. |
xpander agent interactive
Drop into the interactive agent management TUI: list, pick, edit, delete, invoke without typing every command.
xpander agent interactive
Control plane (CRUD)
xpander agent new (alias n)
Create a new agent in the xpander.ai cloud.
xpander agent new
xpander agent new --name "bot" --framework "agno" --folder "."
xpander agent n --name "bot" --model "gpt-4o" --deployment-type serverless --init --json
| Flag | Description |
|---|
--name <name> | Agent name. |
--model <model> | LLM model id. Defaults to gpt-4o. |
--deployment-type <type> | serverless or container. |
--framework <framework> | Template: agno, agno-team, or base. |
--folder <folder> | Local folder to scaffold into. Setting this enables non-interactive mode. |
--init | After creation, run the initialization wizard. |
--json | Output the result as JSON. |
--profile <name> | Profile to use. |
--name, --framework, and --folder together to run non-interactively in CI.
xpander agent update
Update an existing agent’s metadata.
xpander agent update --id abc123 \
--name "Bot v2" \
--role "Assistant" \
--goal "Answer questions about our product" \
--instructions "Be concise" \
--icon "🤖"
| Flag | Description |
|---|
--id <agent_id> | Agent to update. |
--name <name> | New name. |
--role <role> | New role. |
--goal <goal> | New goal. |
--instructions <text> | New instructions. |
--icon <icon> | New icon (emoji or URL). |
--profile <name> | Profile to use. |
--json | Output the result as JSON. |
xpander agent edit [agent] (alias o) / xpander agent open [agent]
Open the agent’s configuration page in your browser. edit and open are equivalent.
xpander agent edit my-agent
xpander agent o my-agent
xpander agent edit --agent-id abc123
| Flag | Description |
|---|
--agent-id <id> | Open by ID. |
--agent-name <name> | Open by name. |
--profile <name> | Profile to use. |
xpander agent delete [agent] (alias del)
Permanently delete an agent.
xpander agent delete my-agent
xpander agent del my-agent --confirm
| Flag | Description |
|---|
--agent-id <id> | Delete by ID. |
--agent-name <name> | Delete by name. |
--confirm | Skip the destructive-action confirmation prompt. |
--profile <name> | Profile to use. |
Local development
xpander agent init [agent-id] (alias i)
Download the agent’s framework files into the current directory.
xpander agent init my-agent
xpander agent i my-agent --framework "agno" --folder "."
xpander agent init my-agent --template
| Flag | Description |
|---|
--framework <framework> | Template to use: agno, agno-team, base. |
--folder <folder> | Target directory. Setting this enables non-interactive mode. |
--template | Show the template-selection picker before initializing. |
--profile <n> | Profile to use. |
Dockerfilerequirements.txtxpander_handler.py.env
Plus framework-specific config (xpander_config.json, agent_instructions.json, …).
The base templates can be inspected via xpander agent templates (below).
xpander agent templates
Manage and discover agent templates.
| Subcommand | Purpose |
|---|
xpander agent templates list | List all available templates. Pass --all to include hidden ones. |
xpander agent templates categories | List template categories. |
xpander agent dev [agent]
Run the agent locally for testing.
xpander agent dev my-agent
| Flag | Description |
|---|
--profile <n> | Profile to use. |
--path <path> | Path to the agent directory. Defaults to current directory. |
.env file in the working directory. Use this to iterate on xpander_handler.py without redeploying.
Cloud deployment
xpander agent deploy [agent] (alias d)
Build and deploy the agent’s Docker image to xpander.ai’s cloud.
xpander agent deploy my-agent
xpander agent d my-agent --confirm --skip-local-tests
xpander agent deploy my-agent --path ./apps/my-agent
| Flag | Description |
|---|
--profile <n> | Profile to use. |
--path <path> | Path to the agent directory. Defaults to current directory. |
--confirm | Skip confirmation prompts. |
--skip-local-tests | Skip local Docker container tests before pushing. |
- Uploads your local agent code.
- Builds a Docker image.
- Deploys and runs the container.
- Increments the agent’s deployed version.
Required files in the working directory:
Dockerfilerequirements.txtxpander_handler.py.env
xpander agent logs [agent] (alias l)
Stream real-time logs from a deployed container.
xpander agent logs my-agent
| Flag | Description |
|---|
--profile <n> | Profile to use. |
Ctrl+C to detach.
xpander agent restart [agent]
Restart the deployed container without rebuilding.
xpander agent restart my-agent
| Flag | Description |
|---|
--profile <n> | Profile to use. |
--path <path> | Path to the agent directory. |
xpander agent stop [agent]
Stop a running container.
xpander agent stop my-agent
| Flag | Description |
|---|
--profile <n> | Profile to use. |
--path <path> | Path to the agent directory. |
Invocation (testing)
xpander agent invoke [agent] [message...]
Test a deployed (or local) agent and print the response.
xpander agent invoke # interactive: pick agent, then enter message
xpander agent invoke my-agent # pick this agent, prompt for message
xpander agent invoke my-agent "Hello" # direct invocation (uses API by default)
xpander agent invoke --agent-id abc123 "status"
xpander agent invoke --json my-agent "summarize" # JSON response
xpander agent invoke --local my-agent "test" # use local xpander_handler.py
xpander agent invoke --webhook my-agent "ping" # use webhook invocation
| Flag | Description |
|---|
--agent <agent> | Agent name or ID. |
--agent-id <id> | Invoke by exact ID. |
--agent-name <name> | Invoke by name. |
--message <message> | Message to send (alternative to positional). |
--profile <name> | Profile to use. |
--json | Output raw JSON response. |
--local | Use the local xpander_handler.py. |
--api | Use API invocation. (Default.) |
--webhook | Use webhook invocation. |
.env file, xpander agent invoke "hi" infers the agent from .env and treats "hi" as the message.
The CLI caches the agent list for 24 hours, so name lookups stay fast across invocations.
Graph
An agent’s operation graph is the directed graph of connector operations the agent is allowed to call, along with the allowed transitions between them. The platform uses it both to constrain tool selection during a run and to render the visual workflow shown in the dashboard. Most users edit graphs through the dashboard; the CLI commands here are useful for scripting and CI.
xpander agent graph create
Create an operation graph for an agent.
xpander agent graph create -a abc123
| Flag | Description |
|---|
-a, --agent-id <id> | Agent to create the graph for. |
xpander agent graph View
View the graph structure of an agent.
xpander agent graph View -a abc123
| Flag | Description |
|---|
-a, --agent-id <id> | Agent whose graph to view. |
The View subcommand is capitalized in the CLI: type it exactly as xpander agent graph View.
slack.send_message, github.create_issue, and so on). Use these commands to discover interface IDs and the operations they offer when you’re building agent configs by hand or scripting against the API.
List available agentic interfaces (categories of connectors and tools your agents can use).
xpander agent tools interfaces
| Flag | Description |
|---|
--profile <name> | Profile to use. |
xpander agent tools operations --interface <interface_id>
| Flag | Description |
|---|
--interface <id> | Interface ID (from agent tools interfaces). |
--profile <name> | Profile to use. |
NeMo
NeMo support lives at the top level (not under agent), but it’s agent-config-related:
xpander nemo pull
Pull an agent’s model configuration into a local NeMo config file.
| Flag | Description |
|---|
--profile <name> | Profile to use. |
xpander nemo push
Push your local NeMo config changes back to the agent.
xpander nemo push --confirm
| Flag | Description |
|---|
--profile <name> | Profile to use. |
--confirm | Skip confirmation prompts. |
Common patterns
Deploy then test
xpander agent deploy my-agent
xpander agent invoke my-agent "test changes"
xpander agent logs my-agent
Iterate locally before deploying
xpander agent init my-agent # pull files
# edit xpander_handler.py
xpander agent dev my-agent # run locally
xpander agent deploy my-agent # ship when ready
Non-interactive for CI
xpander agent new --name "bot" --framework "agno" --folder "."
xpander agent deploy --agent-id "$XPANDER_AGENT_ID" --api-key "$XPANDER_API_KEY" --confirm
--confirm flag skips destructive-action prompts during deployment. Combine with --no-interactive (global) to fail fast if any prompt would otherwise appear.
