aaws - AI-помощник для AWS CLI

PyPI version Python 3.11+ License: Apache 2.0

Естественный язык на входе, команда 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. MCP-сервер aaws предоставляет классификацию рисков, выполнение команд и форматирование вывода в качестве инструментов, которые вызывает 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"]
    }
  }
}

Проверьте с помощью /mcp внутри Claude Code, чтобы увидеть список инструментов.

Доступные инструменты MCP

Инструмент	Назначение	Нужна LLM?
`classify_aws_command`	Классификация уровня риска (0-3) для любой команды AWS CLI	Нет (статическая таблица)
`execute_aws_command`	Безопасное выполнение подпроцесса с внедрением профиля/региона	Нет
`format_aws_output`	Определение структуры JSON -> текстовые таблицы/карточки	Нет
`list_safety_tiers`	Просмотр известных уровней риска команд по сервисам	Нет
`check_aws_environment`	Проверка 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 (бесплатно)
Перевод NL	aaws translator.py	LLM Claude Code
Память сессии	Внутри процесса, лимит 10 шагов	Встроено в Claude Code (полный контекст)
Многошаговые рабочие процессы	Одна команда за раз	Claude Code координирует несколько
Интерпретация ошибок	Вызов LLM на каждую ошибку	Claude Code анализирует stderr
Конфигурация	Требуется `aaws config init`	Просто зарегистрируйте MCP-сервер

Жизненный цикл облачной инженерии AWS (MCP)

Этап жизненного цикла	Автономный CLI	+ MCP с Claude Code
Обнаружение	На основе запросов	+ Автономная инвентаризация, кросс-сервисы
Подготовка	Одиночная команда	+ Многошаговая с учетом зависимостей
Мониторинг	Снимочные запросы	+ Диалоговое углубление
Устранение неполадок	Жестко закодированные + ошибки LLM	+ Автономное исследование логов/метрик
Обслуживание	Ручное удаление/изменение размера	+ Агент находит отходы, предлагает оптимизацию
Безопасность	Проброс CLI	+ Аудит разрешений
Аварийное восстановление	Одиночная команда резервного копирования	+ Оркестрированные рабочие процессы DR

Поток ценности: действия пользователя vs действия агента

Ниже приведено сопоставление каждого действия в жизненном цикле разработки и использования с тем, кто им владеет: пользователь (вручную, намеренно) или агент (автономно, без участия).

Фаза настройки

#	Действие	Владелец	Описание
1	Установка `aaws`	Пользователь	`pip install aaws`
2	Запуск мастера конфигурации	Пользователь	`aaws config init` — выбор провайдера, модели, профиля, региона
3	Обнаружение отсутствия конфига	Агент	Если конфига нет, выводит сообщение и завершает работу
4	Проверка схемы конфига	Агент	Pydantic проверяет все поля, отклоняет неверные значения
5	Разрешение `${ENV_VAR}` в конфиге	Агент	Подставляет значения переменных окружения в YAML
6	Применение переопределений `AAWS_*`	Агент	Переменные окружения переопределяют конфиг (удобно для CI/CD)
7	Обнаружение AWS CLI	Агент	Проверяет `aws` в PATH при запуске; завершается с ссылкой на установку

Поток одиночной команды

#	Действие	Владелец	Описание
8	Написание запроса на естественном языке	Пользователь	`aaws "show my running EC2 instances"`
9	Разрешение профиля и региона AWS	Агент	Объединяет флаги `--profile`/`--region` > конфиг > сессия boto3 > откат
10	Создание промпта LLM с контекстом	Агент	Внедряет системный промпт + контекст профиля/региона + запрос пользователя
11	Вызов LLM через вызов инструментов	Агент	Отправляет структурированную схему инструментов, принудительно использует их
12	Проверка, что команда начинается с `aws`	Агент	Отклоняет галлюцинации, не являющиеся выводом AWS
13	Автоповтор при неверной команде	Агент	Отправляет корректирующую инструкцию, повторяет один раз, затем выдает ошибку
14	Возврат уточнения, если неоднозначно	Агент	Если запрос расплывчат, задает ОДИН уточняющий вопрос вместо угадывания
15	Классификация уровня риска (статическая таблица)	Агент	Поиск по префиксу среди 100+ известных шаблонов команд
16	Откат к уровню, назначенному LLM	Агент	Неизвестные команды используют оценку риска от LLM
17	Проверка защищенного профиля	Агент	Блокирует все операции записи на `prod-*` или glob-шаблонах пользователя
18	Показ команды + объяснение	Агент	Отображает сгенерированную команду с объяснением на обычном языке
19	Подтверждение или отмена выполнения	Пользователь	Уровень 0: автозапуск. Уровень 1: y/n. Уровень 2: введите "yes". Уровень 3: отказ. `--yes` автоподтверждает 1-2
20	Предложение `--dry-run` для EC2	Агент	Для деструктивных команд EC2 предлагает сначала проверить через `--dry-run`
21	Выполнение через подпроцесс	Агент	`shlex.split()` + `subprocess.run(shell=False)` — инъекции невозможны
22	Определение структуры вывода	Агент	Анализ JSON: список -> таблица, словарь -> карточка, пусто -> "No results."
23	Рендеринг отформатированного вывода	Агент	Красивые таблицы с подсказками по колонкам или JSON с подсветкой
24	Классификация ошибки при сбое	Агент	Regex-поиск ошибок учетных данных, разрешений, ресурсов
25	Предоставление жестко закодированного исправления	Агент	Истек токен -> `aws sso login`. Нет учетных данных -> `aws configure`
26	LLM-интерпретация ошибок ресурсов	Агент	Отправляет неудачную команду + stderr в LLM для получения инструкций

Поток интерактивной сессии

#	Действие	Владелец	Описание
27	Начало сессии	Пользователь	`aaws session [--profile X] [--region Y]`
28	Отображение заголовка сессии	Агент	Показывает активный профиль, регион, инструкции по выходу
29	Ввод последующих запросов	Пользователь	Диалоговый ввод с учетом предыдущего контекста
30	Поддержание истории диалога	Агент	Добавляет каждый обмен, ограничено 10 последними для контекста LLM
31	Перевод с учетом истории	Агент	LLM видит предыдущий диалог для уточнения
32	Полный конвейер безопасности на шаг	Агент	Каждая команда проходит через классификацию -> шлюз -> выполнение -> формат
33	Выход из сессии	Пользователь	Введите `exit`/`quit` или Ctrl+C
34	Обработка Ctrl+C	Агент	Перехватывает KeyboardInterrupt, печатает "Goodbye.", без стека ошибок

Вспомогательные потоки

#	Действие	Владелец	Описание
35	Объяснение существующей команды	Пользователь	`aaws explain "aws ec2 describe-instances --filters ..."`
36	LLM генерирует объяснение	Агент	Описывает, что делает команда, каждый флаг и предостережения
37	Просмотр разрешенного конфига	Пользователь	`aaws config show` — эффективный конфиг с маскировкой секретов
38	Использование `--raw` для скриптов	Пользователь	`aaws --raw "list my buckets"	jq '.Buckets[].Name'`
39	Использование `--dry-run` для предпросмотра	Пользователь	Показывает сгенерированную команду без выполнения
40	Переопределение отказа уровня 3	Пользователь	`aaws --i-accept-responsibility "delete all IAM users"`

CI/CD и автоматизация

#	Действие	Владелец	Описание
41	Конфигурация только через переменные	Пользователь	Установите `AAWS_LLM_PROVIDER`, `AAWS_AWS_REGION` и т.д.
42	Передача сырого вывода в инструменты	Пользователь	`aaws --raw "..."	jq ...` для скриптового использования
43	Тесты при пуше (GitHub Actions)	Агент	Lint (ruff) + проверка типов (mypy) + pytest на Python 3.11-3.13
44	Публикация в PyPI при теге	Агент	`hatch build` + доверенная публикация на тегах `v*`

Установка

Шаг 1: Установка AWS CLI v2

aaws требует установленного AWS CLI в вашем PATH. Он делегирует все операции AWS команде aws.

macOS:

brew install awscli

Windows:

Скачайте и запустите установщик с https://awscli.amazonaws.com/AWSCLIV2.msi

Или через winget:

winget install Amazon.AWSCLI

Linux (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 Access Keys (простейший)

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'

aaws - AI-Assisted AWS CLI