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:

Create & Deploy

Directory-based commands for creating environments:

• hud init — Create new environment
• hud deploy — Build remotely & deploy to platform
• hud dev — Local development (hot-reload via --watch)
• hud build — Local build for validation

Run & Evaluate

Target-based commands for using environments and agents:

• hud analyze — Inspect capabilities (fast/live)
• hud debug — 5‑phase compliance test
• 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

Create & Deploy

Command	Input	Description	Example
hud init	Directory	Create new environment	hud init my-env
hud deploy	Directory	Build remotely & deploy to platform	hud deploy .
hud link	Directory	Link to existing environment	hud link --id abc123

Local Development

Command	Input	Description	Example
hud dev	Directory	Development server (--watch for hot-reload)	hud dev . -w controller
hud build	Directory	Build image locally (for validation)	hud build . --tag v1.0

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 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

Registry & Management

Command	Description	Example
hud push	Push built image to registry	hud push .
hud cancel	Cancel remote eval jobs	hud cancel <job_id>

Utilities

Command	Description	Example
hud set	Persist API keys to ~/.hud/.env	hud set HUD_API_KEY=...
hud models	List available inference models	hud models --json
hud convert	Convert external task formats to HUD	hud convert ./tasks --from harbor
hud version	Show CLI version	hud version

Complete Workflows

Creating & Deploying 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. Deploy

   Deploy directly to the HUD platform:

   hud deploy
   

   This builds your environment remotely on HUD’s infrastructure and deploys it. Or push to GitHub and connect on hud.ai for automatic rebuilds.

Local Development (Optional)

Use these commands when iterating on your environment locally before deploying:

# Development server (no auto-reload by default)
hud dev

# Enable hot-reload explicitly
hud dev -w controller -w environment

# Build locally to validate before deploying
hud build

hud dev runs your local development server; add --watch (-w) to enable automatic reloads. hud build creates a local Docker image and generates hud.lock.yaml for validation.

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.

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

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

Create & Deploy

Init Command

Create new environments from scratch

Deploy Command

Build remotely and deploy to HUD platform

Local Development

Dev Command

Develop locally with optional hot-reload and interactive testing

Build Command

Build images locally for validation

Running Commands

Analyze Command

Inspect tools and capabilities

Debug Command

Test MCP protocol compliance