Skip to main content

​
Overview

The hive run command executes an exported agent with the given input. 
hive run <agent_path> [options]

​
Arguments

​
agent_path
str
required
Path to agent folder (containing agent.json)

​
Input Options

​
--input
str
Input context as JSON string
hive run exports/calculator --input '{"expression": "2 + 3"}'
​
--input-file
str
Input context from JSON file
hive run exports/calculator --input-file input.json

​
Output Options

​
--output
str
Write results to file instead of stdout
hive run exports/calculator --input '{...}' --output result.json
​
--quiet
flag
Only output the final result JSON (suppress execution logs)
hive run exports/calculator --input '{...}' --quiet
​
--verbose
flag
Show detailed execution logs (steps, LLM calls, etc.)
hive run exports/calculator --input '{...}' --verbose

​
Execution Options

​
--model
str
LLM model to use (any LiteLLM-compatible name)
hive run exports/calculator --model claude-sonnet-4-20250514 --input '{...}'
Overrides the agent’s default model.
​
--tui
flag
Launch interactive terminal dashboard
hive run exports/calculator --tui
Opens the TUI where you can monitor execution, see live logs, and interact with the agent.

​
Resume Options

​
--resume-session
str
Resume from a specific session ID
hive run exports/calculator --resume-session session_20240315_143022
Loads the session state and continues from where it left off.
​
--checkpoint
str
Resume from a specific checkpoint (requires —resume-session)
hive run exports/calculator --resume-session session_123 --checkpoint checkpoint_5
Restores execution state from the specified checkpoint.

​
Output Format

When execution completes, the output includes: 
{
  "success": true,
  "steps_executed": 5,
  "output": {
    "result": 5,
    "formatted_result": "The answer is 5"
  },
  "error": null,
  "paused_at": null
}
​
success
bool
Whether the agent achieved its goal
​
steps_executed
int
Number of nodes executed
​
output
dict
Final output data from the agent
​
error
str | null
Error message if execution failed
​
paused_at
str | null
Node ID where execution paused (for HITL or resume)

​
Examples

​
Basic Execution

hive run exports/calculator --input '{"expression": "2 + 3"}'
Output: 
Agent: Calculator
Goal: Perform calculations
Steps: 3
Input: {"expression": "2 + 3"}

============================================================
Executing agent...
============================================================

============================================================
Status: SUCCESS
Steps executed: 3
Path: input_parser → calculator → output_formatter
============================================================

--- Results ---
The answer is 5

​
Quiet Mode (JSON Only)

hive run exports/calculator --input '{"expression": "2 + 3"}' --quiet
Output: 
{
  "success": true,
  "steps_executed": 3,
  "output": {
    "result": 5,
    "formatted_result": "The answer is 5"
  }
}

​
Verbose Mode

hive run exports/calculator --input '{"expression": "2 + 3"}' --verbose
Output: 
Agent: Calculator
Goal: Perform calculations

[INFO] Executing node: input_parser
[INFO] Input: {"expression": "2 + 3"}
[INFO] LLM call: claude-haiku-4-5-20251001
[INFO] Tool call: parse_expression(expression="2 + 3")
[INFO] Output: {"parsed": {"op": "+", "left": 2, "right": 3}}
[INFO] ✓ input_parser completed (420ms, 150 tokens)

[INFO] Executing node: calculator
...

​
Save to File

hive run exports/calculator --input '{"expression": "2 + 3"}' --output result.json
cat result.json

​
Use Different Model

# Use Claude Sonnet instead of default Haiku
hive run exports/calculator \
  --model claude-sonnet-4-20250514 \
  --input '{"expression": "integrate x^2 from 0 to 10"}'

​
Interactive TUI

hive run exports/assistant --tui
Launches an interactive terminal dashboard where you can:
  • Enter input naturally
  • See live execution logs
  • Monitor node transitions
  • View conversation history
  • Interact with HITL prompts

​
Resume from Session

# First run (pauses at HITL node)
hive run exports/workflow --input '{"task": "process data"}'
# Output: "paused_at": "approval_node", session saved as session_123

# Resume later
hive run exports/workflow --resume-session session_123 --input '{"approved": true}'

​
Resume from Checkpoint

# List checkpoints
hive sessions checkpoints exports/workflow session_123
# Output: checkpoint_1, checkpoint_2, checkpoint_3

# Resume from specific checkpoint
hive run exports/workflow \
  --resume-session session_123 \
  --checkpoint checkpoint_2

​
Input Auto-Injection

If the agent expects a user_id input but none is provided, the framework auto-injects the current user: 
# No user_id in input
hive run exports/assistant --input '{"message": "Hello"}'
# Framework adds: "user_id": "your_username"
You can override this: 
hive run exports/assistant --input '{"message": "Hello", "user_id": "alice"}'

​
Error Handling

If execution fails: 
hive run exports/calculator --input '{"expression": "invalid"}'
Output: 
============================================================
Status: FAILED
Steps executed: 2
Path: input_parser → calculator
============================================================

Error: Invalid expression: 'invalid'
Exit code: 1

​
Input from File

# Create input.json
cat > input.json <<EOF
{
  "lead_name": "Acme Corp",
  "email": "[email protected]",
  "budget": 50000
}
EOF

# Run with file input
hive run exports/lead-qualifier --input-file input.json

​
Piping Output

# Extract specific field
hive run exports/calculator --input '{"expression": "2 + 3"}' --quiet | jq '.output.result'
# Output: 5

# Check success
hive run exports/agent --input '{...}' --quiet | jq '.success'
# Output: true

​
Exit Codes

​
0
int
Success - Agent completed successfully
​
1
int
Failure - Agent failed, invalid input, or execution error

Build docs developers (and LLMs) love

Get started for freeTalk to us