Agent Command

Managing elizaOS agents through the CLI - list, configure, start, stop, and update agents

Overview

Usage

elizaos agent [options] [command]

Subcommands

Subcommand	Aliases	Description	Required Options	Additional Options
list	ls	List available agents		-j, --json, -r, --remote-url <url>, -p, --port <port>
get	g	Get agent details	-n, --name <name>	-j, --json, -o, --output [file], -r, --remote-url, -p, --port
start	s	Start an agent with a character profile	One of: -n, --name, --path, --remote-character	-r, --remote-url <url>, -p, --port <port>
stop	st	Stop an agent	-n, --name <name>	-r, --remote-url <url>, -p, --port <port>
remove	rm	Remove an agent	-n, --name <name>	-r, --remote-url <url>, -p, --port <port>
set		Update agent configuration	-n, --name <name> AND one of: -c, --config OR -f, --file	-r, --remote-url <url>, -p, --port <port>
clear-memories	clear	Clear all memories for an agent	-n, --name <name>	-r, --remote-url <url>, -p, --port <port>

Options Reference

Common Options (All Subcommands)

• -r, --remote-url <url>: URL of the remote agent runtime
• -p, --port <port>: Port to listen on

Output Options (for list and get)

• -j, --json: Output as JSON format instead of the default table format.
• -o, --output [file]: For the get command, saves the agent’s configuration to a JSON file. If no filename is provided, defaults to {name}.json.

Get Specific Options

• -n, --name <name>: Agent id, name, or index number from list (required)

Start Specific Options

• -n, --name <name>: Name of an existing agent to start
• --path <path>: Path to local character JSON file
• --remote-character <url>: URL to remote character JSON file

Stop/Remove Specific Options

• -n, --name <name>: Agent id, name, or index number from list (required)

Set Specific Options

• -n, --name <name>: Agent id, name, or index number from list (required)
• -c, --config <json>: Agent configuration as JSON string
• -f, --file <path>: Path to agent configuration JSON file

Clear Memories Specific Options

• -n, --name <name>: Agent id, name, or index number from list (required)

Examples

Listing Agents

# List all available agents
elizaos agent list

# Using alias
elizaos agent ls

# List agents in JSON format
elizaos agent list --json
# Or using the shorthand
elizaos agent list -j

# List agents from remote runtime
elizaos agent list --remote-url http://server:3000

# List agents on specific port
elizaos agent list --port 4000

Getting Agent Details

# Get agent details by name
elizaos agent get --name eliza

# Get agent by ID
elizaos agent get --name agent_123456

# Get agent by index from list
elizaos agent get --name 0

# Display configuration as JSON in console
elizaos agent get --name eliza --json
# Or using the shorthand
elizaos agent get --name eliza -j

# Save agent configuration to file
elizaos agent get --name eliza --output

# Save to specific file
elizaos agent get --name eliza --output ./my-agent.json

# Using alias
elizaos agent g --name eliza

Starting Agents

# Start existing agent by name
elizaos agent start --name eliza

# Start with local character file
elizaos agent start --path ./characters/eliza.json

# Start from remote character file
elizaos agent start --remote-character https://example.com/characters/eliza.json

# Using alias
elizaos agent s --name eliza

# Start on specific port
elizaos agent start --path ./eliza.json --port 4000

Required Configuration: You must provide one of these options: --name, --path, or --remote-character

Stopping Agents

# Stop agent by name
elizaos agent stop --name eliza

# Stop agent by ID
elizaos agent stop --name agent_123456

# Stop agent by index
elizaos agent stop --name 0

# Using alias
elizaos agent st --name eliza

# Stop agent on remote runtime
elizaos agent stop --name eliza --remote-url http://server:3000

Removing Agents

# Remove agent by name
elizaos agent remove --name pmairca

# Remove agent by ID
elizaos agent remove --name agent_123456

# Using alias
elizaos agent rm --name pmairca

# Remove from remote runtime
elizaos agent remove --name pmairca --remote-url http://server:3000

Updating Agent Configuration

# Update with JSON string
elizaos agent set --name eliza --config '{"system":"Updated prompt"}'

# Update from configuration file
elizaos agent set --name eliza --file ./updated-config.json

# Update agent on remote runtime
elizaos agent set --name pmairca --config '{"model":"gpt-4"}' --remote-url http://server:3000

# Update agent on specific port
elizaos agent set --name eliza --file ./config.json --port 4000

Clearing Agent Memories

# Clear memories for agent by name
elizaos agent clear-memories --name eliza

# Clear memories by ID
elizaos agent clear-memories --name agent_123456

# Using alias
elizaos agent clear --name eliza

# Clear memories on remote runtime
elizaos agent clear-memories --name eliza --remote-url http://server:3000

Features

Output Formatting

The list and get commands support different output formats, making it easy to use the CLI in scripts or for human readability.

table (Default)

The default format is a human-readable table, best for viewing in the terminal.

$ elizaos agent list
┌─────────┬──────────────┬─────────┬──────────┐
│ (index) │     name     │   id    │  status  │
├─────────┼──────────────┼─────────┼──────────┤
│    0    │   'eliza'    │ 'agent…'│ 'running'│
└─────────┴──────────────┴─────────┴──────────┘

json

Outputs raw JSON data. Useful for piping into other tools like jq. Use the -j or --json flag.

# Get JSON output
elizaos agent get --name eliza --json
# Or using shorthand
elizaos agent get --name eliza -j

Character File Structure

When using --path or --remote-character, the character file should follow this structure:

{
  "name": "eliza",
  "system": "You are a friendly and knowledgeable AI assistant named Eliza.",
  "bio": ["Helpful and engaging conversationalist", "Knowledgeable about a wide range of topics"],
  "plugins": ["@elizaos/plugin-openai", "@elizaos/plugin-discord"],
  "settings": {
    "voice": {
      "model": "en_US-female-medium"
    }
  },
  "knowledge": ["./knowledge/general-info.md", "./knowledge/conversation-patterns.md"]
}

Agent Identification

Agents can be identified using:

1. Agent Name: Human-readable name (e.g., “eliza”, “pmairca”)
2. Agent ID: System-generated ID (e.g., “agent_123456”)
3. List Index: Position in elizaos agent list output (e.g., “0”, “1”, “2”)

Interactive Mode

All agent commands support interactive mode when run without required parameters:

# Interactive agent selection
elizaos agent get
elizaos agent start
elizaos agent stop
elizaos agent remove
elizaos agent set
elizaos agent clear-memories

Remote Runtime Configuration

By default, agent commands connect to http://localhost:3000. Override with:

Environment Variable

export AGENT_RUNTIME_URL=http://your-server:3000
elizaos agent list

Command Line Option

elizaos agent list --remote-url http://your-server:3000

Custom Port

elizaos agent list --port 4000

Agent Lifecycle Workflow

1. Create Agent Character

# Create character file
elizaos create -type agent eliza

# Or create project with character
elizaos create -type project my-project

2. Start Agent Runtime

# Start the agent runtime server
elizaos start

3. Manage Agents

# List available agents
elizaos agent list

# Start an agent
elizaos agent start --path ./eliza.json

# Check agent status
elizaos agent get --name eliza

# Update configuration
elizaos agent set --name eliza --config '{"system":"Updated prompt"}'

# Stop agent
elizaos agent stop --name eliza

# Clear agent memories if needed
elizaos agent clear-memories --name eliza

# Remove when no longer needed
elizaos agent remove --name eliza

Troubleshooting

Troubleshooting

Connection Issues

# Check if runtime is running
elizaos agent list

# If connection fails, start runtime first
elizaos start

# For custom URLs/ports
elizaos agent list --remote-url http://your-server:3000

Agent Not Found

# List all agents to see available options
elizaos agent list

# Try using agent ID instead of name
elizaos agent get --name agent_123456

# Try using list index
elizaos agent get --name 0

Configuration Errors

• Validate JSON syntax in character files and config strings
• Ensure all required fields are present in character definitions
• Check file paths are correct and accessible

Related Commands

• create: Create a new agent character file
• start: Start the agent runtime server
• dev: Run in development mode with hot-reload
• env: Configure environment variables for agents