CLI Tools

Powerful command-line tools for automating your agent development workflow

Table of Contents

The Agentopia Command Line Interface (CLI) provides a comprehensive set of tools for creating, testing, deploying, and managing AI agents. Whether you're building a simple chatbot or a complex multi-agent system, our CLI streamlines your development workflow.

Installation

The Agentopia CLI can be installed using npm, yarn, or directly from source. Choose the method that works best for your environment.

Using npm (Recommended)

npm install -g @agentopia/cli

Using yarn

yarn global add @agentopia/cli

From Source

git clone https://github.com/agentopia/cli.git
cd cli
npm install
npm link

After installation, verify that the CLI is properly installed by running:

agentopia --version

Core Commands

The Agentopia CLI provides a rich set of commands to help you manage your agent development lifecycle. Here are the most commonly used commands:

Create

Initialize a new agent project with the necessary files and structure.

agentopia create my-agent

Use the --template flag to specify a template.

Deploy

Deploy your agent to the Agentopia platform or other environments.

agentopia deploy

Use --env to specify the deployment environment.

Test

Run automated tests on your agent to validate its behavior.

agentopia test

Use --watch for continuous testing during development.

Monitor

Track your agent's performance and usage metrics.

agentopia monitor

Use --dashboard to open the web dashboard.

Command Structure

Most Agentopia CLI commands follow this general structure:

agentopia [command] [subcommand] [options]

Getting Help

You can get detailed help for any command by using the --help flag:

agentopia --help
agentopia create --help

Configuration

The Agentopia CLI can be configured at different levels to customize your development experience. Configuration options can be set globally, per project, or per command execution.

Configuration Files

Agentopia uses configuration files to store settings. The main configuration files are:

Global Config

Located at ~/.agentopia/config.json

Contains user-level settings like API keys, default templates, and global preferences.

Project Config

Located at ./agentopia.json in your project directory

Contains project-specific settings like deployment targets, testing parameters, and dependencies.

Sample Configuration

Here's an example of a project configuration file:

agentopia.json

{
  "name": "my-assistant-agent",
  "version": "1.0.0",
  "description": "An intelligent assistant agent",
  "type": "conversational",
  "deployment": {
    "target": "agentopia-cloud",
    "region": "us-west",
    "resources": {
      "memory": "standard",
      "compute": "medium"
    }
  },
  "testing": {
    "scenarios": "./tests/scenarios",
    "threshold": 0.85
  },
  "dependencies": {
    "@agentopia/core": "^2.0.0",
    "@agentopia/tools": "^1.5.0"
  }
}

Setting Configuration Values

You can set configuration values using the config command:

agentopia config set api.key YOUR_API_KEY
agentopia config set --global default.template basic-agent

To view current configuration:

agentopia config list

Common Workflows

Here are some common development workflows using the Agentopia CLI:

Creating a New Agent

  1. Create a new agent project using a template: 
    agentopia create my-agent --template conversational
  2. Navigate to the project directory: 
    cd my-agent
  3. Install dependencies: 
    npm install
  4. Start the development server: 
    agentopia dev

Testing and Deployment

  1. Run tests to ensure your agent behaves correctly: 
    agentopia test
  2. Run performance benchmarks: 
    agentopia benchmark
  3. Deploy to staging environment: 
    agentopia deploy --env staging
  4. Promote to production after verification: 
    agentopia promote staging production

Monitoring and Maintenance

  1. View agent performance metrics: 
    agentopia monitor --dashboard
  2. Check agent logs: 
    agentopia logs --env production --tail
  3. Update agent dependencies: 
    agentopia update
  4. Rollback to previous version if needed: 
    agentopia rollback production

Plugins & Extensions

The Agentopia CLI supports a plugin system that allows you to extend its functionality. Plugins can add new commands, enhance existing ones, or integrate with third-party services.

Installing Plugins

You can install plugins using the plugin command:

agentopia plugin install @agentopia/plugin-aws

Popular Plugins

  • @agentopia/plugin-aws - AWS integration for deployment
  • @agentopia/plugin-azure - Azure integration
  • @agentopia/plugin-analytics - Enhanced analytics
  • @agentopia/plugin-llm - Additional LLM providers
  • @agentopia/plugin-vector-db - Vector database integrations

Creating Your Own Plugins

You can create custom plugins to extend the CLI functionality:

  1. Create a new plugin project: 
    agentopia plugin:create my-plugin
  2. Implement your plugin logic
  3. Publish to npm or use locally

Managing Plugins

View installed plugins:

agentopia plugin list

Update plugins:

agentopia plugin update

Remove a plugin:

agentopia plugin uninstall @agentopia/plugin-aws

Troubleshooting

If you encounter issues with the Agentopia CLI, here are some common problems and their solutions:

Installation Issues

Problem: Permission errors during installation

Solution: Try installing with administrator privileges or use the --user flag: 

npm install -g @agentopia/cli --user

Problem: Command not found after installation

Solution: Ensure the npm global bin directory is in your PATH, or try:

npm link @agentopia/cli

Deployment Issues

Problem: Authentication failures

Solution: Verify your API keys and credentials:

agentopia auth:verify

Problem: Deployment timeouts

Solution: Check your network connection and try increasing the timeout:

agentopia deploy --timeout 120

Debug Mode

For detailed debugging information, run any command with the --debug flag:

agentopia deploy --debug

Generate a diagnostic report:

agentopia doctor

This will analyze your environment and configuration, and suggest fixes for common issues.

Getting Help

If you're still experiencing issues, you can: