@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

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

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

Quick Start

# 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.

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.

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.

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.

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.

# 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.

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.

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:

[
  {
    "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:

megabrain-agent test --coverage

Configuration

Global Configuration

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

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

Project Configuration

Configure workspace settings in megabrain.workspace.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
• Visit our community forum

Contributing

We welcome contributions! Please see our contributing guide.

License

MIT License - see LICENSE file for details.

Happy agent building! 🤖✨