ec2-cli

Agent and CLI for managing AWS EC2 machines (instances) — launch, inspect, start/stop, and operate fleets.

Audience

An AWS user or mesh agent who wants a single at-a-glance answer to "what am I running and what is it costing me" without opening the AWS console.

Before → After

Before: Today you stitch describe-instances and Cost Explorer queries by hand to answer "what am I running + spending."

After: ec2 overview gives you the fleet and cost figures in one command; ec2 instance manages power and limits; ec2 monitor watches spend against limits.

Why it matters

Cost surprise is the #1 EC2 pain. A single trustworthy "running + spend + forecast" view turns reactive bill-shock into a glanceable habit.

Usage

ec2 overview

Live dashboard: fleet listing plus four EC2-service cost figures (MTD, YTD, end-of-month forecast, end-of-year forecast).

ec2 overview
ec2 overview --json

ec2 instance

Manage instances — list, start, stop, set spend limits, and delete.

ec2 instance                          # list instances
ec2 instance start <id> --yes       # start an instance
ec2 instance stop <id> --yes        # stop an instance
ec2 instance limit <id> <amount> --monthly  # set a spend cap
ec2 instance delete <id>            # review what termination would destroy
ec2 instance delete <id> --apply    # terminate (only after a fresh review)

delete is the one irreversible verb: it is gated behind a two-step review → --apply flow. ec2 instance delete <id> prints what would be destroyed (the instance and its EBS volumes) and records a short-lived review token; --apply terminates only when a fresh review (within 15 minutes) exists for that id.

ec2 monitor

Spend monitoring — evaluate against limits, manage a background daemon.

ec2 monitor check                    # evaluate once, alert on breach
ec2 monitor start                    # start the background daemon (~5 min loop)
ec2 monitor stop                     # stop the daemon
ec2 monitor status                   # report daemon running/stopped

Cost figures

The per-machine cost figure is an estimate: spot or on-demand hourly rate × running hours + attached EBS cost. It excludes RI/Savings-Plan discounts and data transfer. Cost Explorer is the billed-truth source.

Monitor scope

Monthly total spend limits are enforced end-to-end with real Cost Explorer data. Per-machine limits and yearly totals are a known follow-up (they require a price/usage-gathering layer).

What you get

• An agent-first CLI cited from teken (afi-cli) — the runtime package has no third-party dependencies.
• A mesh identity — culture.yaml (suffix + backend) and the matching prompt file (CLAUDE.md for backend: claude).
• The canonical guildmaster skill kit (11 skills) under .claude/skills/, vendored cite-don't-import. See docs/skill-sources.md.
• A build + deploy baseline — pytest, lint, the agent-first rubric gate, and PyPI Trusted Publishing wired into GitHub Actions.

Quickstart

uv sync
uv run pytest -n auto                 # run the test suite
uv run ec2 whoami  # identity from culture.yaml (command is `ec2`; dist is `ec2-cli`)
uv run ec2 learn   # self-teaching prompt (add --json)
uv run teken cli doctor . --strict    # the agent-first rubric gate CI runs

CLI

Every command supports --json. Results go to stdout, errors/diagnostics to stderr (never mixed). Exit codes: 0 success, 1 user error, 2 environment error, 3+ reserved.

Make it your own

1. Rename the package ec2/ and the ec2-cli CLI/dist name throughout pyproject.toml, the package, tests/, sonar-project.properties, and this README.md. The name is hard-coded in ~100 places, so list every occurrence first — see the git grep discovery command in CLAUDE.md, the authoritative rename procedure.
2. Edit culture.yaml with your suffix and backend.
3. Rewrite CLAUDE.md for your agent and run /init.
4. Re-vendor only the skills you need from guildmaster (see docs/skill-sources.md).

See CLAUDE.md for the full conventions (version-bump-every-PR, the cicd PR lane, deploy setup).

License

MIT — see LICENSE.