Hive CLI Reference
The Hive CLI is the primary interface for developing, executing, and monitoring autonomous agents. It provides tools for both headless execution (CI/CD) and interactive development via the Terminal User Interface (TUI).
Command Overview
The CLI is typically invoked via the hive command or python -m framework. For specific agents, the entry point is usually defined in the agent's __main__.py.
Core Commands
run
Executes an agent's workflow for a specific goal or topic.
# Basic execution
hive run --topic "Market analysis of RISC-V processors"
# Execution with mock mode for testing logic without LLM costs
hive run --topic "example topic" --mock
# Quiet mode for programmatic use (outputs JSON)
hive run --topic "data" --quiet
Options:
--topic,-t(Required): The primary input or goal for the agent.--mock: Runs the agent using mock LLM responses.--quiet,-q: Suppresses logs and only outputs the final result in JSON format.--verbose,-v: Enables standard INFO level logging.--debug: Enables detailed DEBUG level logging including framework internals.
tui
Launches the Aden TUI Dashboard, an interactive terminal environment for real-time monitoring and Human-in-the-Loop (HITL) interaction.
hive tui
Dashboard Features:
- Graph View: Visualizes the agent's node structure and current execution path.
- Log Pane: Real-time stream of tool calls, LLM reasoning, and system events.
- Chat REPL: Allows the user to provide feedback or answer agent queries during execution.
info
Displays metadata and structural information about the agent.
hive info
# Use --json for machine-readable output
hive info --json
Output Includes:
- Agent name and version.
- Node graph structure (Entry and Terminal nodes).
- Available tools and capabilities.
- Client-facing nodes (points where the agent can pause for human input).
Interactive Approval Workflow
Hive implements a strict "Human-in-the-Loop" policy for generated code and test cases. When the framework generates a self-improvement test or modifies its own logic, it triggers the Interactive Approval CLI.
Actions
When prompted, you can process pending actions using the following keys:
| Key | Action | Description |
| :--- | :--- | :--- |
| a | Approve | Accepts the generated code/test as-is and continues execution. |
| r | Reject | Declines the change. You will be prompted to provide a reason for the agent to learn from. |
| e | Edit | Opens the code in your default $EDITOR for manual modification before approval. |
| s | Skip | Leaves the decision pending and moves to the next item (if batching). |
Logging and Observability
The Hive CLI provides a three-level logging system to balance visibility and performance:
- Level 1 (Summary): High-level run status, duration, and token consumption.
- Level 2 (Details): Per-node completion results, including retry attempts and "attention flags" for failures.
- Level 3 (Tool Logs): Granular traces of every tool call, input/output payload, and raw LLM text.
Viewing Logs via CLI
Logs are stored in the agent's storage path (default: ~/.hive/agents/<agent_name>/). You can pipe the JSON output of a run --quiet command into tools like jq for analysis:
hive run --topic "research" --quiet | jq '.output'
Environment Configuration
The CLI respects several environment variables for credential management and connectivity:
| Variable | Description |
| :--- | :--- |
| OPENAI_API_KEY | Key for OpenAI models. |
| ANTHROPIC_API_KEY | Key for Anthropic/Claude models. |
| HIVE_STORAGE_PATH | Directory where agent state, logs, and credentials are persisted. |
| EDITOR | The text editor used when choosing the [e]dit option during approval. |
File System Tools (MCP)
When running through the CLI, agents have access to a secure file system toolkit (via Model Context Protocol). These tools are constrained to the agent's session sandbox:
view_file: Reads content from a specific path.list_directory: Lists files in the agent's workspace.patch_file: Applies incremental changes to existing files after approval.