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

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

List registered entity types.

electric agents types

types inspect <name>

Show entity type details. Outputs JSON.

electric agents types inspect chat

types delete <name>

Delete an entity type registration.

electric agents types delete chat

spawn <url-path> [--args <json>]

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

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 a message to an entity. By default, wraps the message string as { text: "..." }. Use --json to send raw JSON.

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

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

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>

Show entity details. Outputs JSON.

electric agents inspect /chat/my-convo

ps [--type <type>] [--status <status>] [--parent <url>]

List entities with optional filters.

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>

Delete an entity.

electric agents kill /chat/my-convo

start

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

electric agents start

start-builtin [--anthropic-api-key <key>]

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

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

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

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 the local Electric Agents dev environment.

electric agents stop
electric agents stop --remove-volumes

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

init [project-name]

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

electric agents init
electric agents init my-agents-app

completion [action]

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

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 (~/.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.

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

const env = getElectricCliEnv({
  ELECTRIC_AGENTS_URL: "http://localhost:4437",
  ELECTRIC_AGENTS_IDENTITY: "[email protected]",
})

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.