The hud pull command fetches HUD environments from registries, showing a preview of tools and capabilities before downloading the Docker image.

​
Usage

hud pull <TARGET> [OPTIONS]

​
Arguments

​
target
string
required
Image reference (e.g., org/env:tag) or path to lock file

​
Options

​
--lock
string
Path to save lock file (if target is image ref). Short: -l
​
--yes
boolean
default:"false"
Skip confirmation prompt. Short: -y
​
--verify-only
boolean
default:"false"
Only verify metadata without pulling image
​
--verbose
boolean
default:"false"
Show detailed output. Short: -v

​
How It Works

1

Fetch Metadata

Retrieves environment information from:
  • HUD registry (if available)
  • Docker manifest (fallback)
  • Local lock file (if provided)
2

Display Preview

Shows environment details:
  • Available tools and descriptions
  • Build information
  • Required environment variables
  • Image size
3

Confirm Download

Prompts for confirmation before pulling (unless --yes)
4

Pull Image

Downloads Docker image using docker pull
5

Save Lock File

Stores metadata locally for offline access

​
Examples

​
Basic Pull

Pull from HUD registry: 
hud pull hudpython/text-analyzer:latest
Output: 
🚀 HUD Environment Pull

Fetching metadata for: hudpython/text-analyzer:latest

📦 Environment Details
┌─────────────┬──────────────────────────┐
│ Image       │ hudpython/text-analyzer  │
│ Source      │ HUD Registry             │
│ Built       │ 2024-01-15T10:30:00Z     │
│ HUD Version │ 0.1.0                    │
│ Size        │ 156 MB                   │
│ Tools       │ 8                        │
└─────────────┴──────────────────────────┘

🔧 Available Tools
├── setup - Initialize environment
├── evaluate - Return environment state  
├── analyze_text - Analyze text sentiment
├── extract_entities - Extract named entities
└── ... 4 more tools

🔑 Environment Variables
├── Required: OPENAI_API_KEY
└── Optional: DEBUG, LOG_LEVEL

Pull hudpython/text-analyzer:latest? [y/N]: y

​
Skip Confirmation

Auto-pull for scripts: 
hud pull myorg/myenv:v1.0.0 --yes

​
Verify Only

Check metadata without downloading: 
hud pull myorg/myenv:latest --verify-only

​
From Lock File

Pull using a shared lock file: 
# Someone shares their hud.lock.yaml
hud pull ./shared-env.lock.yaml

​
Custom Lock Location

Save lock file to specific path: 
hud pull myorg/myenv:latest --lock ~/.hud/locks/myenv.yaml

​
Metadata Sources

The command tries these sources in order:
  1. HUD Registry (Fastest)
    • Full tool descriptions
    • Build metadata
    • Environment requirements
  2. Docker Registry (Limited)
    • Basic image info
    • Size and layers
    • No tool details
  3. Lock File (Complete)
    • Full environment snapshot
    • Reproducible reference
    • Offline capable

​
Lock File Storage

Downloaded lock files are saved to: 
~/.hud/locks/{org}_{name}_{tag}.yaml
Examples:
  • hudpython_text-analyzer_latest.yaml
  • myorg_browser-env_v1.0.0.yaml
Lock files are cached locally, so repeated hud analyze commands are instant.

​
Next Steps

After pulling, the command shows: 
✅ Image pulled successfully
✅ Lock file saved to: ~/.hud/locks/hudpython_text-analyzer_latest.yaml

Next Steps:
  1. Quick analysis:    hud analyze hudpython/text-analyzer
  2. Live analysis:     hud analyze hudpython/text-analyzer --live
  3. Run locally:       hud run hudpython/text-analyzer:latest

​
Registry Access

​
Public Environments

No authentication needed: 
# HUD's public environments
hud pull hudpython/code-analyzer:latest
hud pull hudpython/web-browser:latest

​
Private Registries

Requires Docker login: 
# Login first
docker login private-registry.com

# Then pull
hud pull private-registry.com/team/tool:latest

​
API Key Benefits

With HUD_API_KEY set:
  • Access private HUD metadata
  • Faster metadata retrieval
  • Additional environment details
export HUD_API_KEY="your-key"
hud pull myorg/private-env:latest

​
Troubleshooting

​
Common Issues

​
Network Issues

Behind a proxy? Configure Docker:
export HTTP_PROXY=http://proxy:8080
export HTTPS_PROXY=http://proxy:8080

​
Integration Examples

​
CI/CD Pipeline

# GitHub Actions
- name: Pull HUD environment
  run: |
    hud pull myorg/test-env:latest --yes
    hud analyze myorg/test-env:latest

​
Docker Compose

services:
  mcp-env:
    image: myorg/myenv:latest
    environment:
      - API_KEY=${API_KEY}

​
Scripted Setup

#!/bin/bash
# Pull multiple environments
ENVS=("web-browser" "code-analyzer" "data-processor")

for env in "${ENVS[@]}"; do
  echo "Pulling $env..."
  hud pull "hudpython/$env:latest" --yes
done

​
Best Practices

  1. Version Pinning: Use specific tags 
    hud pull myorg/tool:v1.2.3  # Good
hud pull myorg/tool:latest  # Risky
  2. Cache Lock Files: Share lock files for reproducibility 
    # Save to project
hud pull myorg/env:v1 --lock ./env.lock.yaml
git add env.lock.yaml
  3. Verify First: Check before downloading large images 
    hud pull myorg/large-env:latest --verify-only
  4. Document Requirements: Note any required env vars 
    # After pull, check requirements
hud analyze myorg/env:latest

​
See Also