Agent Commands - xpander.ai

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]

When [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.

Without flags, the command runs an interactive wizard. Pass --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.

Files written:

Dockerfile
requirements.txt
xpander_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.

Starts the agent in your local Python environment using the .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.

What happens:

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:

Dockerfile
requirements.txt
xpander_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.

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

When run inside an agent directory with a .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.

Tools

The xpander platform organizes tools as interfaces (a connector or service: Slack, GitHub, Salesforce, etc.) and operations (the individual API calls each interface exposes: 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.

`xpander agent tools interfaces`

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`

List the operations exposed by a specific interface.

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.

xpander nemo pull

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

The --confirm flag skips destructive-action prompts during deployment. Combine with --no-interactive (global) to fail fast if any prompt would otherwise appear.

​Discovery

​xpander agent list

​xpander agent list-json

​xpander agent get <agent> (alias g)

​xpander agent interactive

​Control plane (CRUD)

​xpander agent new (alias n)

​xpander agent update

​xpander agent edit [agent] (alias o) / xpander agent open [agent]

​xpander agent delete [agent] (alias del)

​Local development

​xpander agent init [agent-id] (alias i)

​xpander agent templates

​xpander agent dev [agent]

​Cloud deployment

​xpander agent deploy [agent] (alias d)

​xpander agent logs [agent] (alias l)

​xpander agent restart [agent]

​xpander agent stop [agent]

​Invocation (testing)

​xpander agent invoke [agent] [message...]

​Graph

​xpander agent graph create

​xpander agent graph View

​Tools

​xpander agent tools interfaces

​xpander agent tools operations

​NeMo

​xpander nemo pull

​xpander nemo push

​Common patterns

​Deploy then test

​Iterate locally before deploying

​Non-interactive for CI

Discovery

`xpander agent list`

`xpander agent list-json`

`xpander agent get <agent>` (alias `g`)

`xpander agent interactive`

Control plane (CRUD)

`xpander agent new` (alias `n`)

`xpander agent update`

`xpander agent edit [agent]` (alias `o`) / `xpander agent open [agent]`

`xpander agent delete [agent]` (alias `del`)

Local development

`xpander agent init [agent-id]` (alias `i`)

`xpander agent templates`

`xpander agent dev [agent]`

Cloud deployment

`xpander agent deploy [agent]` (alias `d`)

`xpander agent logs [agent]` (alias `l`)

`xpander agent restart [agent]`

`xpander agent stop [agent]`

Invocation (testing)

`xpander agent invoke [agent] [message...]`

Graph

`xpander agent graph create`

`xpander agent graph View`

Tools

`xpander agent tools interfaces`

`xpander agent tools operations`

NeMo

`xpander nemo pull`

`xpander nemo push`

Common patterns

Deploy then test

Iterate locally before deploying

Non-interactive for CI