@open-hive/cli

OpenHive CLI

The Official Command-Line Interface for the OpenHive Platform

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

🌟 Features

• 🛠️ Project Scaffolding: Interactively create A2A-compliant agent projects from a remote registry of official templates.
• 🚀 Local Development: Start and test your agents locally with a single command
• 📦 Agent Publishing: Package and publish your agents to OpenHive Platform for automatic deployment
• 📥 Agent Installation: Install agents from the OpenHive marketplace
• 🧪 Interactive Testing: Test A2A agents interactively with capability discovery
• 🔑 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

Create Your First Agent

# Create a new agent interactively
hive agents create my-agent

# The CLI will prompt you to select a runtime (e.g., Node.js, 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 (reads .agent-card.json)
hive start

📚 Commands

Agent Development

Command	Description
hive agents create <name>	Interactively create a new A2A-compliant agent project
hive agents list	List agents from a registry
hive agents delete [agentId]	Delete an agent from a registry
hive agents test	Interactively test an A2A agent
hive start	Start a local agent from .hive.yml
hive up	Start the local agent registry server
hive publish --local	Publish an agent to the local registry

Examples:

# Create an agent (you will be prompted for runtime and template)
hive agents create my-new-agent

# In a new terminal, start the local registry (and leave it running)
hive up

# In your agent's directory, publish it to the local registry
hive publish --local

# Start your agent
hive start

# Test an agent running locally
hive agents test --endpoint http://localhost:8080

Platform Integration

Command	Description
hive login	Authenticate with OpenHive Platform
hive logout	Log out from OpenHive Platform
hive whoami	Display current user information
hive publish	Publish agent to OpenHive Platform
hive install <agent>	Install an agent from OpenHive Platform

Examples:

# Login to OpenHive Platform
hive login

# Check who you're logged in as
hive whoami

# Alternatively, use an API Key for CI/CD environments
export HIVE_API_KEY="your-api-key"
hive whoami

# Publish your agent (from agent directory)
hive publish

# Install a public agent
hive install weather-agent

# Install a specific version
hive install weather-agent@1.2.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.sh

# List all config
hive config list

🏗️ Agent Structure

When you create an agent with hive agents create, you get a complete project 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"]
    }
  ]
}

The agent code loads this directly - no conversion needed!

🔌 A2A Protocol & Official SDKs

OpenHive CLI creates agents using the official A2A SDKs:

• Node.js: @a2a-js/sdk - Built by the A2A team
• Python: a2a-sdk - Official Python implementation

Why Official SDKs?

• ✅ Protocol Compliance: Guaranteed compatibility with A2A spec
• ✅ Automatic Updates: SDK handles protocol changes
• ✅ Less Code: Focus on your logic, not protocol details
• ✅ Better Features: Built-in task management, streaming, error handling

Key Endpoints

The A2A SDKs automatically provide these standard endpoints:

• GET /.well-known/agent-card.json - Returns agent metadata and skills
• GET /health - Health check
• POST /tasks - Execute a skill
• GET /tasks/:taskId - Get task status

Agent Architecture

Agents use the AgentExecutor pattern:

// Node.js
class MyAgentExecutor extends AgentExecutor {
  async execute(requestContext, eventBus) {
    // Your skill logic here
    eventBus.publish(responseMessage)
    eventBus.finished()
  }
}

# Python
class MyAgentExecutor(AgentExecutor):
    async def execute(self, request_context, event_bus):
        # Your skill logic here
        event_bus.publish(response_message)
        event_bus.finished()