Skip to main content

​
Overview

The Hive CLI (hive) provides commands for running agents, managing sessions, testing, and more. 
hive --help

​
Installation

pip install -e core/
The hive command will be available in your PATH.

​
Global Options

​
--model
str
default:"claude-haiku-4-5-20251001"
Anthropic model to use for all commands

​
Command Categories

​
Agent Execution

​
Agent Information

​
Session Management

​
Testing

​
Development

​
Common Commands

​
info

Show agent information. 
hive info exports/my_agent
hive info exports/my_agent --json
​
agent_path
str
required
Path to agent folder (containing agent.json)
​
--json
flag
Output as JSON

​
validate

Validate an exported agent. 
hive validate exports/my_agent
​
agent_path
str
required
Path to agent folder
Output:
  • Graph structure validation
  • Tool availability check
  • Warnings and suggestions

​
list

List available agents. 
hive list
hive list exports/
​
directory
str
default:"exports"
Directory to search for agents

​
shell

Start an interactive agent session (REPL). 
hive shell exports/my_agent
hive shell  # Interactive selection
hive shell --multi  # Multi-agent mode
​
agent_path
str
Path to agent folder (optional, can select interactively)
​
--agents-dir
str
default:"exports"
Directory containing agents
​
--multi
flag
Enable multi-agent mode with orchestrator
​
--no-approve
flag
Disable human-in-the-loop approval (auto-approve all steps)
Features:
  • Natural language input (auto-formatted with Haiku)
  • JSON input support
  • Session memory across inputs
  • Special commands:
    • /info - Show agent details
    • /nodes - Show agent nodes
    • /reset - Reset conversation state
    • /quit - Exit

​
dispatch

Dispatch request to multiple agents via orchestrator. 
hive dispatch exports/ --input '{"task": "analyze data"}' --intent "Data analysis"
hive dispatch --agents my_agent1 my_agent2 --input '{"task": "..."}'
​
agents_dir
str
default:"exports"
Directory containing agent folders
​
--input
str
required
Input context as JSON string
​
--intent
str
Description of what you want to accomplish
​
--agents
list[str]
Specific agent names to use (default: all in directory)
​
--quiet
flag
Only output the final result JSON

​
code

Launch Hive Coder (interactive agent builder). 
hive code
hive code --model claude-sonnet-4-20250514
​
--model
str
LLM model to use (any LiteLLM-compatible name)
Opens the Hive Coder TUI where you can describe what you want and the coder builds the agent for you.

​
Session Management

​
sessions list

List agent sessions. 
hive sessions list exports/my_agent
hive sessions list exports/my_agent --status failed
hive sessions list exports/my_agent --has-checkpoints
​
agent_path
str
required
Path to agent folder
​
--status
str
default:"all"
Filter by status: all, active, failed, completed, paused
​
--has-checkpoints
flag
Show only sessions with checkpoints

​
sessions show

Show session details. 
hive sessions show exports/my_agent session_123
hive sessions show exports/my_agent session_123 --json
​
agent_path
str
required
Path to agent folder
​
session_id
str
required
Session ID to inspect
​
--json
flag
Output as JSON

​
sessions checkpoints

List session checkpoints. 
hive sessions checkpoints exports/my_agent session_123
​
agent_path
str
required
Path to agent folder
​
session_id
str
required
Session ID

​
pause

Request graceful pause of a running session. 
hive pause exports/my_agent session_123
​
agent_path
str
required
Path to agent folder
​
session_id
str
required
Session ID to pause

​
resume

Resume a paused or failed session from a checkpoint. 
hive resume exports/my_agent session_123
hive resume exports/my_agent session_123 --checkpoint checkpoint_5
hive resume exports/my_agent session_123 --tui
​
agent_path
str
required
Path to agent folder
​
session_id
str
required
Session ID to resume
​
--checkpoint
str
Specific checkpoint ID to resume from (default: latest)
​
--tui
flag
Resume in TUI dashboard mode

​
setup-credentials

Interactive credential setup. 
hive setup-credentials exports/my_agent
hive setup-credentials  # General setup
​
agent_path
str
Path to agent folder (optional - runs general setup if not specified)
Guides you through setting up required credentials for an agent.

​
serve

Start HTTP API server. 
hive serve
hive serve --port 8080 --host 0.0.0.0
hive serve --agent exports/my_agent --model claude-sonnet-4-20250514 --open
​
--host
str
default:"127.0.0.1"
Host to bind
​
--port
int
default:"8787"
Port to listen on
​
--agent
list[str]
Agent path(s) to preload (repeatable)
​
--model
str
LLM model for preloaded agents
​
--open
flag
Open dashboard in browser after server starts
Features:
  • REST + SSE APIs for agent control
  • Web dashboard for monitoring
  • Multi-agent support

​
Examples

​
Run an agent

# Basic run
hive run exports/calculator --input '{"expression": "2 + 3"}'

# With TUI
hive run exports/calculator --input '{"expression": "2 + 3"}' --tui

# Resume from session
hive run exports/calculator --resume-session session_123

# Resume from checkpoint
hive run exports/calculator --resume-session session_123 --checkpoint checkpoint_5

​
Interactive session

hive shell exports/assistant
>>> What's the weather in SF?
>>> /info
>>> /reset
>>> /quit

​
Test an agent

# Run all tests
hive test-run exports/calculator --goal calc-001

# Run constraint tests only
hive test-run exports/calculator --goal calc-001 --type constraint

# Parallel execution
hive test-run exports/calculator --goal calc-001 --parallel 4

# Debug a failed test
hive test-debug exports/calculator test_constraint_no_crash

​
Manage sessions

# List sessions
hive sessions list exports/assistant --status paused

# Show session details
hive sessions show exports/assistant session_123

# Resume from pause
hive resume exports/assistant session_123 --tui

​
Environment Variables

​
ANTHROPIC_API_KEY
str
Required for Claude models
​
OPENAI_API_KEY
str
Required for GPT models
​
HIVE_STORAGE_PATH
str
default:"~/.hive"
Base path for agent storage
​
LOG_LEVEL
str
default:"INFO"
Logging level: DEBUG, INFO, WARNING, ERROR

​
Exit Codes

  • 0: Success
  • 1: Error (validation failed, execution failed, etc.)

Build docs developers (and LLMs) love

Get started for freeTalk to us