Agent Command

Overview
Examples
Features
Troubleshooting

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>`, `--auth-token`
`get`	`g`	Get agent details	`-n, --name <name>`	`-j, --json`, `-o, --output [file]`, `-r, --remote-url`, `-p, --port`, `--auth-token`
`start`	`s`	Start an agent with a character profile	One of: `-n, --name`, `--path`, `--remote-character`	`-r, --remote-url <url>`, `-p, --port <port>`, `--auth-token`
`stop`	`st`	Stop an agent	`-n, --name` or `--all`	`-r, --remote-url <url>`, `-p, --port <port>`, `--auth-token`
`remove`	`rm`	Remove an agent	`-n, --name <name>`	`-r, --remote-url <url>`, `-p, --port <port>`, `--auth-token`
`set`		Update agent configuration	`-n, --name <name>` AND one of: `-c, --config` OR `-f, --file`	`-r, --remote-url <url>`, `-p, --port <port>`, `--auth-token`
`clear-memories`	`clear`	Clear all memories for an agent	`-n, --name <name>`	`-r, --remote-url <url>`, `-p, --port <port>`, `--auth-token`

Options Reference

Common Options (All Subcommands)

-r, --remote-url <url>: URL of the remote agent runtime
-p, --port <port>: Port to listen on
--auth-token <token>: API authentication token for secured runtimes

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 Specific Options

-n, --name <name>: Agent id, name, or index number from list
--all: Stop all running agents

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)

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

# Stop all running agents
elizaos agent stop --all

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

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:

Agent Name: Human-readable name (e.g., “eliza”, “pmairca”)
Agent ID: System-generated ID (e.g., “agent_123456”)
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

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

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

Getting Started

Commands

Usage

Subcommands

Options Reference

Common Options (All Subcommands)

Output Options (for `list` and `get`)

Get Specific Options

Start Specific Options

Stop Specific Options

Remove Specific Options

Set Specific Options

Clear Memories Specific Options

Listing Agents

Getting Agent Details

Starting Agents

Stopping Agents

Removing Agents

Updating Agent Configuration

Clearing Agent Memories

Output Formatting

`table` (Default)

`json`

Character File Structure

Agent Identification

Interactive Mode

Remote Runtime Configuration

Environment Variable

Command Line Option

Custom Port

Agent Lifecycle Workflow

1. Create Agent Character

2. Start Agent Runtime

3. Manage Agents

Troubleshooting

Connection Issues

Agent Not Found

Configuration Errors

​Usage

​Subcommands

​Options Reference

​Common Options (All Subcommands)

​Output Options (for list and get)

​Get Specific Options

​Start Specific Options

​Stop Specific Options

​Remove Specific Options

​Set Specific Options

​Clear Memories Specific Options

​Listing Agents

​Getting Agent Details

​Starting Agents

​Stopping Agents

​Removing Agents

​Updating Agent Configuration

​Clearing Agent Memories

​Output Formatting

​table (Default)

​json

​Character File Structure

​Agent Identification

​Interactive Mode

​Remote Runtime Configuration

​Environment Variable

​Command Line Option

​Custom Port

​Agent Lifecycle Workflow

​1. Create Agent Character

​2. Start Agent Runtime

​3. Manage Agents

​Troubleshooting

​Connection Issues

​Agent Not Found

​Configuration Errors

​Related Commands

Usage

Subcommands

Options Reference

Common Options (All Subcommands)

Output Options (for `list` and `get`)

Get Specific Options

Start Specific Options

Stop Specific Options

Remove Specific Options

Set Specific Options

Clear Memories Specific Options

Listing Agents

Getting Agent Details

Starting Agents

Stopping Agents

Removing Agents

Updating Agent Configuration

Clearing Agent Memories

Output Formatting

`table` (Default)

`json`

Character File Structure

Agent Identification

Interactive Mode

Remote Runtime Configuration

Environment Variable

Command Line Option

Custom Port

Agent Lifecycle Workflow

1. Create Agent Character

2. Start Agent Runtime

3. Manage Agents

Troubleshooting

Connection Issues

Agent Not Found

Configuration Errors

Related Commands