OpenHive CLI

The Official Command-Line Interface for the OpenHive Platform

Build, manage, and deploy A2A-compliant AI agents with ease.

🌟 Features

• 🛠️ Source Scaffolding: Interactively create or add A2A-compliant agents to your project.
• 🚀 Local Development: Start and test your agents locally with a unified command.
• 💬 Interactive Chat: Built-in terminal chat interface to interact with your agents.
• 📦 Agent Publishing: Bundle and publish your agent's source code to the OpenHive Platform.
• ☁️ Automatic Deployment: Deploy your agents to serverless cloud infrastructure.
• 🔑 Platform Authentication: Securely log in to OpenHive Platform.
• ⚙️ Configuration Control: Manage CLI settings and configuration profiles.

🚀 Quick Start

Installation

# Install globally with npm
npm install -g @open-hive/cli

# Or with yarn
yarn global add @open-hive/cli

# Verify installation
hive --version

Option 1: Create a New Agent (Standalone)

Ideal for creating a brand new agent project from scratch.

# Create a new agent interactively
hive create my-agent

# The CLI will prompt you to select a runtime (Node.js or Python) and a template.

# Navigate to your agent
cd my-agent

# Install dependencies
npm install  # or: pip install -r requirements.txt

# Start your agent locally
hive start

Option 2: Add Agents to an Existing Project

Ideal for integrating agents into an existing application ("The Shadcn for Agents" flow).

# 1. Initialize OpenHive in your project root
hive init

# 2. Add an agent from the registry
hive add news-summarizer

# This scaffolds the agent code directly into your project (e.g., src/agents/news-summarizer).
# You fully own the code!

# 3. Interact with the agent
hive call news-summarizer

📚 Commands

Project & Agent Management

| Command | Description | | ------- | ----------- | | hive init | Initialize a new OpenHive project configuration (hive.json). | | hive create <name> | Scaffolds a new, standalone agent project from a template. | | hive add <name> | Adds an agent's source code to your existing project. | | hive start | Starts the agent server in development mode (supports Node & Python). |

Interaction & Testing

| Command | Description | | ------- | ----------- | | hive call <agent> | Interact with an agent using the A2A protocol. Supports attachments. |

Options:

• -m, --message: Send a single message (non-interactive).
• -i, --interactive: Start an interactive chat session.
• -f, --file: Attach a file to the message (can be used multiple times).
• -d, --directory: Attach all files in a directory (can be used multiple times).

Examples:

# Start an interactive chat session
hive call my-agent -i

# Send a single message (one-shot)
hive call my-agent -m "Summarize this article"

# Analyze a file
hive call my-agent -m "Check this log" -f ./error.log

# Analyze multiple files or directories
hive call my-agent -m "Review this data" -f ./data.csv -d ./logs/

Platform Integration

| Command | Description | | ------- | ----------- | | hive login | Authenticate with OpenHive Platform. | | hive logout | Sign out from OpenHive Platform. | | hive whoami | Display current user information. | | hive publish | Bundle source, push to registry, and deploy. | | hive push | Push agent source to registry (without deploying). | | hive deploy | Deploy an existing agent version to the cloud. |

Examples:

# Login to OpenHive Platform
hive login

# Publish your agent (from agent directory)
hive publish

# Just push the source code (useful for CI/CD)
hive push

# Deploy a specific version
hive deploy --name my-agent --version 0.1.0

Configuration

| Command | Description | | ------- | ----------- | | hive config get <key> | Get a configuration value. | | hive config set <key> <value> | Set a configuration value. | | hive config list | List all configuration values. |

Examples:

# View current platform URL
hive config get url

# Change platform URL
hive config set url https://www.openhive.cloud

# List all config
hive config list

🏗️ Agent Structure

When you create or add an agent, you get a standard A2A-compliant structure.

Node.js Agent

my-agent/
├── .agent-card.json   # Agent configuration (AgentCard)
├── package.json       # Dependencies
├── src/
│   └── index.ts      # A2A-compliant agent implementation
└── tsconfig.json      # TypeScript configuration

Python Agent

my-agent/
├── .agent-card.json   # Agent configuration (AgentCard)
├── requirements.txt   # Dependencies
└── main.py           # A2A-compliant agent implementation

📄 .agent-card.json Configuration

The .agent-card.json file is your A2A AgentCard - it defines your agent's metadata and skills:

{
  "name": "my-agent",
  "description": "An A2A-compliant AI agent",
  "protocolVersion": "0.3.0",
  "version": "0.1.0",
  "url": "http://localhost:8080",
  "runtime": "node",
  "skills": [
    {
      "id": "hello-world",
      "name": "Hello World",
      "description": "A simple skill that returns a greeting",
      "tags": ["greeting", "demo"]
    }
  ]
}

🔌 A2A Protocol & Official SDKs

OpenHive CLI creates agents using the official A2A SDKs:

• Node.js: @a2a-js/sdk
• Python: a2a-sdk

These SDKs ensure your agents are compliant with the Agent2Agent protocol, handling task management, streaming, and error handling automatically.