> ## Documentation Index > Fetch the complete documentation index at: https://docs.elizaos.ai/llms.txt > Use this file to discover all available pages before exploring further. # Agent Command > Managing elizaOS agents through the CLI - list, configure, start, stop, and update agents ## Usage ```bash theme={null} elizaos agent [options] [command] ``` ## Subcommands | Subcommand | Aliases | Description | Required Options | Additional Options | | ---------------- | ------- | --------------------------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------------- | | `list` | `ls` | List available agents | | `-j, --json`, `-r, --remote-url `, `-p, --port `, `--auth-token` | | `get` | `g` | Get agent details | `-n, --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 `, `-p, --port `, `--auth-token` | | `stop` | `st` | Stop an agent | `-n, --name` or `--all` | `-r, --remote-url `, `-p, --port `, `--auth-token` | | `remove` | `rm` | Remove an agent | `-n, --name ` | `-r, --remote-url `, `-p, --port `, `--auth-token` | | `set` | | Update agent configuration | `-n, --name ` AND one of: `-c, --config` OR `-f, --file` | `-r, --remote-url `, `-p, --port `, `--auth-token` | | `clear-memories` | `clear` | Clear all memories for an agent | `-n, --name ` | `-r, --remote-url `, `-p, --port `, `--auth-token` | ## Options Reference ### Common Options (All Subcommands) * `-r, --remote-url `: URL of the remote agent runtime * `-p, --port `: Port to listen on * `--auth-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 `: Agent id, name, or index number from list (required) ### Start Specific Options * `-n, --name `: Name of an existing agent to start * `--path `: Path to local character JSON file * `--remote-character `: URL to remote character JSON file ### Stop Specific Options * `-n, --name `: Agent id, name, or index number from list * `--all`: Stop all running agents ### Remove Specific Options * `-n, --name `: Agent id, name, or index number from list (required) ### Set Specific Options * `-n, --name `: Agent id, name, or index number from list (required) * `-c, --config `: Agent configuration as JSON string * `-f, --file `: Path to agent configuration JSON file ### Clear Memories Specific Options * `-n, --name `: Agent id, name, or index number from list (required) ### Listing Agents ```bash theme={null} # 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 ```bash theme={null} # 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 ```bash theme={null} # 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 ```bash theme={null} # 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 ```bash theme={null} # 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 ```bash theme={null} # 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 ```bash theme={null} # 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. ```bash theme={null} $ 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. ```bash theme={null} # 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: ```json theme={null} { "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: ```bash theme={null} # 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 ```bash theme={null} export AGENT_RUNTIME_URL=http://your-server:3000 elizaos agent list ``` ### Command Line Option ```bash theme={null} elizaos agent list --remote-url http://your-server:3000 ``` ### Custom Port ```bash theme={null} elizaos agent list --port 4000 ``` ## Agent Lifecycle Workflow ### 1. Create Agent Character ```bash theme={null} # Create character file elizaos create -type agent eliza # Or create project with character elizaos create -type project my-project ``` ### 2. Start Agent Runtime ```bash theme={null} # Start the agent runtime server elizaos start ``` ### 3. Manage Agents ```bash theme={null} # 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 ```bash theme={null} # 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 ```bash theme={null} # 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`](/cli-reference/create): Create a new agent character file * [`start`](/cli-reference/start): Start the agent runtime server * [`dev`](/cli-reference/dev): Run in development mode with hot-reload * [`env`](/cli-reference/env): Configure environment variables for agents