Skip to content

Install CLI

Run HolmesGPT from your terminal as a standalone CLI tool.

Installation Options

  1. Add our tap: 

    brew tap robusta-dev/homebrew-holmesgpt

  2. Install HolmesGPT: 

    brew install holmesgpt

  3. To upgrade to the latest version: 

    brew upgrade holmesgpt

  4. Verify installation: 

    holmes ask --help

  1. Install pipx

  2. Install HolmesGPT: 

    pipx install holmesgpt

  3. Verify installation: 

    holmes ask --help

For development or custom builds:

  1. Install Poetry

  2. Install HolmesGPT: 

    git clone https://github.com/HolmesGPT/holmesgpt.git
cd holmesgpt
poetry install --no-root

  3. Verify installation: 

    poetry run holmes ask --help

Run HolmesGPT using the prebuilt Docker container:

docker run -it --net=host \
  -e OPENAI_API_KEY="your-api-key" \
  -v ~/.holmes:/root/.holmes \
  -v ~/.aws:/root/.aws \
  -v ~/.config/gcloud:/root/.config/gcloud \
  -v $HOME/.kube/config:/root/.kube/config \
  us-central1-docker.pkg.dev/genuine-flight-317411/devel/holmes ask "what pods are unhealthy and why?"

Note: Use -e flags to pass API keys for your provider (e.g., -e ANTHROPIC_API_KEY, -e GEMINI_API_KEY). See Environment Variables Reference for the complete list.

Quick Start

Choose your AI provider (see all providers for more options).

Which Model to Use

We highly recommend using Sonnet 4.0 or Sonnet 4.5 as they give the best results by far. These models are available from Anthropic, AWS Bedrock, and Google Vertex. View Benchmarks.

No Kubernetes Required

The examples below use a Kubernetes pod for a quick guided demo, but HolmesGPT works with any infrastructure. If you don't use Kubernetes, skip the kubectl apply step and ask about your own systems instead: 

holmes ask "what Prometheus alerts are currently firing and why?"
holmes ask "what is the health of my Elasticsearch cluster?"
holmes ask "are there any issues with my production databases?"
See data sources for all supported integrations.

  1. Set up API key: 

    export ANTHROPIC_API_KEY="your-api-key"

  2. Create a test pod to investigate: 

    kubectl apply -f https://raw.githubusercontent.com/robusta-dev/kubernetes-demos/main/pending_pods/pending_pod_node_selector.yaml

  3. Ask your first question: 

    holmes ask "what is wrong with the user-profile-import pod?" --model="anthropic/claude-sonnet-4-5-20250929"

Note: You can use any Anthropic model by changing the model name. See Claude Models Overview for available model names.

See Anthropic Configuration for more details.

  1. Set up API key: 

    export OPENAI_API_KEY="your-api-key"

  2. Create a test pod to investigate: 

    kubectl apply -f https://raw.githubusercontent.com/robusta-dev/kubernetes-demos/main/pending_pods/pending_pod_node_selector.yaml

  3. Ask your first question: 

    # Uses gpt-4.1 by default (fairly fast, decent results)
holmes ask "what is wrong with the user-profile-import pod?"

# Or specify a different model
holmes ask "what is wrong with the user-profile-import pod?" --model="gpt-5"

See OpenAI Configuration for more details.

  1. Set up API key: 

    export AZURE_API_VERSION="2024-02-15-preview"
export AZURE_API_BASE="https://your-resource.openai.azure.com"
export AZURE_API_KEY="your-azure-api-key"

  2. Create a test pod to investigate: 

    kubectl apply -f https://raw.githubusercontent.com/robusta-dev/kubernetes-demos/main/pending_pods/pending_pod_node_selector.yaml

  3. Ask your first question: 

    holmes ask "what is wrong with the user-profile-import pod?" --model="azure/<your-model-name>"

See Azure OpenAI Configuration for more details.

  1. Set up API key: 

    export AWS_ACCESS_KEY_ID="your-access-key"
export AWS_SECRET_ACCESS_KEY="your-secret-key"
export AWS_DEFAULT_REGION="your-region"

  2. Install boto3: 

    pip install "boto3>=1.28.57"

  3. Create a test pod to investigate: 

    kubectl apply -f https://raw.githubusercontent.com/robusta-dev/kubernetes-demos/main/pending_pods/pending_pod_node_selector.yaml

  4. Ask your first question: 

    # Recommended: Use Sonnet 4.0 or Sonnet 4.5 for best results
holmes ask "what is wrong with the user-profile-import pod?" --model="bedrock/anthropic.claude-sonnet-4-20250514-v1:0"

# Or use another model
holmes ask "what is wrong with the user-profile-import pod?" --model="bedrock/<your-model-name>"

See AWS Bedrock Configuration for more details.

  1. Set up API key: 

    export GEMINI_API_KEY="your-gemini-api-key"
export TOOL_SCHEMA_NO_PARAM_OBJECT_IF_NO_PARAMS=true
export MODEL="gemini/<your-gemini-model>"

  2. Create a test pod to investigate: 

    kubectl apply -f https://raw.githubusercontent.com/robusta-dev/kubernetes-demos/main/pending_pods/pending_pod_node_selector.yaml

  3. Ask your first question: 

    holmes ask "what is wrong with the user-profile-import pod?"

# Or specify the model explicitly per command:
holmes ask "what is wrong with the user-profile-import pod?" --model="gemini/<your-gemini-model>"

See Google Gemini Configuration for more details.

  1. Set up credentials: 

    export VERTEXAI_PROJECT="your-project-id"
export VERTEXAI_LOCATION="us-central1"
export GOOGLE_APPLICATION_CREDENTIALS="path/to/service-account-key.json"

  2. Create a test pod to investigate: 

    kubectl apply -f https://raw.githubusercontent.com/robusta-dev/kubernetes-demos/main/pending_pods/pending_pod_node_selector.yaml

  3. Ask your first question: 

    holmes ask "what is wrong with the user-profile-import pod?" --model="vertex_ai/<your-vertex-model>"

See Google Vertex AI Configuration for more details.

  1. Set up API key: No API key required for local Ollama installation.

  2. Create a test pod to investigate: 

    kubectl apply -f https://raw.githubusercontent.com/robusta-dev/kubernetes-demos/main/pending_pods/pending_pod_node_selector.yaml

  3. Ask your first question: 

    holmes ask "what is wrong with the user-profile-import pod?" --model="ollama_chat/<your-model-name>"

    For troubleshooting and advanced options, see Ollama Configuration.

Warning: Ollama can be tricky to configure correctly. We recommend trying HolmesGPT with a hosted model first (like Claude or OpenAI) to ensure everything works before switching to Ollama.

After running the command, HolmesGPT begins its automated investigation, as shown below. image

Once the analysis completes, HolmesGPT provides a clear root-cause summary and fix suggestions. image

Using Multiple Models

If you work with multiple AI providers or model configurations, you can define them in a YAML file and switch between them by name with --model=<name>. See Using Multiple Providers for setup instructions.

Next Steps

Need Help?