aaws - AI-Assisted AWS CLI
aaws - CLI de AWS asistida por IA
Lenguaje natural de entrada, comando de AWS de salida.
pip install aaws -- pypi.org/project/aaws/
Deja de cambiar de contexto para consultar la documentación de AWS. Describe lo que quieres en inglés sencillo y aaws genera, explica y ejecuta de forma segura el comando correcto de 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)Tabla de contenidos
Cómo funciona
Cada invocación de aaws sigue un proceso de seis etapas. Algunas etapas son iniciadas por el usuario (tú las activas) y otras son agénticas (el sistema las maneja de forma autónoma). Esta separación es el principio de diseño fundamental.
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 <───────Uso con Claude Code (MCP)
Usa aaws con tu suscripción a Claude Code: sin claves de API, sin configuración de LLM, sin coste adicional.
En lugar de que aaws llame a un LLM directamente, Claude Code se convierte en el LLM. El servidor MCP de aaws proporciona clasificación de seguridad, ejecución de comandos y formato de salida como herramientas que Claude Code invoca.
Standalone CLI: MCP Mode:
User -> aaws -> LLM (you pay) User -> Claude Code (subscription) -> aaws MCP tools
-> AWS CLI -> AWS CLIConfiguración
Requisito previo: AWS CLI v2 debe estar instalado y configurado (consulta Instalación arriba).
# Install with MCP support
pip install aaws[mcp]
# Register with Claude Code (one-time)
claude mcp add --scope user aaws -- python -m aaws.mcp_serverO añade un archivo .mcp.json con alcance de proyecto (controlado por versiones, compartido con el equipo):
{
"mcpServers": {
"aaws": {
"command": "python",
"args": ["-m", "aaws.mcp_server"]
}
}
}Verifica con /mcp dentro de Claude Code para ver las herramientas listadas.
Herramientas MCP disponibles
Herramienta | Propósito | ¿Requiere LLM? |
| Clasificación de nivel de riesgo (0-3) para cualquier comando de AWS CLI | No (tabla estática) |
| Ejecución segura de subprocesos con inyección de perfil/región | No |
| Detección de forma JSON -> tablas/tarjetas de texto plano | No |
| Explorar niveles de riesgo de comandos conocidos por servicio | No |
| Verificar AWS CLI, perfil activo, región | No |
Ejemplo de conversación en 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(...)Qué cambia respecto a la CLI independiente
Aspecto | CLI independiente | Modo MCP |
Proveedor de LLM | Tú lo configuras (Bedrock/OpenAI) | Suscripción a Claude Code (gratis) |
Traducción de LN | aaws translator.py | LLM de Claude Code |
Memoria de sesión | En proceso, límite de 10 turnos | Integrada en Claude Code (contexto completo) |
Flujos de varios pasos | Un comando a la vez | Claude Code orquesta varios |
Interpretación de errores | Llamada al LLM por error | Claude Code razona sobre stderr |
Configuración |
| Solo registrar servidor MCP |
Ciclo de vida de ingeniería en la nube de AWS (MCP)
Etapa del ciclo de vida | CLI independiente | + MCP con Claude Code |
Descubrimiento | Basado en consultas | + Inventario autónomo, entre servicios |
Aprovisionamiento | Comando único | + Varios pasos con orden de dependencia |
Monitoreo | Consultas instantáneas | + Análisis conversacional |
Solución de problemas | Errores codificados + LLM | + Investigación autónoma de logs/métricas |
Mantenimiento | Borrado/redimensionamiento manual | + El agente encuentra residuos, sugiere optimización |
Seguridad | Paso a través de CLI | + Auditoría de permisos |
Recuperación ante desastres | Copia de seguridad de comando único | + Flujos de DR orquestados |
Flujo de valor: Acciones iniciadas por el usuario vs. Agénticas
Lo siguiente mapea cada actividad en el ciclo de vida de desarrollo y uso según quién es el propietario: el usuario (manual, intencional) o el agente (autónomo, sin intervención).
Fase de configuración
# | Actividad | Propietario | Descripción |
1 | Instalar | Usuario |
|
2 | Ejecutar asistente de configuración | Usuario |
|
3 | Detectar configuración faltante | Agente | Si no existe configuración, imprime mensaje accionable y sale |
4 | Validar esquema de configuración | Agente | Pydantic valida todos los campos, rechaza valores incorrectos |
5 | Resolver | Agente | Sustituye referencias de variables de entorno en valores YAML |
6 | Aplicar anulaciones | Agente | Las variables de entorno anulan la configuración basada en archivos (amigable con CI/CD) |
7 | Detectar presencia de AWS CLI | Agente | Comprueba |
Flujo de comando único
# | Actividad | Propietario | Descripción |
8 | Escribir solicitud en lenguaje natural | Usuario |
|
9 | Resolver perfil + región de AWS | Agente | Fusiona flags |
10 | Construir prompt de LLM con contexto | Agente | Inyecta prompt del sistema + contexto de perfil/región + solicitud del usuario |
11 | Llamar al LLM mediante llamada a herramienta | Agente | Envía esquema de herramienta estructurado, fuerza el uso de herramientas (sin texto libre) |
12 | Validar que el comando empieza con | Agente | Rechaza salidas no relacionadas con AWS alucinatorias |
13 | Reintento automático en comando inválido | Agente | Envía instrucción correctiva, reintenta una vez, luego falla con error claro |
14 | Devolver aclaración si es ambiguo | Agente | Si la solicitud es vaga, hace UNA pregunta aclaratoria en lugar de adivinar |
15 | Clasificar nivel de riesgo (tabla estática) | Agente | Coincidencia de prefijo más largo contra más de 100 patrones de comandos conocidos |
16 | Fallback al nivel asignado por LLM | Agente | Los comandos desconocidos usan la evaluación de riesgo del LLM |
17 | Comprobar perfil protegido | Agente | Bloquea todas las escrituras en |
18 | Mostrar comando + explicación | Agente | Muestra el comando generado con explicación en inglés sencillo |
19 | Confirmar o cancelar ejecución | Usuario | Nivel 0: auto-ejecución. Nivel 1: s/n. Nivel 2: escribe "yes". Nivel 3: rechazado. |
20 | Ofrecer | Agente | Para comandos destructivos de EC2, ofrece validar con |
21 | Ejecutar mediante subproceso | Agente |
|
22 | Detectar forma de salida | Agente | Inspecciona JSON: lista -> tabla, dict -> tarjeta, vacío -> "No hay resultados." |
23 | Renderizar salida formateada | Agente | Tablas enriquecidas con sugerencias de columnas por tipo de recurso, o JSON con resaltado de sintaxis |
24 | Clasificar error en fallo | Agente | Coincidencias de Regex para errores de credenciales, permisos, recursos |
25 | Proporcionar corrección codificada para auth | Agente | Token expirado -> |
26 | LLM interpreta errores de recursos | Agente | Envía comando fallido + stderr al LLM para pasos de recuperación en lenguaje sencillo |
Flujo de sesión interactiva
# | Actividad | Propietario | Descripción |
27 | Iniciar sesión | Usuario |
|
28 | Mostrar encabezado de sesión | Agente | Muestra perfil activo, región, instrucciones de salida |
29 | Escribir solicitudes de seguimiento | Usuario | Entrada conversacional haciendo referencia al contexto previo |
30 | Mantener historial de conversación | Agente | Añade cada intercambio, limitado a los últimos 10 para contexto del LLM |
31 | Traducir con contexto de historial | Agente | El LLM ve la conversación previa para refinamiento de varios turnos |
32 | Pipeline de seguridad completo por turno | Agente | Cada comando pasa por clasificar -> puerta -> ejecutar -> formatear |
33 | Salir de la sesión | Usuario | Escribe |
34 | Manejar Ctrl+C con elegancia | Agente | Captura KeyboardInterrupt, imprime "Adiós.", sin traza de pila |
Flujos de utilidad
# | Actividad | Propietario | Descripción | |
35 | Explicar comando existente | Usuario |
| |
36 | LLM genera explicación | Agente | Describe qué hace el comando, cada flag y advertencias de seguridad | |
37 | Ver configuración resuelta | Usuario |
| |
38 | Usar | Usuario | `aaws --raw "lista mis buckets" | jq '.Buckets[].Name'` |
39 | Usar | Usuario | Muestra el comando generado sin ejecutar | |
40 | Anular rechazo de nivel 3 | Usuario |
|
CI/CD y automatización
# | Actividad | Propietario | Descripción | |
41 | Configurar solo mediante variables de entorno | Usuario | Establecer | |
42 | Canalizar salida cruda a herramientas | Usuario | `aaws --raw "..." | jq ...` para consumo mediante scripts |
43 | Pruebas en push (GitHub Actions) | Agente | Lint (ruff) + comprobación de tipos (mypy) + pytest en Python 3.11-3.13 | |
44 | Publicar en PyPI en etiqueta | Agente |
|
Instalación
Paso 1: Instalar AWS CLI v2
aaws requiere que AWS CLI esté instalado y en tu PATH. Delega todas las operaciones de AWS al comando aws.
macOS:
brew install awscliWindows:
Descarga y ejecuta el instalador desde https://awscli.amazonaws.com/AWSCLIV2.msi
O mediante 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/installVerificar:
aws --version
# aws-cli/2.x.x Python/3.x.x ...Paso 2: Configurar credenciales de AWS
Necesitas al menos un perfil de AWS configurado con credenciales válidas.
Opción A: Claves de acceso IAM (más simple)
aws configureSe te pedirá:
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]: jsonOpción B: AWS SSO (recomendado para organizaciones)
aws configure ssoSigue el flujo de inicio de sesión del navegador. Luego activa la sesión:
aws sso login --profile your-profile-nameOpción C: Variables de entorno (CI/CD)
export AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
export AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
export AWS_DEFAULT_REGION=us-east-1Verificar que las credenciales funcionan:
aws sts get-caller-identity
# Should return your account ID, ARN, and user IDPaso 3: Instalar aaws
Requisitos: Python 3.11+, AWS CLI v2 (configurado arriba)
El paquete está publicado en pypi.org/project/aaws/.
CLI independiente (necesita un proveedor de LLM — Bedrock u OpenAI):
pip install aawsCon soporte para Claude Code MCP (usa tu suscripción de Anthropic, no se necesita clave de API):
pip install aaws[mcp]
claude mcp add --scope user aaws -- python -m aaws.mcp_serverVerifica la instalación:
aaws --help
aws sts get-caller-identity # confirm AWS creds workActualizar a la última versión
pip install --upgrade aawsInstalar desde el código fuente (desarrollo)
git clone https://github.com/farmountain/ai_aws_cli.git
cd ai_aws_cli
pip install -e ".[dev,mcp]"Inicio rápido
1. Configurar
aaws config initEl asistente te guía a través de:
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. Ejecuta tu primer comando
aaws "list my S3 buckets"3. Prueba más comandos
# 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'Configuración
Ubicación del archivo de configuración
SO | Ruta |
Linux/macOS |
|
Windows |
|
Referencia completa de configuración
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: trueAnulaciones de variables de entorno
Cada campo de configuración puede ser anulado con variables de entorno con el prefijo AAWS_. Útil para CI/CD donde la configuración de archivos es poco práctica
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