AgentHive CLI

Command Line Interface for AgentHive - Control your AI agent swarm from the terminal.

Architecture

The CLI communicates with AgentHive through the authenticated GraphQL proxy:

CLI → User API (GraphQL) → System API
      Port 4000            Port 4001
      (authenticated)      (internal)

All CLI commands use GraphQL queries that proxy to the System API, ensuring secure authenticated access.

Installation

Install globally via npm:

npm install -g agenthive-cli

Or run directly from the monorepo:

cd packages/cli
npx tsx src/index.ts <command>

Authentication

The CLI requires authentication before most operations:

# Login to get JWT token
hive auth login

# Token is stored locally and sent with all requests
# Tokens expire and can be refreshed automatically

Quick Start

Use the hive command to interact with your AI agent swarm:

# Get help with any task
hive ask "Help me optimize a Python function for large datasets"

# Check system status
hive status

# View examples
hive examples

Commands

hive ask <prompt>

Send requests to the AI agent swarm for intelligent processing and routing.

Basic Usage:

hive ask "Review this React component for security issues"
hive ask "Design a REST API for user management" 
hive ask "Debug this performance bottleneck in my database queries"

Advanced Options:

# Use performance-optimized routing
hive ask "Complex algorithm optimization" --strategy performance

# Set request priority
hive ask "Urgent: Fix production error" --priority high

# Custom user and session identifiers
hive ask "Help with deployment" --user-id dev-team --session-id sprint-42

hive status

Check the health and availability of AgentHive services.

hive status

Shows:

• System operational status
• API endpoints status
• Service availability
• Provider information

hive examples

Display usage examples and helpful tips.

hive examples

Configuration

Routing Strategies

Control how your requests are routed to agents:

• balanced (default) - Optimal balance of speed and capability
• performance - Maximum capability for complex tasks
• speed - Fastest response for simple tasks

hive ask "Your request" --strategy performance

Priority Levels

Set request priority for better resource allocation:

• normal (default) - Standard processing
• high - Prioritized processing
• low - Background processing

hive ask "Your request" --priority high

Advanced Usage

Session Management

Use session IDs to maintain context across multiple requests:

hive ask "Create a user authentication system" --session-id auth-project
hive ask "Add password reset functionality" --session-id auth-project
hive ask "Implement 2FA support" --session-id auth-project

User Identification

Specify user identifiers for multi-user environments:

hive ask "Team-specific request" --user-id team-frontend

System Requirements

• Node.js: Version 16 or higher
• npm: Version 7 or higher
• AgentHive Services: Running on ports 3000, 4000, 4001

Architecture

The CLI connects exclusively through the User API's authenticated GraphQL endpoint:

• User API (port 4000) - Authenticated GraphQL endpoint
  • Proxies all System API calls
  • Handles JWT authentication
  • Role-based access control

GraphQL Queries Used

The CLI uses these proxy queries to access System API data:

# List agents (proxied from System API)
systemAgents(filter: $filter) { id name description category ... }

# Get single agent
systemAgent(id: $id) { id name description capabilities ... }

# List contexts
systemContexts(filter: $filter) { id title content type ... }

# Search memories
searchMemories(input: $input) { memory { id agentId ... } similarity }

These queries are defined in the User API schema and proxy to http://localhost:4001/api/*.

Troubleshooting

Connection Issues

If you encounter connection errors:

1. Check service status:

   hive status

2. Verify services are running:

   • Web interface: http://localhost:3000
   • User API: http://localhost:4000/graphql
   • System API: http://localhost:4001

3. Check network connectivity:

   curl http://localhost:4001/api/status

Command Not Found

If hive command is not recognized:

1. Reinstall globally:

   npm uninstall -g agenthive-cli
   npm install -g agenthive-cli

2. Check npm global path:

   npm config get prefix

3. Add to PATH if necessary:

   export PATH=$PATH:$(npm config get prefix)/bin

License

This project is licensed under the MIT License.