@elizaos/cli 1.0.0-beta.6 → 1.0.0-beta.60

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 Shaw Walters, aka Moon aka @lalalune
+Copyright (c) 2025 Shaw Walters and elizaOS Contributors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,203 +1,487 @@
-# CLI
+# ElizaOS CLI
 
-The CLI provides a set of commands to manage your ElizaOS projects and plugins, from local development to cloud deployment.
+The ElizaOS CLI provides a comprehensive set of commands to manage your ElizaOS projects and plugins, from local development to cloud deployment.
 
-# TODO: CLI Documentation goes here
+## Installation
 
-## Environment Variables
+```bash
+bun install -g @elizaos/cli@beta
+```
+
+### Alternative usage with npx
 
-Create a .env file with your required variables:
+You can also run the CLI directly without installation using npx:
 
-```env
-ANTHROPIC_API_KEY=your_key
-TELEGRAM_BOT_TOKEN=your_token
-# Add other required variables
+```bash
+npx @elizaos/cli@beta [command]
 ```
 
-# TEE Deployment Docs
+This is useful for trying out commands without installing the CLI globally.
 
-## Getting Started
+## Commands
 
-### Prerequisites
+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`.
 
-- Docker installed and running
-- Node.js and npm/bun installed
-- A Docker Hub account for publishing images
-- A Phala Cloud (https://cloud.phala.network/login) API key for cloud deployments
+### Project Creation
 
-## Commands
+#### `elizaos create [name]`
 
-### Building Your Image
+Initialize a new project, plugin, or agent.
 
-Build your Docker image locally:
+- **Arguments:**
+  - `[name]`: Name for the project, plugin, or agent (optional)
+- **Options:**
+  - `-d, --dir <dir>`: Installation directory (default: `.`)
+  - `-y, --yes`: Skip confirmation and use defaults (default: `false`)
+  - `-t, --type <type>`: Type to create: 'project', 'plugin', or 'agent' (default: 'project')
 
-```bash
-elizaos tee phala build \
-  -i your-image-name \
-  -u your-dockerhub-username \
-  -f path/to/Dockerfile \
-  -t tag-name
-```
+**Important notes:**
 
-### Running the TEE Simulator
+- Projects include a knowledge directory and a prompt for database selection (pglite or postgres)
+- Plugins are automatically prefixed with "plugin-" if the prefix is missing
+- Agents are created as JSON character definition files in the current directory
 
-Start the local TEE simulator for testing:
+### Development
 
-```bash
-elizaos tee phala simulator
-```
+#### `elizaos dev`
 
-This will start the simulator on http://localhost:8090.
+Start the project or plugin in development mode and rebuild on file changes.
 
-### Local Development
+- **Options:**
+  - `-c, --configure`: Reconfigure services and AI models
+  - `-char, --character [paths...]`: Character file(s) to use - accepts paths or URLs
+  - `-b, --build`: Build the project before starting
+  - `-p, --port <port>`: Port number to run the server on
 
-You can develop your agent locally in two ways:
+**Character Handling:**
 
-1. Build the docker-compose file separately:
+The `dev` command supports flexible character specification:
 
 ```bash
-elizaos tee phala build-compose \
-  -i your-image-name \
-  -u your-dockerhub-username \
-  -t tag-name \
-  -c path/to/character.json \
-  -e path/to/.env \
-  -v v2  # or v1 for legacy mode
-```
+# Space-separated paths
+elizaos dev --character file1.json file2.json
 
-2. Run an existing compose file:
+# Comma-separated paths
+elizaos dev --character "file1.json,file2.json"
 
-```bash
-elizaos tee phala run-local \
-  -c path/to/docker-compose.yml \
-  -e path/to/.env
+# 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
 ```
 
-This separation allows you to:
+### Environment Management
 
-- Build compose files without running them immediately
-- Version control your compose files
-- Share compose files with team members
-- Run the same compose file multiple times
+#### `elizaos env <subcommand>`
 
-The CLI will store generated compose files in:
+Manage environment variables and secrets.
 
-```
-.tee-cloud/
-  └── compose-files/     # Generated docker-compose files
-      └── your-character-tee-compose.yaml
-```
+- **Subcommands:**
+  - `list`: List all environment variables
+    - Options: `--local`
+  - `edit-local`: Edit local environment variables
+    - Options: `-y, --yes`
+  - `reset`: Reset all environment variables
+    - Options: `-y, --yes`
+  - `interactive`: Interactive environment variable management
+    - Options: `-y, --yes`
 
-### Publishing Your Image
+### Monorepo Setup
 
-Push your built image to Docker Hub:
+#### `elizaos setup-monorepo`
 
-```bash
-elizaos tee phala publish \
-  -i your-image-name \
-  -u your-dockerhub-username \
-  -t tag-name
-```
+Clone ElizaOS monorepo from a specific branch (defaults to v2-develop).
 
-### List Available Tags
+- **Options:**
+  - `-b, --branch <branch>`: Branch to install (default: `v2-develop`)
+  - `-d, --dir <directory>`: Destination directory (default: `./eliza`)
 
-View all tags for your image on Docker Hub:
+**Notes:**
 
-```bash
-elizaos tee phala list-tags \
-  -i your-image-name \
-  -u your-dockerhub-username
-```
+- The destination directory must be empty or non-existent
+- After cloning, follow the displayed instructions to install dependencies and build the project
 
-### Cloud Deployment
+### Plugin Management
 
-First, set your Phala Cloud API key:
+#### `elizaos plugins <subcommand>`
 
-```bash
-elizaos tee phala set-apikey your-api-key
-```
+Manage an ElizaOS plugin.
 
-Deploy to Phala Cloud:
+- **Subcommands:**
+  - `list` (aliases: `l`, `ls`): List all available plugins
+  - `add <plugin>` (alias: `install`): Add a plugin to the project
+    - Arguments: `<plugin>` (plugin name)
+    - Options: `-n, --no-env-prompt`, `-b, --branch <branchName>`
+  - `installed-plugins`: List plugins found in the project dependencies
+  - `remove <plugin>` (aliases: `delete`, `del`, `rm`): Remove a plugin from the project
+    - Arguments: `<plugin>` (plugin name)
 
-```bash
-elizaos tee phala deploy \
-  -t phala \
-  -m docker-compose \
-  -n your-deployment-name \
-  -c path/to/docker-compose.yml \
-  --env-file path/to/.env
-```
+### Agent Management
 
-### Managing Cloud Deployments
+#### `elizaos agent <subcommand>`
 
-List your active agents (CVMs):
+Manage ElizaOS agents.
 
-```bash
-elizaos tee phala list-cvms
-```
+- **Subcommands:**
+  - `list` (alias: `ls`): List available agents
+    - Options: `-j, --json` (output as JSON)
+  - `get` (alias: `g`): Get agent details
+    - Options:
+      - `-n, --name <n>`: Agent id, name, or index number from list
+      - `-j, --json`: Display JSON output in terminal
+      - `-o, --output <file>`: Save agent data to file
+  - `start` (alias: `s`): Start an agent
+    - Options:
+      - `-n, --name <n>`: Name of an existing agent to start
+      - `-j, --json <json>`: Character JSON configuration string
+      - `--path <path>`: Local path to character JSON file
+      - `--remote-character <url>`: URL to remote character JSON file
+  - `stop` (alias: `st`): Stop an agent
+    - Options:
+      - `-n, --name <n>`: Agent id, name, or index number from list
+  - `remove` (alias: `rm`): Remove an agent
+    - Options:
+      - `-n, --name <n>`: Agent id, name, or index number from list
+  - `set`: Update agent configuration
+    - Options:
+      - `-n, --name <n>`: 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
 
-List your TEE pods:
+**Note:** All agent commands support interactive mode when run without key parameters.
 
-```bash
-elizaos tee phala teepods
-```
+### Publishing
 
-List images in a specific TEE pod:
+#### `elizaos publish`
 
-```bash
-elizaos tee phala images --teepod-id your-teepod-id
-```
+Publish a plugin or project to the registry, GitHub, or npm.
 
-Upgrade an existing deployment:
+- **Options:**
+  - `-t, --test`: Run publish tests without actually publishing
+  - `-n, --npm`: Publish to npm
+  - `-s, --skip-registry`: Skip publishing to the registry
+
+### Agent/Server Management
+
+#### `elizaos start`
+
+Start the Eliza agent with configurable plugins and services.
+
+- **Options:**
+  - `-c, --configure`: Force reconfiguration of services and AI models
+  - `-char, --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:
 
 ```bash
-elizaos tee phala upgrade \
-  -t phala \
-  -m docker-compose \
-  --app-id your-app-id \
-  -c path/to/docker-compose.yml \
-  --env-file path/to/.env
-```
+# Multiple character files (space-separated)
+elizaos start --character file1.json file2.json
 
-## Directory Structure
+# Comma-separated format
+elizaos start --character "file1.json,file2.json"
 
-The CLI will create the following directory structure:
+# 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
 ```
-.tee-cloud/
-  └── compose-files/     # Generated docker-compose files
-```
 
-## Tips
+If any character files fail to load, ElizaOS will:
+
+- Log errors for the failed characters
+- Continue starting with any successfully loaded characters
+- Fall back to the default Eliza character if no characters loaded successfully
+
+### Testing
+
+#### `elizaos test`
+
+Run tests for Eliza agent plugins and projects.
+
+- **Subcommands:**
+  - `component`: Run component tests (via Vitest)
+  - `e2e`: Run end-to-end runtime tests
+  - `all`: Run both component and e2e tests (default)
+- **Options:**
+  - `-p, --port <port>`: Port to listen on for e2e tests
+  - `-n, --name <n>`: Filter tests by name (matches file names or test suite names)
+  - `--skip-build`: Skip building before running tests
+
+### Trusted Execution Environment (TEE) Management
+
+#### `elizaos tee phala <subcommand>`
+
+Manage TEE deployments with Phala vendor.
+
+- **Subcommands:**
+  - `deploy`: Deploy to TEE cloud
+    - Options: `-t, --type <type>`, `-m, --mode <mode>`, `-n, --name <n>`, `-c, --compose <compose>`, `-e, --env <env...>`, `--env-file <envFile>`, `--debug`
+  - `teepods`: Query the teepods
+  - `images`: Query the images
+    - Options: `--teepod-id <teepodId>`
+  - `upgrade`: Upgrade the TEE CLI
+    - Options: `-m, --mode <mode>`, `--app-id <appId>`, `-e, --env <env...>`, `--env-file <envFile>`, `-c, --compose <compose>`
+  - `build-compose`: Build a docker-compose file for Eliza Agent
+    - Options: `-i, --image <n>`, `-u, --username <n>`, `-t, --tag <tag>`, `-c, --character <path>`, `-e, --env-file <path>`, `-v, --version <version>`
+  - `publish`: Publish Docker image to Docker Hub
+    - Options: `-i, --image <n>`, `-u, --username <n>`, `-t, --tag <tag>`
+
+### Updates
+
+#### `elizaos update`
+
+Update ElizaOS CLI and project dependencies to the latest versions.
+
+- **Options:**
+  - `-c, --check`: Check for available updates without applying them - shows what packages would be updated
+  - `-sb, --skip-build`: Skip building after updating
+  - `--cli`: Update only the global CLI installation (without updating packages)
+  - `--packages`: Update only packages (without updating the CLI)
+
+### Environment Configuration
+
+#### `elizaos env`
+
+Manage environment variables and secrets.
+
+- **Subcommands:**
+  - `list`: List all environment variables
+    - Options: `--system`, `--local`
+  - `edit-local`: Edit local environment variables
+    - Options: `-y, --yes`
+  - `reset`: Reset environment variables and clean up database/cache files
+    - Options: `-y, --yes`
+  - `interactive`: Start interactive environment variable manager
+    - Options: `-y, --yes`
+
+### Publishing
+
+#### `elizaos publish`
+
+Publishes the current project or plugin.
+
+- **Options:**
+  - `--dry-run`: Test run without publishing
+  - `--registry <repo>`: Specify target registry (default: 'elizaOS/registry')
+
+## Development Guide
+
+### Developing Agents
+
+Agents are character definitions for ElizaOS bots.
+
+1. **Create a new agent character**:
+
+   ```bash
+   elizaos create my-assistant --type agent
+   ```
+
+   This creates a JSON file (my-assistant.json) with the character definition.
+
+2. **Start an agent with the character**:
+
+   ```bash
+   elizaos agent start --path my-assistant.json
+   ```
+
+### Developing Plugins
+
+Plugins extend the functionality of ElizaOS agents by providing additional capabilities or integrations.
+
+1. **Create a new plugin**:
+
+   ```bash
+   elizaos create my-plugin --type plugin
+   cd plugin-my-plugin  # Note: CLI automatically adds plugin- prefix if not present
+   ```
+
+2. **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
+   ```
+
+3. **Implement your plugin**:
+
+   Your plugin's main file (src/index.ts) should export a plugin object:
+
+   ```typescript
+   import { type Plugin, type IAgentRuntime } from '@elizaos/core';
+   import { z } from 'zod';
 
-- Use the simulator for local testing before cloud deployment
-- Always test your image locally with `run-local` before publishing
-- Keep your API keys secure and never commit them to version control
-- Use the `--help` flag with any command for detailed usage information
+   // Define config schema for validation
+   const configSchema = z.object({
+     API_KEY: z.string().min(1, 'API key is required'),
+   });
 
-## Troubleshooting
+   // Export the plugin object
+   export const myPlugin: Plugin = {
+     name: 'plugin-my-plugin',
+     description: 'My custom plugin description',
 
-Common issues and solutions:
+     // Config section maps environment variables to plugin settings
+     config: {
+       API_KEY: process.env.MY_PLUGIN_API_KEY,
+     },
 
-1. **Docker Build Fails**
+     // Initialization function
+     async init(config: Record<string, string>) {
+       // Validate config
+       const validatedConfig = await configSchema.parseAsync(config);
 
-   - Ensure Docker daemon is running
-   - Check Dockerfile path is correct
-   - Verify you have necessary permissions
+       // Plugin setup
+       return {
+         // Plugin methods and handlers
+         // ...
+       };
+     },
+   };
 
-2. **Simulator Connection Issues**
+   // Default export
+   export default myPlugin;
+   ```
 
-   - Check if port 8090 is available
-   - Ensure Docker has necessary permissions
+4. **Configure package.json**:
 
-3. **Cloud Deployment Fails**
-   - Verify API key is set correctly
-   - Check if image exists on Docker Hub
-   - Ensure environment variables are properly set
+   Add an `agentConfig` section to describe your plugin parameters:
 
-For more help, use the `--help` flag with any command:
+   ```json
+   "agentConfig": {
+     "pluginType": "elizaos:plugin:1.0.0",
+     "pluginParameters": {
+       "API_KEY": {
+         "type": "string",
+         "description": "API key for the service"
+       }
+     }
+   }
+   ```
+
+5. **Test your plugin**:
+
+   ```bash
+   bun run test
+   # Or with the CLI directly:
+   elizaos test --plugin
+   ```
+
+6. **Publish your plugin**:
+
+   ```bash
+   # Test publishing process
+   elizaos plugins publish --test
+
+   # Publish to registry
+   elizaos plugins publish
+
+   # Or publish to npm
+   elizaos plugins publish --npm
+   ```
+
+### Developing Projects (Agents)
+
+Projects contain agent configurations and code for building agent-based applications.
+
+1. **Create a new project**:
+
+   ```bash
+   elizaos create my-agent-project
+   cd my-agent-project
+   ```
+
+2. **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
+   ```
+
+3. **Configure your agent**:
+
+   The main character definition is in src/index.ts:
+
+   ```typescript
+   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
+     ],
+   };
+   ```
+
+4. **Add plugins to your project**:
+
+   ```bash
+   elizaos project add-plugin @elizaos/plugin-openai
+   ```
+
+5. **Run your project in development mode**:
+
+   ```bash
+   bun run dev
+   # Or with the CLI directly:
+   elizaos dev
+   ```
+
+6. **Build and start your project**:
+
+   ```bash
+   bun run build
+   bun run start
+   # Or with the CLI directly:
+   elizaos start
+   ```
+
+7. **Test your project**:
+   ```bash
+   bun run test
+   # Or with the CLI directly:
+   elizaos test
+   ```
+
+## Contributing
+
+For contributing to the ElizaOS CLI, please clone the monorepo using:
 
 ```bash
-elizaos tee phala --help
-elizaos tee phala <command> --help
+elizaos setup-monorepo
 ```