@elizaos/cli 1.0.0-beta.5 → 1.0.0-beta.51

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,403 @@
-# 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 or plugin.
 
-Build your Docker image locally:
+- **Arguments:**
+  - `[name]`: Name for the project or plugin (optional)
+- **Options:**
+  - `-d, --dir <dir>`: Installation directory (default: `.`)
+  - `-y, --yes`: Skip confirmation (default: `false`)
+  - `-t, --type <type>`: Type of template to use (project or plugin)
 
-```bash
-elizaos tee phala build \
-  -i your-image-name \
-  -u your-dockerhub-username \
-  -f path/to/Dockerfile \
-  -t tag-name
-```
+### Development
 
-### Running the TEE Simulator
+#### `elizaos dev`
 
-Start the local TEE simulator for testing:
+Start the project or plugin in development mode and rebuild on file changes.
 
-```bash
-elizaos tee phala simulator
-```
+- **Options:**
+  - `-c, --configure`: Reconfigure services and AI models
+  - `-char, --character <character>`: Path or URL to character file
+  - `-b, --build`: Build the project before starting
 
-This will start the simulator on http://localhost:8090.
+### Environment Management
 
-### Local Development
+#### `elizaos env <subcommand>`
 
-You can develop your agent locally in two ways:
+Manage environment variables and secrets.
 
-1. Build the docker-compose file separately:
+- **Subcommands:**
+  - `list`: List all environment variables
+    - Options: `--global`, `--local`
+  - `edit-global`: Edit global environment variables
+    - Options: `-y, --yes`
+  - `edit-local`: Edit local environment variables
+    - Options: `-y, --yes`
+  - `reset`: Reset all environment variables
+    - Options: `-y, --yes`
+  - `set-path <path>`: Set a custom path for the global environment file
+    - Options: `-y, --yes`
+  - `interactive`: Interactive environment variable management
+    - Options: `-y, --yes`
 
-```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
-```
+### Monorepo Setup
 
-2. Run an existing compose file:
+#### `elizaos setup-monorepo`
 
-```bash
-elizaos tee phala run-local \
-  -c path/to/docker-compose.yml \
-  -e path/to/.env
-```
+Clone ElizaOS monorepo from a specific branch (defaults to v2-develop).
 
-This separation allows you to:
+- **Options:**
+  - `-b, --branch <branch>`: Branch to install (default: `v2-develop`)
+  - `-d, --dir <directory>`: Destination directory (default: `./eliza`)
 
-- 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
+### Plugin Management
 
-The CLI will store generated compose files in:
+#### `elizaos plugin <subcommand>`
 
-```
-.tee-cloud/
-  └── compose-files/     # Generated docker-compose files
-      └── your-character-tee-compose.yaml
-```
+Manage an ElizaOS plugin.
 
-### Publishing Your Image
+- **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)
 
-Push your built image to Docker Hub:
+### Agent Management
 
-```bash
-elizaos tee phala publish \
-  -i your-image-name \
-  -u your-dockerhub-username \
-  -t tag-name
-```
+#### `elizaos agent <subcommand>`
 
-### List Available Tags
+Manage ElizaOS agents.
 
-View all tags for your image on Docker Hub:
+- **Subcommands:**
+  - `list` (alias: `ls`): List available agents
+    - Options: `-j, --json` (output as JSON)
+  - `get` (alias: `g`): Get agent details
+    - Options:
+      - `-n, --name <name>` (required): Agent id, name, or index number from list
+      - `-j, --json`: Output as JSON
+      - `-o, --output <file>`: Output to file (default: {name}.json)
+  - `start` (alias: `s`): Start an agent
+    - Options:
+      - `-n, --name <n>`: Character name to start the agent with
+      - `-j, --json <json>`: Character JSON string
+      - `--path <path>`: Local path to character JSON file
+      - `--remote-character <url>`: Remote URL to character JSON file
+  - `stop` (alias: `st`): Stop an agent
+    - Options:
+      - `-n, --name <name>` (required): Agent id, name, or index number from list
+  - `remove` (alias: `rm`): Remove an agent
+    - Options:
+      - `-n, --name <name>` (required): Agent id, name, or index number from list
+  - `set`: Update agent configuration
+    - Options:
+      - `-n, --name <name>` (required): 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
 
-```bash
-elizaos tee phala list-tags \
-  -i your-image-name \
-  -u your-dockerhub-username
-```
+### Publishing
 
-### Cloud Deployment
+#### `elizaos publish`
 
-First, set your Phala Cloud API key:
+Publish a plugin or project to the registry, GitHub, or npm.
 
-```bash
-elizaos tee phala set-apikey your-api-key
-```
+- **Options:**
+  - `-t, --test`: Run publish tests without actually publishing
+  - `-n, --npm`: Publish to npm
+  - `-s, --skip-registry`: Skip publishing to the registry
 
-Deploy to Phala Cloud:
+### Agent/Server Management
 
-```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
-```
+#### `elizaos start`
 
-### Managing Cloud Deployments
+Start the Eliza agent with configurable plugins and services.
 
-List your active agents (CVMs):
+- **Options:**
+  - `-c, --configure`: Reconfigure services and AI models
+  - `-char, --character <character>`: Path or URL to character file
+  - `-b, --build`: Build the project before starting
+  - `-chars, --characters <paths>`: Multiple character configuration files
 
-```bash
-elizaos tee phala list-cvms
-```
+### Testing
 
-List your TEE pods:
+#### `elizaos test`
 
-```bash
-elizaos tee phala teepods
-```
+Run tests for Eliza agent plugins.
 
-List images in a specific TEE pod:
+- **Options:**
+  - `-p, --port <port>`: Port to listen on
+  - `-pl, --plugin <name>`: Name of plugin to test
+  - `-sp, --skip-plugins`: Skip plugin tests
+  - `-spt, --skip-project-tests`: Skip project tests
+  - `-sb, --skip-build`: Skip building before running tests
 
-```bash
-elizaos tee phala images --teepod-id your-teepod-id
-```
+### Trusted Execution Environment (TEE) Management
 
-Upgrade an existing deployment:
+#### `elizaos tee phala <subcommand>`
 
-```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
-```
+Manage TEE deployments with Phala vendor.
 
-## Directory Structure
+- **Subcommands:**
+  - `deploy`: Deploy to TEE cloud
+    - Options: `-t, --type <type>`, `-m, --mode <mode>`, `-n, --name <name>`, `-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 <name>`, `-u, --username <name>`, `-t, --tag <tag>`, `-c, --character <path>`, `-e, --env-file <path>`, `-v, --version <version>`
+  - `publish`: Publish Docker image to Docker Hub
+    - Options: `-i, --image <name>`, `-u, --username <name>`, `-t, --tag <tag>`
 
-The CLI will create the following directory structure:
+### Updates
 
-```
-.tee-cloud/
-  └── compose-files/     # Generated docker-compose files
-```
+#### `elizaos update`
+
+Update ElizaOS packages to the latest versions.
+
+- **Options:**
+  - `-c, --check`: Check for available updates without applying them
+  - `-sb, --skip-build`: Skip building after updating
+
+Manages environment variables in global and local scopes.
+
+- **`list`**: Shows variables from both scopes
+- **`edit`**: Interactively edit variables
+- **`set <key> <value>`**: Sets/updates a variable
+  - `--global` or `--local`: Specify scope
+- **`unset <key>`**: Removes a variable
+  - `--global` or `--local`: Specify scope
+- **`reset`**: Clears all variables (requires confirmation)
+  - `--global` or `--local`: Specify scope
+- **`set-path <path>`**: Sets custom path for global environment file
+
+### 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 Plugins
 
-## Tips
+Plugins extend the functionality of ElizaOS agents by providing additional capabilities or integrations.
 
-- 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
+1. **Create a new plugin**:
 
-## Troubleshooting
+   ```bash
+   elizaos create my-plugin --type plugin
+   cd plugin-my-plugin
+   ```
 
-Common issues and solutions:
+2. **Structure of a plugin**:
 
-1. **Docker Build Fails**
+   ```
+   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
+   ```
 
-   - Ensure Docker daemon is running
-   - Check Dockerfile path is correct
-   - Verify you have necessary permissions
+3. **Implement your plugin**:
 
-2. **Simulator Connection Issues**
+   Your plugin's main file (src/index.ts) should export a plugin object:
 
-   - Check if port 8090 is available
-   - Ensure Docker has necessary permissions
+   ```typescript
+   import { type Plugin, type IAgentRuntime } from '@elizaos/core';
+   import { z } from 'zod';
 
-3. **Cloud Deployment Fails**
-   - Verify API key is set correctly
-   - Check if image exists on Docker Hub
-   - Ensure environment variables are properly set
+   // Define config schema for validation
+   const configSchema = z.object({
+     API_KEY: z.string().min(1, 'API key is required'),
+   });
 
-For more help, use the `--help` flag with any command:
+   // 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;
+   ```
+
+4. **Configure package.json**:
+
+   Add an `agentConfig` section to describe your plugin parameters:
+
+   ```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 plugin publish --test
+
+   # Publish to registry
+   elizaos plugin publish
+
+   # Or publish to npm
+   elizaos plugin 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
 ```