Skip to main content
New protocol version released: This page may contain outdated information.

​
Overview

The HAIP CLI is a comprehensive command-line interface for the Human-Agent Interaction Protocol (HAIP), providing developers and system administrators with powerful tools for testing, monitoring, and interacting with HAIP servers. Built with TypeScript and featuring a beautiful terminal interface, the CLI supports all major HAIP protocol features.

Multiple Transports

WebSocket, SSE, and HTTP streaming support with automatic connection management.

Real-time Monitoring

Monitor server events with filtering, formatting, and follow mode.

Performance Testing

Test server connectivity and performance with configurable parameters.

Health Checks

Check server health status with JSON and text output formats.

Message Sending

Send text messages, tool calls, and run commands with full protocol support.

Interactive Mode

Connect and interact with servers in real-time with verbose logging.

​
Features

​
Core CLI Framework

  • Beautiful UI - Colored output with chalk, loading spinners with ora, and ASCII art with figlet
  • TypeScript Support - Full type safety with comprehensive type definitions
  • Error Handling - Robust error handling with user-friendly error messages
  • Help System - Comprehensive help and documentation for all commands

​
Connection Management

  • Multiple Transport Support - WebSocket, SSE, and HTTP streaming
  • Authentication - JWT token support with validation
  • Reconnection Logic - Automatic reconnection with exponential backoff
  • Heartbeat System - Automatic ping/pong for connection health monitoring
  • Connection State Tracking - Real-time connection state and statistics

​
Advanced Features

Flow Control

Credit-based flow control with back-pressure management

Binary Data Support

Audio chunks and binary frame handling

Session Management

Session ID tracking and resumption

Statistics Tracking

Message counts, byte transfer, and performance metrics

Configuration

Environment variable support for default settings

​
Quick Start

# Install from source
git clone https://github.com/haiprotocol/haip-cli.git
cd haip-cli
npm install
npm run build

# Check server health
node dist/index.js health

# Connect to server
node dist/index.js connect ws://localhost:8080

# Send a message
node dist/index.js send text "Hello, HAIP!"

# Monitor events
node dist/index.js monitor --follow

​
Architecture

The CLI is built with a modular architecture that separates concerns and provides flexibility:

​
Key Components

​
Command System

  • Commander.js Integration - Complete command-line argument parsing
  • Subcommand Support - Nested commands for complex operations
  • Help Generation - Automatic help text and usage examples
  • Option Validation - Type checking and validation for all options

​
Connection Layer

  • Transport Abstraction - Unified interface for all transport types
  • Connection Pooling - Efficient connection management
  • Error Recovery - Automatic retry and reconnection logic
  • State Management - Real-time connection state tracking

​
Message Processing

  • Protocol Compliance - Full HAIP 1.1.2 protocol support
  • Message Validation - Schema validation for all message types
  • Event Handling - Comprehensive event processing and routing
  • Binary Support - Audio and binary data handling

​
Output System

  • Colored Terminal - Beautiful, readable output with syntax highlighting
  • Multiple Formats - Text, JSON, and structured output options
  • Progress Indicators - Loading spinners and progress bars
  • Error Reporting - Clear, actionable error messages

​
Protocol Support

The HAIP CLI implements the complete HAIP 1.1.2 protocol specification:

Core Events

HAI - Protocol handshake and version negotiation
PING/PONG - Heartbeat and connection health monitoring
ERROR - Error reporting and handling

Messaging Events

MESSAGE_START/PART/END - Text message streaming
AUDIO_CHUNK - Audio data transmission
Message Channels - USER, AGENT, SYSTEM, AUDIO_IN, AUDIO_OUT

Run Management

RUN_STARTED - Start new conversation runs
RUN_FINISHED - Complete runs with status and summary
RUN_CANCEL - Cancel active runs
RUN_ERROR - Error handling for runs

Tool Integration

TOOL_CALL - Invoke tools with parameters
TOOL_UPDATE - Tool progress updates
TOOL_DONE - Tool completion with results
TOOL_CANCEL - Cancel tool execution
TOOL_LIST - Discover available tools
TOOL_SCHEMA - Tool schema definitions

Flow Control

FLOW_UPDATE - Credit-based flow control
PAUSE_CHANNEL - Channel pause for back-pressure
RESUME_CHANNEL - Channel resume after pause

​
Use Cases

Development & Testing

Protocol Testing - Validate HAIP protocol implementations
Server Testing - Test server functionality and performance
Debugging - Monitor and debug HAIP applications
Integration Testing - Test client-server integration

Production Monitoring

Health Monitoring - Monitor server health and status
Performance Monitoring - Track message throughput and latency
Error Monitoring - Monitor and debug production issues
Load Testing - Test server performance under load

Administration

Server Management - Manage HAIP server instances
Configuration Testing - Test server configurations
Deployment Validation - Validate deployments and configurations
Troubleshooting - Diagnose and resolve issues

​
Next Steps