The hud push command publishes your HUD environment to both Docker registry and HUD registry, making it available for others to use with hud pull.

​
Usage

hud push [DIRECTORY] [OPTIONS]

​
Arguments

​
directory
string
default:"."
Environment directory containing hud.lock.yaml

​
Options

​
--image
string
Override registry image name (e.g., myorg/myenv). Short: -i
​
--tag
string
Override tag (e.g., v1.0, latest). Short: -t
​
--sign
boolean
default:"false"
Sign the image with cosign (not yet implemented)
​
--yes
boolean
default:"false"
Skip confirmation prompts. Short: -y
​
--verbose
boolean
default:"false"
Show detailed output. Short: -v

​
Prerequisites

hud push requires an API key. Set it via environment variable:
export HUD_API_KEY="your-api-key"
You must be logged in to a Docker registry:
docker login
# or
docker login ghcr.io

​
What It Does

1

Validate Lock File

Reads hud.lock.yaml to get image reference and metadata
2

Tag for Registry

Creates registry tag from local image:
  • Uses --image if provided
  • Auto-detects from Docker config
  • Defaults to Docker Hub format
3

Push to Docker

Pushes image to Docker registry and gets digest
4

Update Lock File

Updates hud.lock.yaml with:
  • Registry image reference with digest
  • Push timestamp
  • Registry information
5

Upload Metadata

Sends lock file to HUD registry at: {HUD_API_URL}/registry/envs/{org}/{name}:{tag}

​
Registry Detection

The command intelligently detects your registry:
  1. Explicit: Use --image flag 
    hud push . --image ghcr.io/myorg/myenv
  2. Docker Config: Reads from ~/.docker/config.json 
    docker login ghcr.io
hud push  # Auto-uses ghcr.io
  3. Default: Docker Hub format 
    hud push  # Creates: yourusername/envname

​
Examples

​
Basic Push

Push to default registry: 
# After hud build
hud push
Output: 
🚀 HUD Environment Push

📋 Local Details
Image: hud-my-env:latest
Lock: hud.lock.yaml (2.3 KB)
Tools: 5 tools available

🎯 Registry Target
Local: hud-my-env:latest
Registry: myusername/my-env:latest

Push to registry? [y/N]: y

✅ Tagged image
✅ Pushed to registry: myusername/my-env@sha256:abc123...
✅ Updated lock file
✅ Metadata uploaded to HUD registry

​
Custom Registry

Push to GitHub Container Registry: 
hud push . --image ghcr.io/myorg/my-tool --tag v1.0.0

​
CI/CD Automation

Skip prompts for automation: 
hud push . --yes --tag "prod-$(date +%Y%m%d)"

​
Override Tag

Push with different tag: 
hud push . --tag experimental

​
Lock File Updates

After pushing, hud.lock.yaml gains registry information: 
version: "1.0"
image: "myorg/myenv:latest@sha256:abc123..."
build:
  generatedAt: "2024-01-15T10:30:00Z"
  hudVersion: "0.1.0"
  directory: "my-env"
push:
  source: "hud-my-env:latest"
  pushedAt: "2024-01-15T11:00:00Z"
  registry: "ghcr.io"
environment:
  # ... environment details
tools:
  # ... tool information

​
Sharing Workflows

​
Public Sharing

After pushing, others can use: 
# Pull with metadata preview
hud pull myorg/myenv:latest

# Use in MCP configs
{"hud": {"registry": "myorg/myenv:latest"}}

# Direct Docker usage
docker run myorg/myenv:latest

​
Private Registries

For private registries, users need:
  1. Docker registry access: 
    docker login private-registry.com
  2. HUD API key (if using private HUD registry): 
    export HUD_API_KEY="shared-key"

​
Usage Messages

After successful push, helpful usage examples are shown: 
📦 Usage:

Test locally:
  hud run myorg/myenv:latest

Use in MCP configs:
  
  Claude Desktop:
    {"docker": {"image": "myorg/myenv@sha256:...", "command": "auto"}}
  
  Via HUD (recommended):
    {"hud": {"registry": "myorg/myenv:latest"}}

Share environment:
  Others can now pull with: hud pull myorg/myenv:latest

​
Troubleshooting

​
Authentication Issues

​
Push Failures

For large images, push may timeout. Use --verbose to see progress:
hud push . --verbose
If metadata upload fails, the Docker image is still pushed. You can retry metadata upload or share hud.lock.yaml manually.

​
Best Practices

  1. Version Tags: Use semantic versioning 
    hud push . --tag v1.0.0
hud push . --tag v1.1.0-beta
  2. Namespace Organization: Group related environments 
    hud push . --image myorg/tools/browser
hud push . --image myorg/tools/scraper
  3. Documentation: Update README with pull instructions 
    ## Installation
```bash
hud pull myorg/myenv:latest
  4. CI Integration: Automate pushes 
    - name: Push HUD environment
  env:
    HUD_API_KEY: ${{ secrets.HUD_API_KEY }}
  run: hud push . --yes --tag ${{ github.ref_name }}

​
Security

The HUD registry only stores metadata (lock files), not code or images. Actual images are stored in Docker registries with their existing security models.
  • API Keys: Keep HUD_API_KEY secret
  • Registry Auth: Use Docker’s credential helpers
  • Image Signing: Coming soon with --sign flag
  • Private Envs: Use private Docker registries

​
See Also