@elizaos/cli 1.0.0-beta.26 → 1.0.0-beta.28

package/README.md

@@ -1,203 +1,353 @@
-# 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
+```
+
+### 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
+### Project Creation and Management
 
-- 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
+#### `elizaos create [name]`
 
-## Commands
+Initializes a new ElizaOS project or plugin.
 
-### Building Your Image
+- **`[name]`**: (Optional) The name for the new project or plugin directory
+- **Options:**
+  - `-d, --dir <dir>`: Specify the directory for creation (default: current directory)
+  - `-y, --yes`: Skip confirmation prompts
+  - `-t, --type <type>`: Specify 'project' or 'plugin' to create
 
-Build your Docker image locally:
+#### `elizaos project ...`
 
-```bash
-elizaos tee phala build \
-  -i your-image-name \
-  -u your-dockerhub-username \
-  -f path/to/Dockerfile \
-  -t tag-name
-```
+Manages project-specific configurations and plugins.
 
-### Running the TEE Simulator
+- **`list-plugins`**: Lists available plugins
+  - `-t, --type <type>`: Filter by plugin type (adapter, client, plugin)
+- **`add-plugin <plugin>`**: Adds a plugin to the current project
+  - `--no-env-prompt`: Skip prompting for environment variables
+- **`remove-plugin <plugin>`**: Removes a plugin from the current project
 
-Start the local TEE simulator for testing:
+#### `elizaos setup-monorepo`
 
-```bash
-elizaos tee phala simulator
-```
+Clones the main `elizaOS/eliza` monorepo locally.
 
-This will start the simulator on http://localhost:8090.
+- **Options:**
+  - `-b, --branch <branch>`: Specify branch (default: 'v2-develop')
+  - `-d, --dir <directory>`: Specify destination directory (default: './eliza')
 
-### Local Development
+### Plugin Development
 
-You can develop your agent locally in two ways:
+#### `elizaos plugin ...`
 
-1. Build the docker-compose file separately:
+Manages plugin development workflows.
 
-```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
-```
+- **`publish`**: Publishes the plugin to a registry
+  - `-r, --registry <registry>`: Target registry (default: 'elizaOS/registry')
+  - `-n, --npm`: Publish to npm instead of GitHub registry
+  - `-t, --test`: Run in test mode without making changes
+  - `-p, --platform <platform>`: Specify platform compatibility
 
-2. Run an existing compose file:
+### Agent Management
 
-```bash
-elizaos tee phala run-local \
-  -c path/to/docker-compose.yml \
-  -e path/to/.env
-```
+#### `elizaos agent ...`
 
-This separation allows you to:
+Interacts with the ElizaOS Agent Runtime API.
 
-- 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
+- **`list`** (alias: `ls`): Lists all agents
+  - `-j, --json`: Output in JSON format
+- **`get`** (alias: `g`): Gets details about a specific agent
+  - `-n, --name <name>`: Agent ID, name, or index
+  - `-j, --json`: Output in JSON format
+  - `-o, --output <file>`: Save configuration to file
+- **`start`** (alias: `s`): Starts a new agent instance
+  - `-n, --name <name>`: Use pre-defined character name
+  - `-j, --json <json>`: Provide character definition as JSON
+  - `-p, --path <path>`: Load definition from local file
+  - `-r, --remote <url>`: Load definition from remote URL
+- **`stop`** (alias: `st`): Stops a specific agent
+  - `-n, --name <name>`: Agent to stop
+- **`restart`** (alias: `r`): Restarts a specific agent
+  - `-n, --name <name>`: Agent to restart
 
-The CLI will store generated compose files in:
+### Server Management
 
-```
-.tee-cloud/
-  └── compose-files/     # Generated docker-compose files
-      └── your-character-tee-compose.yaml
-```
+#### `elizaos start`
 
-### Publishing Your Image
+Starts the main ElizaOS server process.
 
-Push your built image to Docker Hub:
+- **Options:**
+  - `--configure`: Force reconfiguration
+  - `-p, --port <port>`: Specify server port (default: 3000)
+  - `-c, --character <path>`: Start a single agent using specified file
+  - `-d, --data-dir <path>`: Specify data directory for persistence
 
-```bash
-elizaos tee phala publish \
-  -i your-image-name \
-  -u your-dockerhub-username \
-  -t tag-name
-```
+#### `elizaos stop`
 
-### List Available Tags
+Stops all running ElizaOS processes initiated by the CLI.
 
-View all tags for your image on Docker Hub:
+#### `elizaos dev`
 
-```bash
-elizaos tee phala list-tags \
-  -i your-image-name \
-  -u your-dockerhub-username
-```
+Starts the ElizaOS server in development mode with hot reloading.
 
-### Cloud Deployment
+- **Options:**
+  - `-p, --port <port>`: Specify development server port
 
-First, set your Phala Cloud API key:
+### Updates and Maintenance
 
-```bash
-elizaos tee phala set-apikey your-api-key
-```
+#### `elizaos update`
 
-Deploy to Phala Cloud:
+Updates all `@elizaos/*` dependencies in the current project.
 
-```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
-```
+- **Options:**
+  - `--check`: Check for updates without installing
+  - `--skip-build`: Skip automatic build after updating
 
-### Managing Cloud Deployments
+#### `elizaos update-cli`
 
-List your active agents (CVMs):
+Updates the globally installed CLI package to the latest version.
 
-```bash
-elizaos tee phala list-cvms
-```
+### Testing
 
-List your TEE pods:
+#### `elizaos test`
 
-```bash
-elizaos tee phala teepods
-```
+Runs tests for the current project or plugin.
 
-List images in a specific TEE pod:
+- **Options:**
+  - `-p, --port <port>`: Specify test server port
+  - `--plugin`: Force testing as a plugin
+  - `--skip-plugins`: Skip plugin-related tests
+  - `--skip-project-tests`: Skip project-specific tests
+  - `--skip-build`: Skip build step before testing
 
-```bash
-elizaos tee phala images --teepod-id your-teepod-id
-```
+### Environment Variables
 
-Upgrade an existing deployment:
+#### `elizaos env ...`
 
-```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
-```
+Manages environment variables in global and local scopes.
 
-## Directory Structure
+- **`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
 
-The CLI will create the following directory structure:
+### Publishing
 
-```
-.tee-cloud/
-  └── compose-files/     # Generated docker-compose files
-```
+#### `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
+
+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
+   ```
+
+2. **Structure of a plugin**:
 
-## Tips
+   ```
+   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
+   ```
 
-- 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
+3. **Implement your plugin**:
 
-## Troubleshooting
+   Your plugin's main file (src/index.ts) should export a plugin object:
 
-Common issues and solutions:
+   ```typescript
+   import { type Plugin, type IAgentRuntime } from '@elizaos/core';
+   import { z } from 'zod';
 
-1. **Docker Build Fails**
+   // Define config schema for validation
+   const configSchema = z.object({
+     API_KEY: z.string().min(1, 'API key is required'),
+   });
 
-   - Ensure Docker daemon is running
-   - Check Dockerfile path is correct
-   - Verify you have necessary permissions
+   // Export the plugin object
+   export const myPlugin: Plugin = {
+     name: 'plugin-my-plugin',
+     description: 'My custom plugin description',
 
-2. **Simulator Connection Issues**
+     // Config section maps environment variables to plugin settings
+     config: {
+       API_KEY: process.env.MY_PLUGIN_API_KEY,
+     },
 
-   - Check if port 8090 is available
-   - Ensure Docker has necessary permissions
+     // Initialization function
+     async init(config: Record<string, string>) {
+       // Validate config
+       const validatedConfig = await configSchema.parseAsync(config);
 
-3. **Cloud Deployment Fails**
-   - Verify API key is set correctly
-   - Check if image exists on Docker Hub
-   - Ensure environment variables are properly set
+       // Plugin setup
+       return {
+         // Plugin methods and handlers
+         // ...
+       };
+     },
+   };
 
-For more help, use the `--help` flag with any command:
+   // 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
+   │   └── plugin.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
 ```

package/dist/assets/{index-DLvpF7l_.js → index-BS4yKZxf.js}

@@ -1,4 +1,4 @@
-import { r as require$$2, a as requireString_decoder, c as commonjsGlobal, b as requireEvents, g as getDefaultExportFromCjs } from "./index-B5fPWkuO.js";
+import { r as require$$2, a as requireString_decoder, c as commonjsGlobal, b as requireEvents, g as getDefaultExportFromCjs } from "./index-Cf6FmcGh.js";
 function _mergeNamespaces(n, m) {
   for (var i = 0; i < m.length; i++) {
     const e = m[i];
@@ -4242,4 +4242,4 @@ const index$1 = /* @__PURE__ */ _mergeNamespaces({
 export {
   index$1 as i
 };
-//# sourceMappingURL=index-DLvpF7l_.js.map
+//# sourceMappingURL=index-BS4yKZxf.js.map