aws-assistant-toolkit 2.0.0

Lightweight, beginner-friendly AWS assistant CLI with safer workflows than raw AWS CLI.

AWS Assistant Toolkit (Version 2.0)

A practical Python toolkit for day-to-day AWS operations, built for public developer use with a focus on speed, safety, and fewer manual console steps.

Expanding to more AWS services - currently includes:

• S3 operations (uploader.py)
• EC2 operations (aws_assistant.py)
• Lambda deployment & scheduling (lambda_assistant.py)
• Container orchestration - ECS, EKS, Docker, ECR (container_assistant.py)

Cross-platform support: Works on Windows, Linux, and macOS.

Why This Exists

Managing common AWS tasks directly in the console is repetitive and error-prone, especially for:

• selecting the correct EC2 instance every time
• creating consistent snapshots with useful tags
• launching repeatable instances from standardized settings
• syncing local folders to S3 with clear behavior

Version 1.1 wraps these operations in simple commands that are easier to repeat, document, and automate, and now includes a full Lambda workflow (create, deploy, test, and schedule).

Features

Unified Assistant CLI (aws_assistant.py)

• Single entrypoint for day-to-day workflows: aws-assistant ec2 ... | s3 ... | lambda ... | ecs ... | eks ...
• Smart defaults via ~/.aws-assistant.yml (region/profile/tag filters)
• Built-in safety confirmations for destructive operations (bucket delete, EC2 terminate)
• CloudWatch + Kubernetes log helpers with quick error scans
• IAM quick visibility and starter policy templates
• Cost-safety scan for suspicious resources
• Optional interactive TUI mode (aws-assistant tui) with arrow-key menus and searchable long lists
• Quick Action Palette in TUI for power users (type intent directly, skip menu navigation)

S3 (uploader.py)

• Upload files
• List bucket objects
• Delete an object
• Generate pre-signed URLs
• Manage lifecycle rules (expire logs, transition to Glacier)
• Sync folder local <-> S3 (up, down, both) with optional delete

EC2 (aws_assistant.py)

• Start/stop/reboot by instance-id, Name tag, or custom tag
• Safe EBS snapshot flow for one selected instance
• Optional stop/start for root-volume consistency during snapshot
• Launch instance from JSON/YAML profile templates
• key=value shorthand support for faster command entry
• Windows wrapper command: aws-assistant ...

Lambda (lambda_assistant.py)

• Create new Lambda functions with custom runtime, memory, timeout
• Package Lambda code with dependencies into deployment zip
• Deploy code to existing Lambda functions
• Update environment variables from config file
• Test Lambda functions with saved JSON event files
• Display CloudWatch logs with test results
• Create EventBridge schedules for recurring Lambda invocations
• List and delete scheduled Lambda jobs

Containers (container_assistant.py)

ECS Operations:

• Register task definitions from JSON templates
• Update services with zero-downtime deployments
• Scale services (adjust desired task count)
• List services and tasks in clusters
• Stop running tasks

EKS Operations:

• Update kubeconfig and connect to clusters in one command
• Get cluster information and status
• Apply/delete Kubernetes manifests
• List pods across namespaces

Docker & ECR:

• Build Docker images from Dockerfiles
• Tag and push images to registries
• Create and manage ECR repositories
• ECR login automation
• Complete build-tag-push workflow to ECR
• List images in ECR repositories

Release Notes

v1.3.0 (2026-03-10)

• Added unified assistant UX in aws_assistant.py:
  • lambda, container, ecs, eks forwarding from one top-level CLI
  • logs helper commands for Lambda/ECS/EKS with quick error scanning
  • iam summary and iam policy-template helper commands
  • safety scan command for suspicious resource checks
  • tui interactive mode for EC2, logs, IAM templates, and safety scan
  • config init/show using ~/.aws-assistant.yml
  • Destructive-op confirmations for ec2 terminate and s3 delete-bucket
• Added test coverage for assistant quality-of-life functions in tests/test_aws_assistant_qol.py

v1.2.0 (2026-03-10)

• Added container_assistant.py for comprehensive container orchestration:
  • ECS task definition registration and service management (update, scale, list)
  • EKS cluster connection and kubectl manifest operations (apply, delete, list pods)
  • Docker build/tag/push workflows with ECR integration
  • ECR repository creation and image management
• Added container example templates: ecs_task_definition.example.json, Dockerfile.example, k8s_deployment.example.yaml
• Added comprehensive container test suite in tests/test_container_assistant.py
• Updated .gitignore for container artifacts (Dockerfiles, task definitions, k8s manifests)
• Updated documentation with complete container workflows

v1.1.0 (2026-03-10)

• Added lambda_assistant.py with end-to-end Lambda flows: create, package/deploy, test invoke, and schedule management.
• Added Lambda-focused test coverage in tests/test_lambda_assistant.py plus supporting test organization under tests/.
• Added setup/ helper scripts for IAM role setup and Lambda handler/account utilities.
• Added lambda_demo/handler.py and test_events/ examples for reproducible local demos.
• Updated docs (README.md, instructions.md, LAMBDA_WORKFLOW_DEMO.md) and dependencies (requirements.txt).
• Refined .gitignore for a public developer repository: keep examples/tests in git, ignore local secrets and build artifacts.

Project Layout

• uploader.py: S3 command-line utility (all platforms)
• aws_assistant.py: EC2 command-line utility (all platforms)
• lambda_assistant.py: Lambda deployment & scheduling utility (all platforms)
• container_assistant.py: Container orchestration utility - ECS, EKS, Docker, ECR (all platforms)
• aws-assistant.cmd: Windows convenience wrapper
• aws-assistant: Linux/Mac convenience wrapper (requires chmod +x)
• ec2_profiles.example.json: launch profile template reference
• lambda_config.example.json: Lambda deployment config template
• ecs_task_definition.example.json: ECS task definition template
• Dockerfile.example: Docker containerization template
• k8s_deployment.example.yaml: Kubernetes deployment template
• test_events/: example Lambda test event files
• instructions.md: quick command cookbook
• requirements.txt: Python dependencies
• tests/: Unit test files
  • test_lambda_assistant.py: Lambda assistant unit tests (20 tests)
  • test_aws_assistant_ec2.py: EC2 assistant unit tests
  • test_lambda.py: Legacy Lambda tests
  • test_container_assistant.py: Container assistant unit tests
• setup/: One-time AWS account setup scripts
  • setup_lambda_role.py: Creates IAM execution role for Lambda
  • get_aws_info.py: Retrieves AWS account and role information
  • update_handler.py: Updates Lambda handler configuration

Prerequisites

• Python 3.10+ (or python3 on Linux/Mac)
• AWS IAM credentials with required permissions for S3/EC2 operations
• Network access to AWS APIs

Setup

Fast Install (Recommended For Newcomers)

Install as a package and use global commands:

pip install aws-assistant-toolkit

Optional TUI extras (arrow keys + searchable menus):

pip install "aws-assistant-toolkit[tui]"

Then run:

aws-assistant --help

All Platforms

1. Create and activate a virtual environment.
2. Install dependencies:

pip install -r requirements.txt

3. Create .env in project root:

AWS_ACCESS_KEY_ID=YOUR_KEY
AWS_SECRET_ACCESS_KEY=YOUR_SECRET
AWS_REGION=ap-south-1

4. (Optional) Validate credentials:

python validate_aws_credentials.py

Linux/Mac Only: Enable Wrapper Script

chmod +x aws-assistant

After this, you can use ./aws-assistant instead of python aws_assistant.py.

How To Use

Single-page command sheet for v2.0 release:

• See COMMANDS_SHEET.md for all commands in one place.

Note: All commands work cross-platform. Use:

• Windows: python or aws-assistant.cmd
• Linux/Mac: python3 or ./aws-assistant (after chmod)

If installed as package:

• aws-assistant
• aws-assistant-s3
• aws-assistant-lambda
• aws-assistant-container

Assistant-First Workflows (Recommended)

Create config once:

python aws_assistant.py config init
python aws_assistant.py config show

Use one CLI for all services:

python aws_assistant.py ec2 start --name my-dev-box --wait
python aws_assistant.py s3 list my-bucket
python aws_assistant.py lambda deploy my-function --config lambda_config.json
python aws_assistant.py ecs list-services my-cluster
python aws_assistant.py eks pods --all-namespaces

Interactive TUI mode:

python aws_assistant.py tui
python aws_assistant.py tui --plain

Quick Action Palette examples (inside TUI):

ec2 stop name my-dev-box
ec2 terminate id i-0123456789abcdef0
logs lambda my-function 30
iam summary role my-app-role
iam template s3-read-only my_policy.json
safety scan

Quick aliases (inside TUI palette):

ec2 sp name my-dev-box
ec2 term id i-0123456789abcdef0
ls-lambda my-function 30
iam-sum role my-app-role
iam-tpl s3-read-only my_policy.json
scan

For best TUI experience (arrow keys + searchable selection), ensure questionary is installed from requirements.txt.

Logs and quick error scanning:

python aws_assistant.py logs lambda my-function --minutes 30 --quick-errors
python aws_assistant.py logs ecs my-cluster abc123def456 --minutes 30 --quick-errors
python aws_assistant.py logs eks my-pod --namespace production --minutes 30 --quick-errors

IAM quality-of-life:

python aws_assistant.py iam summary role my-app-role
python aws_assistant.py iam summary user my-user
python aws_assistant.py iam policy-template s3-read-only --output s3_read_only_policy.json
python aws_assistant.py iam policy-template ec2-start-stop

Cost-safety scan:

python aws_assistant.py safety scan

Destructive operations with confirmation:

python aws_assistant.py ec2 terminate --tag Environment=dev
python aws_assistant.py s3 delete-bucket my-temp-bucket --force-empty

Skip prompt only when intentional:

python aws_assistant.py ec2 terminate --instance-id i-0123456789abcdef0 --yes
python aws_assistant.py s3 delete-bucket my-temp-bucket --force-empty --yes

S3 Commands

Upload:

python uploader.py upload <file_path> <bucket> [s3_key]

Legacy shorthand upload:

python uploader.py <file_path> <bucket> [s3_key]

List objects:

python uploader.py list <bucket>

Delete object:

python uploader.py delete <bucket> <s3_key>

Pre-signed URL:

python uploader.py presign <bucket> <s3_key> --expires-in 3600

Lifecycle rules:

python uploader.py lifecycle <bucket> --show
python uploader.py lifecycle <bucket> --expire-logs-days 30 --glacier-days 90
python uploader.py lifecycle <bucket> --disable-expire-logs --disable-glacier

Folder sync:

python uploader.py sync <local_folder> <bucket> --prefix data/ --direction up
python uploader.py sync <local_folder> <bucket> --prefix data/ --direction down
python uploader.py sync <local_folder> <bucket> --prefix data/ --direction both --delete

EC2 Commands

Start/stop/reboot by selector:

python aws_assistant.py ec2 start --name my-dev-box --wait
python aws_assistant.py ec2 stop --tag Environment=dev --wait
python aws_assistant.py ec2 reboot --instance-id i-0123456789abcdef0

Safe snapshot:

python aws_assistant.py ec2 snapshot --name my-dev-box --snapshot-tag Purpose=backup
python aws_assistant.py ec2 snapshot --name my-dev-box --stop-for-root-consistency --snapshot-tag Purpose=root-consistent
python aws_assistant.py ec2 snapshot --name my-dev-box --volume-id vol-0123 --volume-id vol-0456 --snapshot-tag Ticket=OPS-102

Launch from profile config:

python aws_assistant.py ec2 launch --profile dev-web --config ec2_profiles.example.json --wait

Shorthand (key=value):

python aws_assistant.py ec2 launch profile=dev-web config=ec2_profiles.example.json

Windows wrapper:

aws-assistant ec2 launch profile=dev-web config=ec2_profiles.example.json

Lambda Commands

Create new Lambda function:

python lambda_assistant.py create <function_name> <role_arn>
python lambda_assistant.py create my-function arn:aws:iam::123456789012:role/lambda-role --runtime python3.12 --memory 512 --timeout 60

Package and deploy:

python lambda_assistant.py deploy <function_name> --config lambda_config.json
python lambda_assistant.py deploy <function_name> --source-dir lambda_ --requirements requirements.txt
python lambda_assistant.py deploy <function_name> --config lambda_config.json --update-env

Test with event file:

python lambda_assistant.py test <function_name> test_events/s3_upload_event.json
python lambda_assistant.py test <function_name> test_events/custom_event.json --tail
python lambda_assistant.py test <function_name> test_events/custom_event.json --no-logs

Create scheduled Lambda:

python lambda_assistant.py schedule create <rule_name> <function_name> "rate(1 hour)"
python lambda_assistant.py schedule create <rule_name> <function_name> "cron(0 22 * * ? *)" --description "Nightly cleanup"
python lambda_assistant.py schedule create <rule_name> <function_name> "rate(1 day)" --event test_events/event.json

List and delete schedules:

python lambda_assistant.py schedule list
python lambda_assistant.py schedule list --function <function_name>
python lambda_assistant.py schedule delete <rule_name>

Container Commands

ECS Operations:

Register task definition:

python container_assistant.py ecs register ecs_task_definition.json

Update service:

python container_assistant.py ecs update-service my-cluster my-service --task-definition my-task:2
python container_assistant.py ecs update-service my-cluster my-service --desired-count 5 --force-deploy

Scale service:

python container_assistant.py ecs scale my-cluster my-service 10

List services and tasks:

python container_assistant.py ecs list-services my-cluster
python container_assistant.py ecs list-tasks my-cluster --service my-service

Stop task:

python container_assistant.py ecs stop-task my-cluster abc123def456 --reason "Manual stop"

EKS Operations:

Connect to cluster:

python container_assistant.py eks connect my-cluster --region ap-south-1 --alias my-cluster-prod

Get cluster info:

python container_assistant.py eks info my-cluster

Apply/delete manifests:

python container_assistant.py eks apply deployment.yaml --namespace production
python container_assistant.py eks delete deployment.yaml --namespace production

List pods:

python container_assistant.py eks pods --namespace default
python container_assistant.py eks pods --all-namespaces

Docker Operations:

Build image:

python container_assistant.py docker build Dockerfile my-app:v1.0
python container_assistant.py docker build Dockerfile my-app:latest --no-cache

Tag image:

python container_assistant.py docker tag my-app:latest my-app:v1.0

Push image:

python container_assistant.py docker push my-app:latest

ECR Operations:

Create repository:

python container_assistant.py ecr create-repo my-app
python container_assistant.py ecr create-repo my-app --immutable --no-scan

ECR login:

python container_assistant.py ecr login

List images:

python container_assistant.py ecr list-images my-app

Complete build and push flow:

python container_assistant.py ecr push-flow Dockerfile my-app --tag v1.0 --repository my-app-repo

Lambda Config Example

Use lambda_config.example.json as a base:

{
  "functions": {
    "my-function": {
      "source_dir": "lambda_",
      "requirements": "requirements.txt",
      "output_zip": "dist/my-function.zip",
      "environment": {
        "TARGET_BUCKET": "my-bucket",
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

EC2 Profile Config Example

Use ec2_profiles.example.json as a base:

{
  "security_group_templates": {
    "web": ["sg-0123456789abcdef0"]
  },
  "profiles": {
    "dev-web": {
      "ami": "ami-0123456789abcdef0",
      "instance_type": "t3.micro",
      "key_pair": "my-keypair",
      "subnet_id": "subnet-0123456789abcdef0",
      "sg_template": "web",
      "tags": {
        "Name": "dev-web",
        "Environment": "dev"
      }
    }
  }
}

Container Config Examples

ECS Task Definition Template

Use ecs_task_definition.example.json as a base:

{
  "family": "my-app-task",
  "networkMode": "awsvpc",
  "requiresCompatibilities": ["FARGATE"],
  "cpu": "256",
  "memory": "512",
  "containerDefinitions": [{
    "name": "my-app-container",
    "image": "<ACCOUNT_ID>.dkr.ecr.ap-south-1.amazonaws.com/my-app:latest",
    "portMappings": [{"containerPort": 8080, "protocol": "tcp"}],
    "environment": [
      {"name": "ENV", "value": "production"}
    ],
    "logConfiguration": {
      "logDriver": "awslogs",
      "options": {
        "awslogs-group": "/ecs/my-app",
        "awslogs-region": "ap-south-1"
      }
    },
    "healthCheck": {
      "command": ["CMD-SHELL", "curl -f http://localhost:8080/health || exit 1"]
    }
  }]
}

Kubernetes Deployment Template

Use k8s_deployment.example.yaml as a base:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app-deployment
spec:
  replicas: 3
  selector:
    matchLabels:
      app: my-app
  template:
    spec:
      containers:
      - name: my-app
        image: <ACCOUNT_ID>.dkr.ecr.ap-south-1.amazonaws.com/my-app:latest
        ports:
        - containerPort: 8080
        resources:
          requests:
            memory: "256Mi"
            cpu: "250m"
---
apiVersion: v1
kind: Service
metadata:
  name: my-app-service
spec:
  selector:
    app: my-app
  ports:
    - port: 80
      targetPort: 8080
  type: LoadBalancer

Manual / Operational Notes

• Use least-privilege IAM permissions.
• Prefer --name/--tag selectors to reduce wrong-instance operations.
• For root volume snapshot consistency, use --stop-for-root-consistency on running instances.
• Keep local real profile configs private (ec2_profiles.json, lambda_config.json, ecs_task_definition.json, Dockerfile, k8s_deployment.yaml) and commit only examples.
• Always stop/terminate temporary EC2 test instances to avoid cost.
• Test Lambda functions with sample events before creating schedules.
• Keep test event files with sensitive data in gitignore.
• For ECS/EKS: Ensure proper IAM roles (ecsTaskExecutionRole, ecsTaskRole) exist before deploying.
• For ECR: Login expires after 12 hours; re-run ecr login if push fails.
• For EKS: Requires kubectl and AWS CLI installed; run eks connect before using kubectl commands.
• For Docker: Ensure Docker daemon is running locally before build/tag/push operations.

Comparison: Version 1 vs Previous Workflow

Previous workflow (manual console + ad-hoc commands)

• Repeated clicking in AWS Console for common tasks
• Harder to standardize launch settings between environments
• Snapshot tagging inconsistent across team members
• Instance targeting often done via instance-id lookup each time
• Sync behavior between local and S3 not centralized

Version 1 (this toolkit)

• Single command layer for routine S3 + EC2 workflows
• Launch profiles provide repeatable infrastructure parameters
• Snapshot flow auto-applies useful source tags
• Instance actions can target by name/tag, not only ID
• Sync behavior is explicit (up/down/both, optional delete)
• Easier onboarding due to codified commands and examples

Limitations (Current V1 Scope)

• Credentials currently read from .env (no advanced profile/STS workflow yet)
• No dry-run mode for EC2 actions yet
• No built-in automated snapshot retention cleanup yet

Packaging And Release

For GitHub Actions automation (CI, TestPyPI/PyPI publish, optional GHCR publish):

• See GITHUB_RELEASE_SETUP.md

Build package artifacts:

python -m pip install build twine
python -m build

Validate package metadata:

python -m twine check dist/*

Publish to TestPyPI first:

python -m twine upload --repository testpypi dist/*

Publish to PyPI:

python -m twine upload dist/*