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

# Agent Commands

> Every command under `xpander agent` (control plane, local dev, graph, skills, NeMo).

The `xpander agent` namespace covers agent management plus graph editing, skill discovery, and NeMo model-config sync. Most lifecycle commands also exist as top-level shortcuts (`xpander dev` ≡ `xpander agent dev`).

```bash theme={"dark"}
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).

```bash theme={"dark"}
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.

```bash theme={"dark"}
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.

```bash theme={"dark"}
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.

```bash theme={"dark"}
xpander agent interactive
```

## Control plane (CRUD)

### `xpander agent new` (alias `n`)

Create a new agent in the xpander.ai cloud.

```bash theme={"dark"}
xpander agent new
xpander agent new --name "bot" --framework "agno" --folder "."
xpander agent n --name "bot" --model "gpt-4o" --init --json
```

| Flag | Description |
| - | - |
| `--name <name>` | Agent name. |
| `--model <model>` | LLM model id. Defaults to `gpt-4o`. |
| `--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.

```bash theme={"dark"}
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.

```bash theme={"dark"}
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.

```bash theme={"dark"}
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 template files for its agent loop into the current directory.

```bash theme={"dark"}
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 template-specific config (`xpander_config.json`, `agent_instructions.json`, and so on).

The base templates can be inspected via [`xpander agent templates`](#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.

```bash theme={"dark"}
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` against real prompts.

## Invocation (testing)

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

Test an agent (running locally or on xpander) and print the response.

```bash theme={"dark"}
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 skill operations the agent is allowed to call, along with the allowed transitions between them. xpander uses it to constrain skill selection during a run. The CLI commands here are for scripting and CI.

### `xpander agent graph create`

Create an operation graph for an agent.

```bash theme={"dark"}
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.

```bash theme={"dark"}
xpander agent graph View -a abc123
```

| Flag | Description |
| - | - |
| `-a, --agent-id <id>` | Agent whose graph to view. |

<Note>
  The `View` subcommand is capitalized in the CLI: type it exactly as `xpander agent graph View`.
</Note>

## Skills

The `xpander agent tools` commands work with skills: in the SDK a skill is a `Tool`, the name agent loops use for them, and the CLI reuses that name for this command group. xpander organizes skills as **interfaces** (a service from the skills catalog: 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 skills your agents can use).

```bash theme={"dark"}
xpander agent tools interfaces
```

| Flag | Description |
| - | - |
| `--profile <name>` | Profile to use. |

### `xpander agent tools operations`

List the operations exposed by a specific interface.

```bash theme={"dark"}
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.

```bash theme={"dark"}
xpander nemo pull
```

| Flag | Description |
| - | - |
| `--profile <name>` | Profile to use. |

### `xpander nemo push`

Push your local NeMo config changes back to the agent.

```bash theme={"dark"}
xpander nemo push --confirm
```

| Flag | Description |
| - | - |
| `--profile <name>` | Profile to use. |
| `--confirm` | Skip confirmation prompts. |

## Common patterns

### Non-interactive for CI

```bash theme={"dark"}
xpander agent new --name "bot" --framework "agno" --folder "."
```

Combine with `--no-interactive` (global) to fail fast if any prompt would otherwise appear.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.