Cloud-Pilot ☁️

Terminal-native, agentic CLI for orchestrating AWS infrastructure via natural language

Cloud-Pilot is an AI-powered command-line tool that translates natural language requests into AWS operations. It acts as a semantic bridge between human intent and the AWS CLI, powered by Claude 3.5 Sonnet via AWS Bedrock.

✨ Features

• Natural Language Interface: Execute AWS operations using plain English
• Safety First: Read-only by default with explicit confirmation for destructive operations
• Transparent Planning: Review and approve execution plans before any changes
• Context Aware: Automatically detects AWS account, region, and local project context
• Audit Trail: Complete history of all operations in ~/.cloud-pilot/history.jsonl
• OODA Loop Architecture: Observe → Orient → Decide → Act state machine
• Cost Awareness: Optional budget caps and cost estimation
• Multi-Region Support: Works across all AWS regions

🚀 Quick Start

Prerequisites

• Node.js v20 or higher
• AWS CLI v2 installed and configured
• AWS Credentials with appropriate permissions
• AWS Bedrock access in your region (for Claude 3.5 Sonnet)

Installation

# Install dependencies
npm install

# Build the project
npm run build

# Link for local development
npm link

# Or install globally (after publishing)
npm install -g @cloud-pilot/cli

First Run

# Initialize and verify setup
cloud-pilot init

This will check:

• ✅ AWS CLI availability
• ✅ AWS credentials validity
• ✅ Bedrock access to Claude models

📖 Usage

Check Environment Status

cloud-pilot status

Displays:

• AWS account and region information
• Running EC2 and RDS instances
• S3 bucket count
• Monthly spend to date

Execute Natural Language Commands

# List resources
cloud-pilot "List all running EC2 instances"
cloud-pilot "Show me my S3 buckets"

# With explicit run command
cloud-pilot run "Find unused Elastic IPs"

# Dry run (preview without executing)
cloud-pilot --dry-run "Stop all t3.micro instances"

# Specify region
cloud-pilot --region us-west-2 "List Lambda functions"

# Verbose output
cloud-pilot --verbose "Create a new S3 bucket named my-data-bucket"

# JSON output for scripting
cloud-pilot --json "Describe my VPCs"

View Execution History

cloud-pilot history

Shows past commands with:

• Timestamp
• Natural language prompt
• Number of steps executed
• Success/failure status

🔐 Safety Features

Destructive Operation Warnings

Cloud-Pilot automatically detects dangerous operations:

• delete, terminate, stop, truncate, destroy, remove

These operations:

1. Are clearly marked with ⚠️ in the plan
2. Require explicit user confirmation
3. May require secondary confirmation with resource ID

Budget Protection

Configure a daily spending cap in ~/.cloud-pilot/config.json:

{
  "maxDailySpend": 50.00,
  "defaultRegion": "us-east-1",
  "outputFormat": "text",
  "verbose": false
}

If estimated costs exceed the cap, execution is blocked.

Audit Logging

All operations are logged to ~/.cloud-pilot/history.jsonl:

{"ts":"2025-11-20T12:00:00.000Z","user":"arn:aws:iam::123456789012:user/admin","prompt":"List running instances","plan":{...},"result":"success","exitCode":0}

🏗️ Architecture

OODA Loop State Machine

OBSERVE → ORIENT → DECIDE → ACT
   ↓         ↓        ↓       ↓
Context  Reasoning  Plan   Execute
Gather   (Claude)   Review  Commands

Technology Stack

• Runtime: Node.js v20+ (ES Modules)
• Language: TypeScript (Strict Mode)
• CLI Framework: Commander.js
• LLM: Claude 3.5 Sonnet via AWS Bedrock
• AWS SDK: Modular AWS SDK v3
• State Management: XState v5
• Validation: Zod
• UI: Chalk, cli-table3, inquirer

🛠️ Development

Project Structure

cloud-pilot/
├── src/
│   ├── cli.ts                 # Main CLI entry point
│   ├── commands/              # Command implementations
│   │   ├── init.ts
│   │   ├── status.ts
│   │   ├── run.ts
│   │   └── history.ts
│   ├── modules/               # Core functionality
│   │   ├── bedrock-client.ts  # Claude integration
│   │   ├── context-gatherer.ts # AWS context
│   │   ├── executor.ts        # Command execution
│   │   ├── safety-guards.ts   # Safety checks
│   │   ├── history-logger.ts  # Audit logging
│   │   ├── plan-schema.ts     # Zod schemas
│   │   └── state-machine.ts   # XState OODA loop
│   ├── types/                 # TypeScript definitions
│   └── utils/                 # Utilities
├── dist/                      # Compiled output
├── package.json
├── tsconfig.json
└── SPEC.md                    # Technical specification

Build Commands

# Install dependencies
npm install

# Build once
npm run build

# Watch mode (rebuild on changes)
npm run dev

# Run locally
npm start -- status
npm start -- "List EC2 instances"

🔧 Configuration

Configuration is stored in ~/.cloud-pilot/config.json:

{
  "defaultRegion": "us-east-1",
  "defaultProfile": "default",
  "outputFormat": "text",
  "maxDailySpend": 100.00,
  "verbose": false
}

📋 Examples

Common Operations

# Resource management
cloud-pilot "List all S3 buckets"
cloud-pilot "Show running EC2 instances with their IPs"
cloud-pilot "Find unused EBS volumes"

# Information gathering
cloud-pilot "What's my current AWS spending this month?"
cloud-pilot "List all Lambda functions in us-west-2"
cloud-pilot "Show me my RDS instances"

# Destructive operations (with confirmation)
cloud-pilot "Stop all t3.micro instances"
cloud-pilot "Delete unused Elastic IPs"
cloud-pilot "Terminate instance i-1234567890abcdef0"

# Preview before executing
cloud-pilot --dry-run "Delete all unattached EBS volumes"

🔒 Permissions Required

Cloud-Pilot requires AWS permissions for:

Bedrock (Required)

• bedrock:InvokeModel on Claude models

Core Services (Required)

• sts:GetCallerIdentity

Status Command (Optional)

• ce:GetCostAndUsage (Cost Explorer)
• ec2:DescribeInstances
• rds:DescribeDBInstances
• s3:ListBuckets

Execution (As Needed)

• Permissions for specific operations requested via natural language

⚠️ Important Notes

1. Bedrock Access: Ensure Claude 3.5 Sonnet is available in your AWS region
2. Cost Explorer: May not be available in all regions/accounts
3. Dry Run: Always test with --dry-run first for destructive operations
4. Audit Trail: Review ~/.cloud-pilot/history.jsonl regularly
5. Budget Caps: Set maxDailySpend to prevent unexpected costs

🗺️ Roadmap

v1.0 (Current)

• ✅ Core CLI with natural language interface
• ✅ OODA loop state machine
• ✅ Safety guardrails and confirmations
• ✅ Audit logging
• ✅ Status command

Future Enhancements

• Multi-agent architecture (specialized agents)
• Interactive REPL mode
• Cost estimation with Pricing API
• Architecture diagram generation (Mermaid)
• Drift detection for Terraform
• Plugin system for custom tools

📄 License

MIT

🤝 Contributing

Contributions are welcome! Please see SPEC.md for technical details.

🐛 Issues & Feedback

Report issues at: https://github.com/your-org/cloud-pilot/issues

⚡ Quick Reference

# Global flags
--profile <name>   # AWS profile
--region <region>  # AWS region override
--json            # JSON output
--dry-run         # Preview only
--verbose         # Debug output

# Commands
cloud-pilot init              # Setup and verify
cloud-pilot status            # Environment health check
cloud-pilot run "<prompt>"    # Execute natural language command
cloud-pilot "<prompt>"        # Shorthand for run
cloud-pilot history          # View past operations

Built with ❤️ using Claude 3.5 Sonnet