Skip to main content
This tutorial walks you through installing Clanker CLI and running your first natural language infrastructure query.

​
What you’ll learn

By the end of this tutorial, you’ll be able to:
  • Install and configure Clanker CLI
  • Connect to your AWS account
  • Run natural language queries about your infrastructure
  • Understand the AI-powered investigation flow
1

Install Clanker CLI

Install Clanker using Homebrew (recommended) or from source:
# Homebrew installation (macOS)
brew tap clankercloud/tap
brew install clanker
Alternatively, build from source:
# Clone and build from source
git clone https://github.com/bgdnvk/clanker.git
cd clanker
make install
Verify the installation:
clanker --help
2

Configure AI provider

Clanker uses AI to analyze your infrastructure questions. Create a configuration file:
# Create config from example
cp .clanker.example.yaml ~/.clanker.yaml
Edit ~/.clanker.yaml and configure your AI provider. Gemini API is recommended for getting started:
ai:
  default_provider: gemini-api
  providers:
    gemini-api:
      model: gemini-2.5-flash
      api_key_env: GEMINI_API_KEY
Set your API key:
export GEMINI_API_KEY="your-api-key-here"
Alternatively, you can use OpenAI (gpt-5), Anthropic (Claude), or AWS Bedrock. See the AI configuration guide for details.
3

Connect to AWS

Clanker uses your existing AWS CLI profiles. Configure a profile if you haven’t already:
# Create AWS profile
aws configure --profile my-profile
Enter your AWS credentials when prompted. Verify the profile works:
aws sts get-caller-identity --profile my-profile
Update your Clanker config to use this profile:
infra:
  default_provider: aws
  default_environment: dev
  
  aws:
    environments:
      dev:
        profile: my-profile
        region: us-east-1
4

Run your first query

Now you’re ready to ask Clanker about your infrastructure. Start with a simple question:
clanker ask "What EC2 instances are running?"
Clanker will:
  1. Analyze your question using semantic understanding
  2. Determine which AWS operations to execute
  3. Call the AWS CLI in parallel to gather data
  4. Synthesize a comprehensive markdown response
Example output:
# EC2 Instances Overview

You have **3 running instances** in us-east-1:

## Production Instances

### web-server-prod (i-0a1b2c3d4e5f6)
- **State**: running
- **Type**: t3.medium
- **Launch Time**: 2026-02-15 14:23:11
- **Private IP**: 10.0.1.45
- **Public IP**: 54.234.123.45
- **Security Groups**: web-sg, ssh-sg

### api-server-prod (i-9z8y7x6w5v4u3)
- **State**: running
- **Type**: t3.large
- **Launch Time**: 2026-02-20 09:15:33
- **Private IP**: 10.0.1.67
- **Security Groups**: api-sg

## Development Instances

### dev-test (i-1a2b3c4d5e6f7)
- **State**: running
- **Type**: t3.small
- **Launch Time**: 2026-02-28 16:42:19
- **Private IP**: 10.0.2.12
5

Try more complex queries

Clanker supports natural language questions across your entire infrastructure:
# Lambda functions
clanker ask "Show me lambda functions with high error rates"

# RDS databases
clanker ask "What's the current RDS instance status?"

# Cost analysis
clanker ask "Which services are costing the most this month?"

# Security
clanker ask "Show me security groups with port 22 open to the world"

# Recent changes
clanker ask "What resources were created in the last 24 hours?"
Use the --debug flag to see what operations Clanker is running:
clanker ask "what lambdas do we have?" --debug
6

Understanding the investigation flow

When you run a query, Clanker follows this intelligent process:1. Semantic Analysis
  • Extracts intent, urgency, and target services from your question
  • Identifies required data types (logs, metrics, resources)
2. Agent Selection
  • Uses a decision tree to determine which specialized agents to execute
  • Selects appropriate AWS operations (EC2, Lambda, RDS, CloudWatch, etc.)
3. Parallel Execution
  • Runs AWS CLI operations in parallel with dependency ordering
  • Shares results across agents for comprehensive context
4. Response Synthesis
  • Combines all gathered data into a unified context
  • Uses AI to generate a clear, actionable markdown response
This multi-stage pipeline ensures you get accurate, comprehensive answers without manual AWS console navigation.

​
Next steps

Creating infrastructure

Learn how to use Clanker’s maker mode to generate and apply infrastructure plans

Kubernetes setup

Set up and manage Kubernetes clusters with Clanker

Monitoring resources

Monitor your infrastructure health and metrics

Configuration guide

Deep dive into Clanker configuration options

​
Troubleshooting

If you see authentication errors:
# Verify your AWS profile works
aws sts get-caller-identity --profile my-profile

# If using SSO, login first
aws sso login --profile my-profile
Make sure your profile name in ~/.clanker.yaml matches your AWS CLI profile.
If you see AI API errors:
  • Verify your API key is set: echo $GEMINI_API_KEY
  • Check your API quota/limits in your provider dashboard
  • Try a different model (e.g., switch from gemini-2.5-flash to gemini-3-pro-preview)
If queries return no results:
  • Verify you’re querying the correct AWS region
  • Check that resources exist: aws ec2 describe-instances --profile my-profile
  • Try the --discovery flag for comprehensive infrastructure scanning

Build docs developers (and LLMs) love

Get started for freeTalk to us