---
url: /docs/agents/reference/cli.md
description: >-
  Command reference for the Electric Agents CLI: spawn, send, observe, inspect,
  list, and manage entities.
---

# CLI

# CLI reference

The Electric Agents CLI manages entity types and entities. Install it from `electric-ax`, then use the `electric agents` command. You can also run one-off commands with `npx electric-ax agents ...`.

```bash
npm install -g electric-ax
```

## Environment variables

| Variable                         | Default                 | Purpose                                      |
| -------------------------------- | ----------------------- | -------------------------------------------- |
| `ELECTRIC_AGENTS_URL`            | `http://localhost:4437` | Server URL for entity commands and built-ins |
| `ELECTRIC_AGENTS_IDENTITY`       | `user@hostname`         | Sender identity for messages                 |
| `ELECTRIC_AGENTS_PORT`           | `4437`                  | Port used by `start` / `quickstart`          |
| `ELECTRIC_AGENTS_BUILTIN_PORT`   | `4448`                  | Webhook port for `start-builtin`             |
| `ELECTRIC_AGENTS_COMPOSE_PROJECT` | `electric-agents`       | Docker Compose project name                  |
| `ANTHROPIC_API_KEY`              | -                       | Required for `start-builtin` and `quickstart` |

## Commands

### types {#types}

List registered entity types.

```bash
electric agents types
```

### types inspect \<name> {#types-inspect-name}

Show entity type details. Outputs JSON.

```bash
electric agents types inspect chat
```

### types delete \<name> {#types-delete-name}

Delete an entity type registration.

```bash
electric agents types delete chat
```

### spawn \<url-path> \[--args \<json>] {#spawn-url-path-args-json}

Spawn an entity. URL path format: `/<type>/<id>`.

```bash
electric agents spawn /chat/my-convo
electric agents spawn /chat/my-convo --args '{"topic": "AI safety"}'
```

| Option          | Description                    |
| --------------- | ------------------------------ |
| `--args <json>` | Spawn arguments as JSON object |

### send \<url> \<message...> \[--type \<msg-type>] \[--json] {#send-url-message-type-json}

Send a message to an entity. By default, wraps the message string as `{ text: "..." }`. Use `--json` to send raw JSON.

```bash
electric agents send /chat/my-convo 'Hello!'
electric agents send /chat/my-convo '{"custom": "payload"}' --json
electric agents send /chat/my-convo 'alert' --type warning
```

| Option              | Description                                                      |
| ------------------- | ---------------------------------------------------------------- |
| `--type <msg-type>` | Set the message type field                                       |
| `--json`            | Parse message argument as JSON instead of wrapping as `{ text }` |

### observe \<url> \[--from \<offset>] {#observe-url-from-offset}

Stream entity events in real-time. Requires an interactive terminal.

```bash
electric agents observe /chat/my-convo
electric agents observe /chat/my-convo --from 0
```

| Option            | Description                      |
| ----------------- | -------------------------------- |
| `--from <offset>` | Start streaming from this offset |

### inspect \<url> {#inspect-url}

Show entity details. Outputs JSON.

```bash
electric agents inspect /chat/my-convo
```

### ps \[--type \<type>] \[--status \<status>] \[--parent \<url>] {#ps-type-status-parent}

List entities with optional filters.

```bash
electric agents ps
electric agents ps --type chat --status running
electric agents ps --parent /manager/my-manager
```

| Option              | Description                 |
| ------------------- | --------------------------- |
| `--type <type>`     | Filter by entity type       |
| `--status <status>` | Filter by status            |
| `--parent <url>`    | Filter by parent entity URL |

Output shows `URL`, `STATUS`, `CREATED`, and `LAST ACTIVE` columns with human-readable relative timestamps. Results are sorted by most recently active first.

### kill \<url> {#kill-url}

Delete an entity.

```bash
electric agents kill /chat/my-convo
```

### start {#start}

Start the local Electric Agents coordinator server, Postgres, Electric, and UI using Docker Compose.

```bash
electric agents start
```

### start-builtin \[--anthropic-api-key \<key>] {#start-builtin}

Start the built-in Horton runtime and register built-in agent types with the coordinator server.

```bash
electric agents start-builtin --anthropic-api-key sk-ant-...
```

| Option                         | Description                                    |
| ------------------------------ | ---------------------------------------------- |
| `--anthropic-api-key <key>`    | Anthropic API key for the built-in Horton server |

### quickstart \[--anthropic-api-key \<key>] {#quickstart}

Start the coordinator server, print onboarding commands, and run the built-in agents runtime.

```bash
electric agents quickstart --anthropic-api-key sk-ant-...
```

| Option                         | Description                                    |
| ------------------------------ | ---------------------------------------------- |
| `--anthropic-api-key <key>`    | Anthropic API key for the built-in Horton server |

### stop \[--remove-volumes] {#stop}

Stop the local Electric Agents dev environment.

```bash
electric agents stop
electric agents stop --remove-volumes
```

| Option             | Description                    |
| ------------------ | ------------------------------ |
| `--remove-volumes` | Remove Docker volumes as well. |

### init \[project-name] {#init-project-name}

Scaffold a new Electric Agents project from the bundled starter template.

```bash
electric agents init
electric agents init my-agents-app
```

### completion \[action] {#completion-action}

Set up shell completions. Without arguments, prints setup instructions.

```bash
electric agents completion            # Show setup instructions
electric agents completion install    # Auto-install into your shell init file
```

**Manual setup** (add to your shell init file):

```bash
# Bash (~/.bashrc) or Zsh (~/.zshrc)
eval "$(electric --completion)"

# Fish (~/.config/fish/config.fish)
electric --completion-fish | source
```

Completions provide tab-completion for commands, flags, entity types, and entity URLs.

## Programmatic CLI

The `electric-ax` package also exports the Commander program and handler factory used by the binary. Use these APIs for tests, custom wrappers, or embedding the command tree in another tool.

```ts
import {
  createElectricCliHandlers,
  createElectricProgram,
  getElectricCliEnv,
  run,
} from "electric-ax"

const env = getElectricCliEnv({
  ELECTRIC_AGENTS_URL: "http://localhost:4437",
  ELECTRIC_AGENTS_IDENTITY: "docs@example.com",
})

const handlers = createElectricCliHandlers(env, "electric agents")
const program = createElectricProgram({
  env,
  handlers,
  commandName: "electric",
  commandPrefix: "electric agents",
})

await program.parseAsync(["node", "electric", "agents", "types"])
```

| Export                            | Purpose                                                                  |
| --------------------------------- | ------------------------------------------------------------------------ |
| `DEFAULT_ELECTRIC_AGENTS_URL`     | Default server URL (`"http://localhost:4437"`).                          |
| `getElectricCliEnv(env?)`         | Reads `ELECTRIC_AGENTS_URL` and `ELECTRIC_AGENTS_IDENTITY`.              |
| `createElectricCliHandlers()`     | Creates the default command handlers.                                    |
| `createElectricProgram()`         | Creates the Commander program.                                           |
| `resolveCommandPrefix(argv, env?)` | Resolves help text examples for direct or package-manager invocation.    |
| `run(argv?)`                      | Runs the CLI entrypoint.                                                 |

The installed binaries are `electric` and `electric-ax`. The package also includes `electric-dev` for development workflows.