Skip to main content
The hud analyze command inspects MCP environments to discover tools and capabilities. By default it uses cached metadata; pass --live (or Docker args) to run a container.

​
Usage

hud analyze <IMAGE> [DOCKER_ARGS...] [OPTIONS]
hud analyze --config mcp.json
hud analyze --cursor <SERVER_NAME>

​
Arguments

​
image
string
Docker image to analyze (omit when using —config or —cursor)

​
Options

​
--format
string
default:"interactive"
Output format: interactive, json, or markdown. Short: -f
​
--verbose
boolean
default:"false"
Show input schemas in fast mode and more details in live mode. Short: -v
​
--live
boolean
default:"false"
Run container for live analysis (slower but exact)
​
--config
string
JSON file with MCP configuration (always live). Short: -c
​
--cursor
string
Analyze a Cursor MCP server (always live)

​
Analysis Modes

​
Fast Mode (Default)

Sources (in order):
  1. Local HUD cache: ~/.hud/envs/<digest>/hud.lock.yaml
  2. HUD registry metadata (if available)
  3. Basic Docker manifest info
# Instant results from metadata
hud analyze myorg/my-env:latest

​
Live Mode

Runs the container and queries the server: 
# Full analysis with running container
hud analyze myorg/my-env:latest --live

# Passing env vars implies live mode
a=API_KEY=secret hud analyze myorg/my-env:latest --live -e API_KEY=secret
Providing Docker args (after the image) automatically switches to live mode.

​
Output Formats

  • interactive (default): rich table/tree views
  • json: structured output for tooling
  • markdown: docs-friendly summaries

​
Examples

# Fast metadata analysis
hud analyze hudpython/text-2048:latest

# From lock file
hud analyze ./locks/text-2048.yaml --format json

# Live analysis with env vars
hud analyze my-env:latest --live -e API_KEY=test

# Cursor and config
hud analyze --cursor my-dev-server --live
hud analyze --config mcp-config.json

​
Tips

  • Prefer fast mode during iteration; switch to --live for final validation.
  • If metadata isn’t found, the command suggests pulling or running live.

​
See Also