@elizaos/cli
Advanced tools
The ElizaOS CLI provides a comprehensive set of commands to manage your ElizaOS projects and plugins, from local development to cloud deployment.
bun install -g @elizaos/cli
The ElizaOS CLI requires Bun as its package manager. If Bun is not installed when you run the CLI, it will attempt to automatically install it for you.
Auto-installation features:
--no-auto-install flagTo disable auto-installation:
# Global flag (applies to all commands)
elizaos --no-auto-install create my-project
# Environment variable
ELIZA_NO_AUTO_INSTALL=true elizaos create my-project
The following options are available for all ElizaOS CLI commands:
--no-emoji: Disable emoji output for better compatibility with certain terminals or scripts--no-auto-install: Disable automatic Bun installation (useful in CI environments or when you prefer manual control)-v, --version: Show the CLI version number-h, --help: Display help informationExample usage:
# Disable auto-installation and emojis
elizaos --no-auto-install --no-emoji create my-project
# Just show version
elizaos --version
Below is a comprehensive reference for all ElizaOS CLI commands, including their options, arguments, and subcommands. For the most up-to-date usage, run elizaos [command] --help.
elizaos create [name]Initialize a new project, plugin, or agent.
[name]: Name for the project, plugin, or agent (optional)-y, --yes: Skip confirmation and use defaults (default: false)-t, --type <type>: Type to create: 'project', 'plugin', 'agent', or 'tee' (default: 'project')Important notes:
elizaos devStart the project or plugin in development mode with auto-rebuild, detailed logging, and file change detection.
-c, --configure: Reconfigure services and AI models (skips using saved configuration)--character [paths...]: Character file(s) to use - accepts paths or URLs-b, --build: Build the project before starting-p, --port <port>: Port to listen onCharacter Handling:
The dev command supports flexible character specification:
# Space-separated paths
elizaos dev --character file1.json file2.json
# Comma-separated paths
elizaos dev --character "file1.json,file2.json"
# Mixed formats with optional quotes
elizaos dev --character "'file1.json'" "file2.json"
# With or without .json extension
elizaos dev --character assistant # .json extension added automatically
# URLs are also supported
elizaos dev --character https://example.com/characters/assistant.json
elizaos env <subcommand>Manage environment variables and secrets.
list: List all environment variables
--localedit-local: Edit local environment variables
-y, --yesreset: Reset all environment variables
-y, --yesinteractive: Interactive environment variable management
-y, --yeselizaos monorepoClone ElizaOS monorepo from a specific branch (defaults to develop).
-b, --branch <branch>: Branch to install (default: develop)-d, --dir <directory>: Destination directory (default: ./eliza)Notes:
elizaos plugins <subcommand>Manage an ElizaOS plugin.
list (alias: l): List available plugins (shows v1.x plugins by default)add <plugin> (alias: install): Add a plugin to the project
<plugin> (plugin name)-n, --no-env-prompt, -b, --branch <branchName>, -T, --tag <tagname>update (alias: refresh): Fetch the latest plugin registry and update local cacheinstalled-plugins: List plugins found in the project dependenciesremove <plugin> (alias: delete): Remove a plugin from the project
<plugin> (plugin name)upgrade <path>: Upgrade a plugin from v0.x to v1.x using AI
<path> (GitHub URL or local path)--api-key <key>, --skip-tests, --skip-validationelizaos agent <subcommand>Manage ElizaOS agents.
list (alias: ls): List available agents
-j, --json: Output as JSON-r, --remote-url <url>: URL of the remote agent runtime-p, --port <port>: Port to listen onget (alias: g): Get agent details
-n, --name <name>: Agent id, name, or index number from list-j, --json: Display JSON output in terminal-o, --output <file>: Save agent data to file-r, --remote-url <url>: URL of the remote agent runtime-p, --port <port>: Port to listen onstart (alias: s): Start an agent
-n, --name <name>: Name of an existing agent to start--path <path>: Local path to character JSON file--remote-character <url>: URL to remote character JSON file-r, --remote-url <url>: URL of the remote agent runtime-p, --port <port>: Port to listen onstop (alias: st): Stop an agent
-n, --name <name>: Agent id, name, or index number from list--all: Stop all running ElizaOS agents locally-r, --remote-url <url>: URL of the remote agent runtime-p, --port <port>: Port to listen onremove (alias: rm): Remove an agent
-n, --name <name>: Agent id, name, or index number from list-r, --remote-url <url>: URL of the remote agent runtime-p, --port <port>: Port to listen onset: Update agent configuration
-n, --name <name>: Agent id, name, or index number from list-c, --config <json>: Agent configuration as JSON string-f, --file <path>: Path to agent configuration JSON file-r, --remote-url <url>: URL of the remote agent runtime-p, --port <port>: Port to listen onNote: All agent commands support interactive mode when run without key parameters.
elizaos publishPublish a plugin to the registry.
-t, --test: Test publish process without making changes--npm: Publish to npm instead of GitHub--skip-registry: Skip publishing to the registry-d, --dry-run: Generate registry files locally without publishingDefault behavior:
npm-only mode:
--npm flag to publish only to npmImportant for continuous development:
The elizaos publish command is designed for initial plugin publishing only. After initial publishing, use standard npm and git workflows for updates:
bun version patch|minor|major to update version (or npm version if preferred)npm publish to publish to npmgit push origin main && git push --tags to update GitHubThe ElizaOS registry automatically syncs with npm updates.
elizaos startStart the Eliza agent with configurable plugins and services.
-c, --configure: Force reconfiguration of services and AI models (bypasses saved configuration)--character [paths...]: Character file(s) to use - accepts paths or URLs-b, --build: Build the project before starting-p, --port <port>: Port to listen on (default: 3000)Character Handling:
The start command accepts characters in various formats:
# Multiple character files (space-separated)
elizaos start --character file1.json file2.json
# Comma-separated format
elizaos start --character "file1.json,file2.json"
# With or without quotes
elizaos start --character "'file1.json'" "file2.json"
# Extension-optional (.json added automatically if missing)
elizaos start --character character1
# URLs are supported
elizaos start --character https://example.com/characters/assistant.json
If any character files fail to load, ElizaOS will:
elizaos testRun tests for Eliza agent plugins and projects.
ElizaOS employs a dual testing strategy:
Component Tests (src/__tests__/*.test.ts)
E2E Tests (src/__tests__/e2e/*.e2e.ts)
component: Run component tests (via bun:test)e2e: Run end-to-end runtime testsall: Run both component and e2e tests (default)-p, --port <port>: Port to listen on for e2e tests-n, --name <n>: Filter tests by name (matches file names or test suite names). Case sensitive.--skip-build: Skip building before running testsE2E Test Structure:
src/plugin.ts via the tests arraysrc/index.ts via the tests array[template-name].e2e.tselizaos tee phala <subcommand>Manage TEE deployments using the official Phala Cloud CLI. This integration provides seamless access to Phala's decentralized TEE cloud infrastructure directly through the ElizaOS CLI.
All Phala Cloud CLI commands are passed through transparently, allowing you to use the full functionality of Phala's TEE platform.
elizaos tee phala <command> [options]
elizaos tee phala help - Display help for all commandselizaos tee phala join (alias: free) - Join Phala Cloud! Get an account and deploy a CVM for FREEelizaos tee phala demo - Launch demo applications on Phala Cloud (Jupyter Notebook, HTTPBin)elizaos tee phala auth)elizaos tee phala auth login [api-key] - Set the API key for authentication
elizaos tee phala auth logout - Remove the stored API key
elizaos tee phala auth status - Check authentication status
elizaos tee phala cvms)elizaos tee phala cvms list (alias: ls) - List all CVMs
-j, --json - Output in JSON formatelizaos tee phala cvms create - Create a new CVM
-n, --name <name> - Name of the CVM-c, --compose <compose> - Path to Docker Compose file--vcpu <vcpu> - Number of vCPUs (default: 2)--memory <memory> - Memory in MB (default: 4096)--disk-size <diskSize> - Disk size in GB (default: 40)--teepod-id <teepodId> - TEEPod ID to use (will prompt if not provided)--image <image> - Version of dstack image to use (will prompt if not provided)-e, --env-file <envFile> - Path to environment file--skip-env - Skip environment variable prompt (default: false)--debug - Enable debug mode (default: false)elizaos tee phala cvms get [app-id] - Get details of a CVM
-j, --json - Output in JSON formatelizaos tee phala cvms start [app-id] - Start a stopped CVM
elizaos tee phala cvms stop [app-id] - Stop a running CVM
elizaos tee phala cvms restart [app-id] - Restart a CVM
elizaos tee phala cvms delete [app-id] - Delete a CVM
-f, --force - Skip confirmation promptelizaos tee phala cvms upgrade [app-id] - Upgrade a CVM to a new version
-c, --compose <compose> - Path to new Docker Compose file--env-file <envFile> - Path to environment file--debug - Enable debug modeelizaos tee phala cvms resize [app-id] - Resize resources for a CVM
-v, --vcpu <vcpu> - Number of virtual CPUs-m, --memory <memory> - Memory size in MB-d, --disk-size <diskSize> - Disk size in GB-r, --allow-restart <allowRestart> - Allow restart of the CVM if needed-y, --yes - Automatically confirm the resize operationelizaos tee phala cvms attestation [app-id] - Get attestation information for a CVM
elizaos tee phala docker)elizaos tee phala docker login - Login to Docker Hub
elizaos tee phala docker build - Build a Docker image
--image <image> - Docker image name--tag <tag> - Tag for the Docker imageelizaos tee phala docker push - Push a Docker image to Docker Hub
--image <image> - Docker image name--tag <tag> - Tag to pushelizaos tee phala docker generate - Generate a Docker Compose file
-i, --image <imageName> - Docker image name to use in the compose file-e, --env-file <envFile> - Path to environment variables file-o, --output <output> - Output path for generated docker-compose.yml--template <template> - Template to use for the generated docker-compose.ymlelizaos tee phala simulator)elizaos tee phala simulator start - Start the TEE simulator
-i, --image <image> - Simulator image to use-p, --port <port> - Simulator port (default: 8090) (default: "8090")-t, --type <type> - Simulator type (docker, native) (default: "docker")elizaos tee phala simulator stop - Stop the TEE simulator
Sign up for Phala Cloud:
elizaos tee phala free
# Or visit https://cloud.phala.network to create an account
Authenticate:
elizaos tee phala auth login <your-api-key>
elizaos tee phala auth status
Deploy your first Eliza Agent:
# Create a TEE project starter template
elizaos create -t tee tee-agent
# cd into directory and authenticate your Phala Cloud API Key
cd tee-agent
elizaos tee phala auth login
# Log into Docker and ensure docker is running
elizaos tee phala docker build
# Publish the Docker image you built
elizaos tee phala docker push
# Generate a Docker Compose file or update the image in the existing docker compose file
elizaos tee phala docker generate --template eliza
# Create and deploy a CVM
elizaos tee phala cvms create --name elizaos -c <docker-compose file> -e <path to .env>
# Check deployment status
elizaos tee phala cvms list
# Upgrade existing deployment
elizaos tee phala cvms upgrade -c <docker-compose file> -e <path to .env (optional)>
Verify TEE attestation:
elizaos tee phala cvms attestation <app-id>
For private Docker images, set these environment variables before deployment and add them to your docker-compose file:
DockerHub:
DSTACK_DOCKER_USERNAME - Your DockerHub usernameDSTACK_DOCKER_PASSWORD - Your DockerHub password or access tokenDSTACK_DOCKER_REGISTRY - Registry URL (optional, defaults to DockerHub)AWS ECR:
DSTACK_AWS_ACCESS_KEY_ID - AWS access keyDSTACK_AWS_SECRET_ACCESS_KEY - AWS secret keyDSTACK_AWS_REGION - AWS regionDSTACK_AWS_ECR_REGISTRY - Full ECR registry URLelizaos tee phala help or elizaos tee phala <command> --helpAll commands support the full range of options available in the official Phala CLI. For the most current command reference, run npx phala help.
elizaos updateUpdate ElizaOS CLI and project dependencies to the latest versions.
-c, --check: Check for available updates without applying them - shows what packages would be updated--skip-build: Skip building after updating--cli: Update only the global CLI installation (without updating packages)--packages: Update only packages (without updating the CLI)elizaos envManage environment variables and secrets.
list: List all environment variables
--system, --localedit-local: Edit local environment variables
-y, --yesreset: Reset environment variables and clean up database/cache files
-y, --yesinteractive: Start interactive environment variable manager
-y, --yesTo stop all running ElizaOS agents locally, use:
elizaos agent stop --all
This command uses pkill to terminate all ElizaOS processes. For stopping individual agents, see the Agent Management section.
Agents are character definitions for ElizaOS bots.
Create a new agent character:
elizaos create my-assistant --type agent
This creates a JSON file (my-assistant.json) with the character definition.
Start an agent with the character:
elizaos agent start --path my-assistant.json
Plugins extend the functionality of ElizaOS agents by providing additional capabilities or integrations.
Create a new plugin:
elizaos create my-plugin --type plugin
cd plugin-my-plugin # Note: CLI automatically adds plugin- prefix if not present
Structure of a plugin:
plugin-my-plugin/
├── src/ # Source code
│ └── index.ts # Main entry point defining the plugin
├── images/ # Required for publishing to registry
│ ├── logo.jpg # 400x400px square (<500KB)
│ └── banner.jpg # 1280x640px (<1MB)
├── package.json # Package configuration with agentConfig section
├── tsconfig.json # TypeScript configuration
└── README.md # Documentation
Implement your plugin:
Your plugin's main file (src/index.ts) should export a plugin object:
import { type Plugin, type IAgentRuntime } from '@elizaos/core';
import { z } from 'zod';
// Define config schema for validation
const configSchema = z.object({
API_KEY: z.string().min(1, 'API key is required'),
});
// Export the plugin object
export const myPlugin: Plugin = {
name: 'plugin-my-plugin',
description: 'My custom plugin description',
// Config section maps environment variables to plugin settings
config: {
API_KEY: process.env.MY_PLUGIN_API_KEY,
},
// Initialization function
async init(config: Record<string, string>) {
// Validate config
const validatedConfig = await configSchema.parseAsync(config);
// Plugin setup
return {
// Plugin methods and handlers
// ...
};
},
};
// Default export
export default myPlugin;
Configure package.json:
Add an agentConfig section to describe your plugin parameters:
"agentConfig": {
"pluginType": "elizaos:plugin:1.0.0",
"pluginParameters": {
"API_KEY": {
"type": "string",
"description": "API key for the service"
}
}
}
Test your plugin:
# Run tests during development
elizaos test
# Or with the CLI directly:
elizaos test
# Test specific components
elizaos test component
# Test end-to-end functionality
elizaos test e2e
E2E Test Structure:
plugin-my-plugin/
├── src/
│ ├── __tests__/
│ │ ├── e2e/
│ │ │ ├── plugin-my-plugin.e2e.ts # E2E test suite
│ │ │ └── README.md # E2E test documentation
│ │ └── *.test.ts # Component unit tests
│ └── plugin.ts # Export tests here: tests: [MyPluginTestSuite]
Publish your plugin:
# Login to npm first (still needed for publishing)
npm login
# Test your plugin thoroughly
elizaos test
# Test publishing process
elizaos publish --test
# Publish to npm + GitHub + registry (recommended)
elizaos publish
Continuous development workflow:
# Make changes to your plugin
elizaos dev # Test locally
# Test your changes
elizaos test
# Update version and publish updates
bun version patch # or minor/major
npm publish # Note: npm publish is still required for registry
git push origin main && git push --tags
Projects contain agent configurations and code for building agent-based applications.
Create a new project:
elizaos create my-agent-project
cd my-agent-project
Project structure:
my-agent-project/
├── src/ # Source code
│ ├── index.ts # Main entry point with character definition
│ └── plugins.ts # Custom project plugin implementation
├── data/ # Data storage directory
│ └── uploads/ # For uploaded files
├── package.json # Package configuration
├── tsconfig.json # TypeScript configuration
└── README.md # Documentation
Configure your agent:
The main character definition is in src/index.ts:
import { type Character } from '@elizaos/core';
export const character: Character = {
name: 'My Assistant',
plugins: [
'@elizaos/plugin-openai',
// Add other plugins here
],
system: 'You are a helpful assistant...',
bio: [
'Helpful and knowledgeable',
'Communicates clearly and concisely',
// Other character traits
],
messageExamples: [
// Example conversations
],
};
Add plugins to your project:
elizaos plugins add @elizaos/plugin-openai
Run your project in development mode:
elizaos dev
Build and start your project:
elizaos start
Test your project:
# Run all tests
elizaos test
# Run component tests only
elizaos test component
# Run e2e tests only
elizaos test e2e
# Test with specific options (--name is case sensitive)
elizaos test --port 4000 --name specific-test
E2E Test Structure for Projects:
my-agent-project/
├── src/
│ ├── __tests__/
│ │ ├── e2e/
│ │ │ ├── project-my-agent.e2e.ts # E2E test suite
│ │ │ └── README.md # E2E test documentation
│ │ └── *.test.ts # Component unit tests
│ └── index.ts # Export tests here: tests: [MyProjectTestSuite]
Development workflow:
# Make changes to your project
elizaos dev # Development mode with hot-reload
# Test your changes
elizaos test
# Build and start in production mode
elizaos start
For contributing to the ElizaOS CLI, please clone the monorepo using:
elizaos monorepo
FAQs
elizaOS CLI - Manage your AI agents and plugins
The npm package @elizaos/cli receives a total of 4,405 weekly downloads. As such, @elizaos/cli popularity was classified as popular.
We found that @elizaos/cli demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 5 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Former RubyGems maintainers have launched The Gem Cooperative, a new community-run project aimed at rebuilding open governance in the Ruby ecosystem.
Security News
An opt-in lazy import keyword aims to speed up Python startups, especially CLIs, without the ecosystem-wide risks that sank PEP 690.
Security News
Socket CEO Feross Aboukhadijeh discusses the recent npm supply chain attacks on PodRocket, covering novel attack vectors and how developers can protect themselves.