CLI Overview

Complete reference for HUD command-line tools

The HUD CLI provides a complete toolkit for creating, developing, and running MCP environments. Commands are organized into two main workflows:

Build & Ship

Directory-based commands for creating and sharing environments:

• hud init — Create new environment
• hud dev — Develop with hot‑reload
• hud build — Build and generate lock file
• hud push — Share to registry

Run & Evaluate

Target-based commands for using environments and agents:

• hud analyze — Inspect capabilities (fast/live)
• hud debug — 5‑phase compliance test
• hud run — Execute (Python module/command/Docker)
• hud eval — Run agents on tasks/datasets
• hud rft — Fine-tune models (BETA, invite-only)

Installation

uv (Recommended)

uv tool install hud-python@latest --python 3.12
hud --version

Commands

Building Workflow

Command	Input	Description	Example
hud init	Directory	Create new environment	hud init my-env
hud dev	Directory	Hot-reload development	hud dev . --interactive
hud build	Directory	Build image & lock file	hud build . --tag v1.0
hud push	Directory	Share to registry	hud push . --tag prod

Running Workflow

Command	Input	Description	Example
hud analyze	Image or config	Inspect tools & capabilities	hud analyze org/env
hud debug	Image/dir/config	5‑phase compliance test	hud debug my-env:latest
hud run	Module/command/image	Execute server (local/remote)	hud run controller --reload
hud eval	Tasks/dataset	Run agent on tasks	hud eval tasks.json claude
hud rft	Tasks file	Fine-tune models (BETA, invite-only)	hud rft run tasks.json

Other Commands

Command	Description	Example
hud get	Download HF dataset to tasks file	hud get hud-evals/2048-basic -o tasks.jsonl
hud quickstart	Clone quickstart repo	hud quickstart
hud cursor-list	List Cursor MCP servers	hud cursor-list
hud version	Show CLI version	hud version
hud clone	Clone any git repo (pretty output)	hud clone https://github.com/...
hud set	Persist API keys to ~/.hud/.env	hud set HUD_API_KEY=...

Complete Workflows

Building an Environment

1. Initialize

   Create a new HUD environment with minimal boilerplate:

   hud init my-env && cd my-env
   

   Creates Dockerfile, pyproject.toml, controller/ (MCP server), optional environment/ backend, tasks.json.

2. Develop

   Run with hot-reload and interactive testing:

   hud dev
   

   Your changes reload automatically. Test tools interactively with arrow keys.

3. Build

   Create production image and lock file:

   hud build
   

   Generates hud.lock.yaml with metadata and labels image for reproducibility.

4. Push

   Share to Docker and HUD registries:

   hud push
   

   Requires HUD_API_KEY. Auto-detects registry from Docker login.

Running an Environment

1. Analyze

   Quick inspection without running:

   hud analyze hudpython/text_init    # Fast (from metadata)
   hud analyze hudpython/text_init --live  # Full (runs container)
   
2. Debug

   Test MCP protocol compliance:

   hud debug hudpython/text_init:latest
   

   Validates through 5 phases of initialization.

3. Run

   Execute in production mode:

   hud run hudpython/text_init:latest        # Remote (default)
   hud run hudpython/text_init:latest --local  # Local Docker
   

Common Usage

Docker Images

# Basic
hud debug my-image:latest

# With options
hud debug my-image:latest -e DEBUG=true -p 8080:8080

# From registry
hud analyze ghcr.io/org/image:v1.0.0

Arbitrary Commands (Python/Node/etc.)

# Run any command as MCP server (stdio/http)
hud run --cmd "python -m controller" -t http -p 8765
hud run --cmd "node mcp-server.js"

Cursor Integration

# Debug Cursor server
hud debug --cursor my-dev-server

# List all servers
hud cursor-list

Output Formats

Interactive (Default)

hud analyze my-env

🔍 Analyzing MCP environment: my-env
✓ Connected successfully
✓ Found 12 tools

Available Tools:
  • click - Click at coordinates
  • type - Type text
  ...

JSON

hud analyze my-env --format json

{
  "tools": [{
    "name": "click",
    "description": "Click at coordinates",
    "parameters": {...}
  }]
}

Markdown

hud analyze my-env --format markdown > docs/tools.md

CI/CD Example

#!/bin/bash
set -e

# Test environment
hud debug "$IMAGE_NAME"

# Verify tools
TOOLS=$(hud analyze "$IMAGE_NAME" --format json | jq '.tools | length')
if [ "$TOOLS" -lt 3 ]; then
  echo "Not enough tools!"
  exit 1
fi

Python Scripting

import subprocess
import json

def get_tools(image):
    result = subprocess.run(
        ["hud", "analyze", image, "--format", "json"],
        capture_output=True,
        text=True,
        check=True
    )
    return json.loads(result.stdout)["tools"]

# Use
tools = get_tools("my-env:latest")
for tool in tools:
    print(f"- {tool['name']}: {tool['description']}")

Exit Codes

Code	Meaning	Description
0	Success	Command completed
1	General Error	Command failed
2	Usage Error	Invalid arguments
3	Connection Error	Failed to connect
4	Timeout	Operation timed out
5	Protocol Error	MCP violation

Environment Variables

# Debug output
export HUD_CLI_DEBUG=true

# Custom timeout
export HUD_CLI_TIMEOUT=120

# Provider keys
export ANCHOR_API_KEY=...

Next Steps

Building Commands

Init Command

Create new environments from scratch

Dev Command

Develop with hot-reload and interactive testing

Build Command

Build images and generate lock files

Push Command

Share environments to registry

Running Commands

Analyze Command

Inspect tools and capabilities

Debug Command

Test MCP protocol compliance

Run Command

Execute servers locally or remotely