Dev Command
The dev
command runs your ElizaOS project or plugin in development mode with auto-rebuild and restart on file changes. This is the recommended way to develop and test your implementations locally.
Usage
Note: Assumes you have the elizaos CLI tool installed
elizaos dev [options]
Options
Option | Description |
---|---|
--port , -p | Port to listen on |
--configure | Reconfigure services and AI models (skips using saved configuration) |
--character | Path or URL to character file to use instead of default |
--build | Build the project before starting |
Development Features
When you run dev
, ElizaOS provides several developer-friendly features:
- Auto Rebuilding: Automatically rebuilds your project when source files change
- Auto Restarting: Restarts the server after rebuilds to apply changes
- File Watching: Monitors your source files for changes
- TypeScript Support: Compiles TypeScript files during rebuilds
- Detailed Error Messages: Provides comprehensive error information
What Happens During Dev Mode
When you run the dev
command, ElizaOS:
- Detects whether you're in a project or plugin directory
- Builds the project initially
- Starts the server using the
start
command with your options - Sets up file watching for .ts, .js, .tsx, and .jsx files
- Rebuilds and restarts when files change
For more information about project detection and startup process, see the Start Command.
Examples
Basic Development Mode
# Navigate to your project
cd my-agent-project
# Start development mode
elizaos dev
Custom Port
elizaos dev --port 8080
Using a Custom Character
elizaos dev --character ./characters/custom-assistant.json
Force Configuration
elizaos dev --configure
Development Process
A typical development workflow with ElizaOS:
- Edit code: Modify TypeScript/JavaScript files in your project
- Automatic rebuild: The dev server detects changes and rebuilds
- Automatic restart: The server restarts with your changes
- Test: Interact with your updated implementation
- Repeat: Continue the development cycle
File Watching
The dev command watches for changes in your project's source files, specifically:
- TypeScript files (
.ts
,.tsx
) - JavaScript files (
.js
,.jsx
)
The file watcher ignores:
node_modules/
directorydist/
directory.git/
directory
Logs and Debugging
The dev mode provides information about the file watching and rebuild process:
[info] Running in project mode
[info] Building project...
[success] Build successful
[info] Starting server...
[info] Setting up file watching for directory: /path/to/your/project
[success] File watching initialized in: /path/to/your/project/src
[info] File event: change - src/index.ts
[info] Triggering rebuild for file change: src/index.ts
[info] Rebuilding project after file change...
[success] Rebuild successful, restarting server...
Troubleshooting
Build failures
If your project fails to build:
[error] Initial build failed: Error message
[info] Continuing with dev mode anyway...
The server will still start, but you'll need to fix the build errors for proper functionality.
File watching issues
If file changes aren't being detected:
- Check if your files are in the watched directories
- Ensure you're modifying the right types of files (.ts, .js, .tsx, .jsx)
- Check for error messages in the console