aaws - AI-Assisted AWS CLI
aaws - AI 辅助的 AWS CLI
自然语言输入,AWS 命令输出。
pip install aaws -- pypi.org/project/aaws/
无需再频繁切换到 AWS 文档。用简单的英语描述您的需求,aaws 即可生成、解释并安全地执行正确的 AWS CLI 命令。
$ aaws "list my S3 buckets"
Command: aws s3api list-buckets --output json
Lists all S3 buckets in your account.
Name CreationDate
my-app-assets 2024-03-15T10:22:00+00:00
my-logs-bucket 2024-06-01T08:00:00+00:00
staging-uploads 2025-01-10T14:30:00+00:00
3 result(s)目录
工作原理
每个 aaws 调用都遵循一个六阶段流水线。有些阶段是用户发起的(由您触发),而另一些是代理执行的(系统自动处理)。这种分离是核心设计原则。
YOU aaws (AGENT)
─── ────────────
Type natural language ──────────> LLM translates to AWS CLI command
Agent classifies risk tier (0-3)
Agent selects safety gate
Review command + confirm ───────> Agent executes via subprocess
Agent detects output shape
Agent formats as table/card/JSON
Read formatted results <────────
(on error) Agent classifies error
(on error) Agent generates recovery advice
Read error + suggestion <───────与 Claude Code (MCP) 配合使用
将 aaws 与您的 Claude Code 订阅配合使用 — 无需 API 密钥,无需 LLM 配置,零额外成本。
aaws 不再直接调用 LLM,而是由 Claude Code 充当 LLM。aaws MCP 服务器提供安全分类、命令执行和输出格式化工具,供 Claude Code 调用。
Standalone CLI: MCP Mode:
User -> aaws -> LLM (you pay) User -> Claude Code (subscription) -> aaws MCP tools
-> AWS CLI -> AWS CLI设置
前提条件:必须安装并配置 AWS CLI v2(参见上文 安装)。
# Install with MCP support
pip install aaws[mcp]
# Register with Claude Code (one-time)
claude mcp add --scope user aaws -- python -m aaws.mcp_server或者添加一个项目范围的 .mcp.json(版本控制,与团队共享):
{
"mcpServers": {
"aaws": {
"command": "python",
"args": ["-m", "aaws.mcp_server"]
}
}
}在 Claude Code 中使用 /mcp 进行验证,查看列出的工具。
可用的 MCP 工具
工具 | 用途 | 需要 LLM? |
| 任何 AWS CLI 命令的风险等级分类 (0-3) | 否(静态表) |
| 带有配置文件/区域注入的安全子进程执行 | 否 |
| JSON 形状检测 -> 纯文本表格/卡片 | 否 |
| 按服务浏览已知的命令风险等级 | 否 |
| 验证 AWS CLI、活动配置文件、区域 | 否 |
Claude Code 中的对话示例
You: List my S3 buckets in us-west-2
Claude Code:
1. Calls check_aws_environment() -> {aws_cli_available: true, active_profile: "default"}
2. Calls classify_aws_command("aws s3api list-buckets --output json")
-> {tier: 0, tier_label: "Read-only", should_confirm: false}
3. Calls execute_aws_command("aws s3api list-buckets --output json", region="us-west-2")
-> {stdout: '{"Buckets": [...]}', success: true}
4. Calls format_aws_output(stdout)
-> Formatted table with bucket names and dates
You: Now delete the one named old-logs
Claude Code:
1. Calls classify_aws_command("aws s3 rb s3://old-logs --force")
-> {tier: 2, tier_label: "Destructive", should_confirm: true}
2. Asks: "This is a destructive operation (tier 2). Delete bucket old-logs?"
3. You confirm
4. Calls execute_aws_command(...)与独立 CLI 的区别
方面 | 独立 CLI | MCP 模式 |
LLM 提供商 | 您配置 (Bedrock/OpenAI) | Claude Code 订阅(免费) |
自然语言翻译 | aaws translator.py | Claude Code LLM |
会话记忆 | 进程内,10 轮限制 | Claude Code 内置(完整上下文) |
多步工作流 | 一次一个命令 | Claude Code 编排多个 |
错误解释 | 每个错误调用一次 LLM | Claude Code 对 stderr 进行推理 |
配置 | 需要 | 只需注册 MCP 服务器 |
AWS 云工程生命周期 (MCP)
生命周期阶段 | 独立 CLI | + MCP 与 Claude Code |
发现 | 基于查询 | + 自主库存,跨服务 |
配置 | 单命令 | + 带有依赖排序的多步操作 |
监控 | 快照查询 | + 对话式深入分析 |
故障排除 | 硬编码 + LLM 错误 | + 自主日志/指标调查 |
维护 | 手动删除/调整大小 | + 代理发现浪费,建议优化 |
安全 | CLI 透传 | + 权限审计 |
灾难恢复 | 单命令备份 | + 编排的 DR 工作流 |
价值流:用户发起 vs 代理执行
下表将开发和使用生命周期中的每项活动映射到其所有者:用户(手动、有意)或代理(自主、零接触)。
设置阶段
# | 活动 | 所有者 | 描述 |
1 | 安装 | 用户 |
|
2 | 运行配置向导 | 用户 |
|
3 | 检测缺失配置 | 代理 | 如果不存在配置,打印可操作消息并退出 |
4 | 验证配置模式 | 代理 | Pydantic 验证所有字段,拒绝错误值 |
5 | 解析配置中的 | 代理 | 替换 YAML 值中的环境变量引用 |
6 | 应用 | 代理 | 环境变量覆盖基于文件的配置(对 CI/CD 友好) |
7 | 检测 AWS CLI 是否存在 | 代理 | 启动时检查 PATH 中的 |
单次命令流
# | 活动 | 所有者 | 描述 |
8 | 编写自然语言请求 | 用户 |
|
9 | 解析 AWS 配置文件 + 区域 | 代理 | 合并 |
10 | 构建带有上下文的 LLM 提示 | 代理 | 注入系统提示 + 配置文件/区域上下文 + 用户请求 |
11 | 通过工具/函数调用 LLM | 代理 | 发送结构化工具模式,强制使用工具(无自由文本) |
12 | 验证命令以 | 代理 | 拒绝幻觉产生的非 AWS 输出 |
13 | 无效命令自动重试 | 代理 | 发送纠正指令,重试一次,然后以清晰的错误失败 |
14 | 如果模糊则返回澄清 | 代理 | 如果请求模糊,提出一个澄清问题而不是猜测 |
15 | 分类风险等级(静态表) | 代理 | 针对 100 多个已知命令模式的最长前缀匹配 |
16 | 回退到 LLM 分配的等级 | 代理 | 未知命令使用 LLM 的风险评估 |
17 | 检查受保护的配置文件 | 代理 | 阻止对 |
18 | 显示命令 + 解释 | 代理 | 显示生成的命令及纯英语解释 |
19 | 确认或取消执行 | 用户 | 等级 0:自动运行。等级 1:y/n。等级 2:输入 "yes"。等级 3:拒绝。 |
20 | 为 EC2 提供 | 代理 | 对于破坏性 EC2 命令,首先提供 |
21 | 通过子进程执行 | 代理 |
|
22 | 检测输出形状 | 代理 | 检查 JSON:列表 -> 表格,字典 -> 卡片,空 -> "No results." |
23 | 渲染格式化输出 | 代理 | 带有资源类型列提示的丰富表格,或语法高亮的 JSON |
24 | 失败时分类错误 | 代理 | 针对凭证、权限、资源错误的正则表达式匹配 |
25 | 提供身份验证的硬编码修复 | 代理 | 令牌过期 -> |
26 | LLM 解释资源错误 | 代理 | 将失败的命令 + stderr 发送给 LLM 以获取纯英语恢复步骤 |
交互式会话流
# | 活动 | 所有者 | 描述 |
27 | 启动会话 | 用户 |
|
28 | 显示会话标题 | 代理 | 显示活动配置文件、区域、退出说明 |
29 | 输入后续请求 | 用户 | 引用先前上下文的对话式输入 |
30 | 维护对话历史 | 代理 | 追加每次交换,限制为 LLM 上下文的最后 10 条 |
31 | 使用历史上下文翻译 | 代理 | LLM 查看先前对话以进行多轮优化 |
32 | 每轮完整的安全流水线 | 代理 | 每个命令都经过分类 -> 门控 -> 执行 -> 格式化 |
33 | 退出会话 | 用户 | 输入 |
34 | 优雅处理 Ctrl+C | 代理 | 捕获 KeyboardInterrupt,打印 "Goodbye.",无堆栈跟踪 |
实用流程
# | 活动 | 所有者 | 描述 | |
35 | 解释现有命令 | 用户 |
| |
36 | LLM 生成解释 | 代理 | 描述命令的功能、每个标志及安全注意事项 | |
37 | 查看已解析的配置 | 用户 |
| |
38 | 使用 | 用户 | `aaws --raw "list my buckets" | jq '.Buckets[].Name'` |
39 | 使用 | 用户 | 显示生成的命令而不执行 | |
40 | 覆盖等级 3 拒绝 | 用户 |
|
CI/CD 和自动化
# | 活动 | 所有者 | 描述 | |
41 | 仅通过环境变量配置 | 用户 | 设置 | |
42 | 将原始输出通过管道传给工具 | 用户 | `aaws --raw "..." | jq ...` 用于脚本消费 |
43 | 推送时测试 (GitHub Actions) | 代理 | 在 Python 3.11-3.13 上进行 Lint (ruff) + 类型检查 (mypy) + pytest | |
44 | 在标签上发布到 PyPI | 代理 |
|
安装
第 1 步:安装 AWS CLI v2
aaws 要求安装 AWS CLI 并将其添加到您的 PATH 中。它将所有 AWS 操作委托给 aws 命令。
macOS:
brew install awscliWindows:
从 https://awscli.amazonaws.com/AWSCLIV2.msi 下载并运行安装程序
或者通过 winget:
winget install Amazon.AWSCLILinux (x86_64):
curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip"
unzip awscliv2.zip
sudo ./aws/install验证:
aws --version
# aws-cli/2.x.x Python/3.x.x ...第 2 步:配置 AWS 凭证
您至少需要配置一个具有有效凭证的 AWS 配置文件。
选项 A:IAM 访问密钥(最简单)
aws configure系统将提示您输入:
AWS Access Key ID [None]: AKIAIOSFODNN7EXAMPLE
AWS Secret Access Key [None]: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
Default region name [None]: us-east-1
Default output format [None]: json选项 B:AWS SSO(组织推荐)
aws configure sso按照浏览器登录流程操作。然后激活会话:
aws sso login --profile your-profile-name选项 C:环境变量 (CI/CD)
export AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
export AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
export AWS_DEFAULT_REGION=us-east-1验证凭证是否有效:
aws sts get-caller-identity
# Should return your account ID, ARN, and user ID第 3 步:安装 aaws
要求: Python 3.11+,AWS CLI v2(如上配置)
该包发布在 pypi.org/project/aaws/。
独立 CLI(需要 LLM 提供商 — Bedrock 或 OpenAI):
pip install aaws支持 Claude Code MCP(使用您的 Anthropic 订阅,无需 API 密钥):
pip install aaws[mcp]
claude mcp add --scope user aaws -- python -m aaws.mcp_server验证安装:
aaws --help
aws sts get-caller-identity # confirm AWS creds work升级到最新版本
pip install --upgrade aaws从源码安装(开发)
git clone https://github.com/farmountain/ai_aws_cli.git
cd ai_aws_cli
pip install -e ".[dev,mcp]"快速入门
1. 配置
aaws config init向导将引导您完成:
aaws configuration wizard
LLM provider [bedrock/openai] (bedrock):
Bedrock model ID (anthropic.claude-3-5-haiku-20241022-v1:0):
Default AWS profile (default):
Default AWS region (us-east-1):
Configuration saved to ~/.config/aaws/config.yaml
Run aaws "list my S3 buckets" to test.2. 运行您的第一个命令
aaws "list my S3 buckets"3. 尝试更多命令
# Read-only (auto-executes, no confirmation)
aaws "show my running EC2 instances in us-west-2"
aaws "how many Lambda functions do I have"
aaws "get the details of my RDS database named prod-db"
# Write operations (asks y/n)
aaws "create an S3 bucket named my-new-bucket in us-east-1"
aaws "tag instance i-abc123 with Environment=staging"
# Preview without executing
aaws --dry-run "terminate instance i-abc123"
# Explain an existing command
aaws explain "aws iam attach-role-policy --role-name MyRole --policy-arn arn:aws:iam::aws:policy/ReadOnlyAccess"
# Raw output for scripting
aaws --raw "list my S3 buckets" | jq '.Buckets[].Name'配置
配置文件位置
操作系统 | 路径 |
Linux/macOS |
|
Windows |
|
完整配置参考
llm:
provider: bedrock # "bedrock" or "openai"
model: anthropic.claude-3-5-haiku-20241022-v1:0
api_key: ${OPENAI_API_KEY} # Only for OpenAI; supports ${ENV_VAR} syntax
temperature: 0.1 # Low for deterministic output
timeout: 30 # Seconds
aws:
default_profile: default
default_region: us-east-1
safety:
auto_execute_tier: 0 # Auto-run commands at or below this tier (0=read-only)
protected_profiles: # Glob patterns — all writes blocked on these profiles
- "prod-*"
- "production"
output:
format: auto # "auto" detects tables/cards/JSON
raw: false # true = always output raw JSON
color: true环境变量覆盖
每个配置字段都可以用 AAWS_ 前缀的环境变量覆盖。对于无法使用文件配置的 CI/CD 非常有用。
环境变量 | 配置字段 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
命令参考
aaws "<request>"
将自然语言翻译为 AWS CLI 命令并运行。
aaws [OPTIONS] "<natural language request>"标志 | 描述 |
| 为此调用覆盖 AWS 配置文件 |
| 为此调用覆盖 AWS 区域 |
| 输出原始 JSON(无表格,无格式化) |
| 显示生成的命令而不执行 |
| 自动确认等级 1-2 命令(跳过交互式提示) |
| 覆盖等级 3 灾难性操作拒绝 |
`aaws explain ""
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Related MCP Connectors
Hosted MCP server for live public-data APIs and Skills for AI agents.
Remote MCP server for supportsheep: run AI interviews and manage support content for your blog.
Remote MCP server for supportsheep: run AI interviews and manage support content for your blog.
An MCP server that gives your AI access to the source code and docs of all public github repos