npm package: @megabrainapp/agent-cli
Description: CLI tool for developing MegaBrain agents
Author: MegaBrain Team
Latest version: 1.0.11

# @megabrain/agent-cli

The official CLI tool for developing MegaBrain agents. Scaffold, develop, test, and deploy AI agents with ease.

## Features

🏗️ **Project Scaffolding** - Create agent projects from templates  
🔥 **Hot Reload Development** - Real-time development server with auto-reload  
🧪 **Built-in Testing** - Comprehensive testing framework for agents  
📦 **Build System** - Production-ready builds with TypeScript  
🚀 **Easy Deployment** - One-command deployment to MegaBrain platform  
✅ **Code Validation** - Lint and validate agent code and manifests  

## Installation

```bash
# Install globally
npm install -g @megabrain/agent-cli

# Or use with npx (recommended)
npx @megabrain/agent-cli --help
```

## Quick Start

```bash
# Initialize a new workspace
megabrain-agent init my-agents-workspace
cd my-agents-workspace
yarn install

# Create your first agent
megabrain-agent create my-first-agent
cd agents/my-first-agent

# Start development server
megabrain-agent dev

# Test your agent
megabrain-agent test "Hello, world!"

# Build for production
megabrain-agent build

# Deploy to platform
megabrain-agent deploy --token YOUR_TOKEN
```

## Commands

### `init [name]`

Initialize a new agent workspace.

```bash
megabrain-agent init my-workspace
megabrain-agent init --template advanced-workspace
```

**Options:**
- `-t, --template <template>` - Workspace template (basic-workspace, advanced-workspace)
- `-d, --directory <dir>` - Target directory

### `create <name>`

Create a new agent from a template.

```bash
megabrain-agent create my-agent
megabrain-agent create my-rag-agent --template rag-agent
```

**Options:**
- `-t, --template <template>` - Agent template (basic, rag-agent, data-agent)
- `-d, --directory <dir>` - Target directory
- `--no-install` - Skip dependency installation

### `dev`

Start the development server with hot reload.

```bash
megabrain-agent dev
megabrain-agent dev --port 3002 --host 0.0.0.0
```

**Options:**
- `-p, --port <port>` - Port to run on (default: 3001)
- `-h, --host <host>` - Host to bind to (default: localhost)
- `--no-open` - Don't open browser automatically
- `--mock-services` - Use mock services (default: true)

**Features:**
- 🔄 Hot reload on file changes
- 🌐 Web-based testing interface
- 📊 Real-time agent testing
- 🔗 WebSocket integration for live updates

### `build`

Build agents for production.

```bash
megabrain-agent build
megabrain-agent build --output dist --minify --bundle
```

**Options:**
- `-o, --output <dir>` - Output directory (default: dist)
- `--minify` - Minify output files
- `--bundle` - Create single bundle file

### `test [input]`

Test agents with various inputs.

```bash
# Interactive test
megabrain-agent test "Hello, world!"

# Test with file
megabrain-agent test --file test-cases.json

# Run built-in test suite
megabrain-agent test

# Watch mode
megabrain-agent test --watch
```

**Options:**
- `-f, --file <file>` - Test file with multiple inputs
- `-w, --watch` - Watch for changes and re-run tests
- `--coverage` - Generate coverage report

### `validate`

Validate agent code and manifests.

```bash
megabrain-agent validate
megabrain-agent validate --fix --strict
```

**Options:**
- `--fix` - Automatically fix issues where possible
- `--strict` - Use strict validation rules

### `deploy`

Deploy agents to the MegaBrain platform.

```bash
megabrain-agent deploy --token YOUR_TOKEN
megabrain-agent deploy --env staging --dry-run
```

**Options:**
- `-t, --token <token>` - Authentication token
- `-e, --env <environment>` - Target environment (default: production)
- `--dry-run` - Simulate deployment without uploading

## Templates

### Agent Templates

- **basic-agent** - Simple agent with basic functionality
- **rag-agent** - RAG (Retrieval Augmented Generation) agent with document processing
- **data-agent** - Data analysis agent with advanced capabilities

### Workspace Templates  

- **basic-workspace** - Simple workspace for individual developers
- **advanced-workspace** - Advanced workspace with examples and additional tooling

## Development Server

The development server provides a comprehensive environment for testing agents:

### Web Interface

Visit `http://localhost:3001` when running `megabrain-agent dev`:

- 📝 **Interactive Testing** - Test agents with custom inputs
- 📊 **Real-time Results** - See agent responses instantly  
- 🔄 **Hot Reload** - Automatic reloading when code changes
- 📈 **Performance Metrics** - Monitor response times and errors
- 🔍 **Debug Console** - View logs and debugging information

### API Endpoints

- `GET /api/agents` - List all available agents
- `POST /api/agents/:name/test` - Test specific agent
- `GET /api/agents/:name/info` - Get agent information
- `GET /api/health` - Health check

## Testing Framework

### Test File Format

Create a `tests.json` file for comprehensive testing:

```json
[
  {
    "name": "Basic greeting",
    "input": "Hello!",
    "expectedOutput": "Hello! I'm ready to help you.",
    "context": {}
  },
  {
    "name": "File processing",
    "input": "Analyze file:data.csv",
    "context": {
      "files": ["data.csv"]
    }
  }
]
```

### Coverage Reports

Generate test coverage reports:

```bash
megabrain-agent test --coverage
```

## Configuration

### Global Configuration

Configure CLI defaults in `~/.megabrain/config.json`:

```json
{
  "defaultTemplate": "basic-agent",
  "defaultPort": 3001,
  "defaultEnvironment": "production",
  "token": "your-default-token"
}
```

### Project Configuration

Configure workspace settings in `megabrain.workspace.json`:

```json
{
  "name": "my-workspace",
  "version": "1.0.0",
  "sdk": "1.0.0",
  "agents": ["agent1", "agent2"],
  "settings": {
    "defaultTemplate": "basic",
    "buildOutput": "dist",
    "testFramework": "jest"
  }
}
```

## Environment Variables

- `MEGABRAIN_TOKEN` - Default authentication token
- `MEGABRAIN_ENV` - Default deployment environment
- `MEGABRAIN_API_URL` - Custom API endpoint

## Best Practices

### Project Structure

```
my-workspace/
├── agents/                 # Individual agents
│   ├── agent1/
│   │   ├── src/
│   │   ├── package.json
│   │   └── agent.json
│   └── agent2/
├── shared/                 # Shared utilities
├── tests/                  # Integration tests
├── package.json
└── megabrain.workspace.json
```

### Agent Development

1. **Start with Templates** - Use provided templates as starting points
2. **Incremental Development** - Use dev server for rapid iteration
3. **Test Early and Often** - Write tests as you develop
4. **Validate Regularly** - Run validation before deployment
5. **Use TypeScript** - Leverage full type safety

### Performance Tips

- **Hot Reload** - Keep dev server running during development
- **Mock Services** - Use mock services for faster testing
- **Parallel Builds** - Build multiple agents simultaneously
- **Bundle Optimization** - Use `--minify` and `--bundle` for production

## Troubleshooting

### Common Issues

**"No agent project found"**
- Make sure you're in an agent directory or workspace
- Check that `package.json` or `agent.json` exists

**"Template not found"**
- Verify template name with `megabrain-agent create --help`
- Check template availability

**"Build failed"**
- Ensure TypeScript compilation succeeds
- Check for syntax errors and type issues

**"Development server won't start"**
- Check if port is already in use
- Verify agent manifests are valid

### Getting Help

- Run any command with `--help` for detailed usage
- Enable verbose logging with `--verbose`
- Check the [documentation](https://docs.megabrain.ai)
- Visit our [community forum](https://community.megabrain.ai)

## Contributing

We welcome contributions! Please see our [contributing guide](CONTRIBUTING.md).

## License

MIT License - see LICENSE file for details.

---

**Happy agent building! 🤖✨**