> ## 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` (full lifecycle, graph, tools, NeMo).

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`).

```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" --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.

```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 framework files 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 framework-specific config (`xpander_config.json`, `agent_instructions.json`, …).

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` without redeploying.

## Cloud deployment

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

Build and deploy the agent's Docker image to xpander.ai's cloud.

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

1. Uploads your local agent code.
2. Builds a Docker image.
3. Deploys and runs the container.
4. 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.

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

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

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

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

```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>

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

```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

### Deploy then test

```bash theme={"dark"}
xpander agent deploy my-agent
xpander agent invoke my-agent "test changes"
xpander agent logs my-agent
```

### Iterate locally before deploying

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

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