aws-green

get your projects green

A terminal dashboard for live AWS resource health across multiple accounts and regions — CodePipeline, CloudFormation, and ECS — no browser required.

Features

• Stoplight-per-project — 🟢 🔴 🟡 ⏸ ⚪ derived from worst-case across pipeline, CloudFormation stacks, and ECS services
• Per-resource-type summary — collapsed row shows Pipeline 🟡 Stacks 🟢 ECS 🟢 at a glance
• Stage-level expand — expand any project to see pipeline stages, stack statuses with elapsed timers, and ECS running/desired task counts
• Active-first sorting — in-progress and failing projects surface to the top automatically
• Inline expand/collapse — navigate with ↑/↓, toggle any row with enter/space
• Auto-expand what needs attention — a project opens on its own when it goes red, yellow, or ⏸, and closes when it recovers. Collapse one by hand and it stays collapsed until its status actually changes
• Auto-polling — refreshes every 30 seconds (configurable); retains last-known status on API errors
• CloudFormation monitoring — maps stack status to stoplight; in-progress stacks show elapsed timer
• ECS service monitoring — shows running/desired task counts; flags active deployments. Stopped-task detail is fetched only for services that are actually unhealthy, so a green fleet costs one call per cluster
• Throttle-aware — AWS clients use the SDK's adaptive retry mode, self-throttling before AWS has to reject a burst
• Manual approvals — pipelines waiting at an approval gate show ⏸ and sort to the top; approve or reject from the dashboard with a / x
• Stuck alerts — POSTs a signed JSON event to your webhooks when a pipeline, stack, or service stays wedged past a threshold, once per incident
• Multi-account — per-account AWS profile config with named profiles or environment credentials
• In-TUI project management — add, edit, delete, and enable/disable projects without leaving the terminal; adding a pipeline finds its CloudFormation stacks and ECS services for you
• Interactive init — aws-green init writes a starter config via a terminal form
• Single binary — no runtime, no dependencies

Install

Homebrew

brew install --cask ericdahl-dev/tap/aws-green

As of v0.4.0, aws-green is published as a Homebrew cask rather than a formula — GoReleaser removed the formula config this project used. The tap still holds the old formula under the same name, frozen at v0.3.1, and Homebrew picks the formula over the cask when you leave out --cask, so keep the flag. If you installed before v0.4.0 you are on the old formula; move across once with:

brew uninstall --formula aws-green
brew install --cask ericdahl-dev/tap/aws-green

Go

go install github.com/ericdahl-dev/aws-green@latest

Requires Go 1.25 or later. A binary built this way reports its version as dev.

Usage

aws-green            # launch the dashboard
aws-green init       # write a starter config
aws-green --version  # print the version
aws-green --help     # show usage

First-time config

Run an interactive wizard (writes ~/.config/aws-green/config.toml):

aws-green init

Use aws-green init --force to overwrite an existing file.

Config

Create ~/.config/aws-green/config.toml by hand, or start from aws-green init and edit:

[settings]
poll_interval_seconds   = 30
stuck_threshold_minutes = 30   # optional; how long a resource stays bad before it alerts

[[accounts]]
name    = "production"
profile = "prod"
region  = "us-east-1"

[[projects]]
name    = "my-app"
account = "production"
# enabled = false          # optional; disable without deleting (no API calls made)

  [projects.pipeline]
  name = "my-app-DeploymentPipeline-abc123"

  [[projects.stacks]]
  name = "my-app-cluster"

  [[projects.stacks]]
  name = "my-app-service"

  [[projects.ecs]]
  cluster  = "my-app-FargateCluster-xyz789"
  services = ["my-app-web", "my-app-worker"]

[[webhooks]]
url    = "https://hooks.example.com/aws-green"
secret = "shared-secret"        # optional; enables request signing

Stuck alerts

A dashboard only helps when someone is looking at it. Configure one or more [[webhooks]] and aws-green POSTs a JSON event the moment a resource has been wedged for longer than stuck_threshold_minutes (default 30):

• Pipeline — a stage of the latest execution is Failed/Stopped, or still InProgress (a pipeline waiting on a manual approval is not stuck, and never alerts)
• CloudFormation stack — any *_IN_PROGRESS or *_FAILED status
• ECS service — running task count does not match desired

Each wedged resource fires once, on the cycle it crosses the threshold — not every poll. Once it recovers it is re-armed, so the next incident alerts again.

A resource whose fetch failed is never reported as wedged: what is on screen is carried-forward data, and a stack frozen mid-update by an expired SSO session is not a broken deploy. The failing fetch alerts instead, as fetch_failed, with the underlying error in detail:

{
  "event": "fetch_failed",
  "reason": "fetch_failed",
  "project": "my-app",
  "account": "production",
  "resource_type": "stack",
  "resource": "my-app",
  "detail": "operation error CloudFormation: DescribeStacks, ... token has expired",
  "stuck_since": "2026-01-02T03:04:05Z",
  "timestamp": "2026-01-02T03:35:05Z"
}

Stack and ECS fetches cover a whole group rather than one named resource, so their resource is the project.

{
  "event": "pipeline_stuck",
  "reason": "pipeline_in_progress",
  "project": "my-app",
  "account": "production",
  "region": "us-east-1",
  "resource_type": "pipeline",
  "resource": "my-app-DeploymentPipeline-abc123",
  "status": "InProgress",
  "detail": "stage Deploy",
  "stuck_since": "2026-01-02T03:04:05Z",
  "timestamp": "2026-01-02T03:35:05Z"
}

event is one of pipeline_stuck, stack_stuck, ecs_service_stuck, fetch_failed; reason is one of pipeline_failed, pipeline_in_progress, stack_failed, stack_in_progress, ecs_count_mismatch, fetch_failed. ECS events also carry cluster.

When a webhook has a secret, the request is signed with HMAC-SHA256 over the raw body and sent as X-Aws-Green-Signature: sha256=<hex> — verify it before trusting the payload. Delivery failures are never retried and never interrupt polling; run with AWS_GREEN_DEBUG=1 to see them on stderr.

Using the default AWS profile

If all your resources live in one account, omit [[accounts]] and leave account blank — aws-green will use your default AWS profile and region:

[[projects]]
name = "my-app"

  [projects.pipeline]
  name = "my-deploy-pipeline"

  [[projects.stacks]]
  name = "my-app-stack"

Authentication

aws-green uses the standard AWS credential chain via aws-sdk-go-v2. Any of these work:

• Named profiles in ~/.aws/config (recommended — set profile in [[accounts]])
• AWS SSO (IAM Identity Center) profiles, after aws sso login --profile <name>; run it again when the session expires
• Environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, etc.)
• IAM instance/task roles when running on AWS

The dashboard only reads, and needs these permissions for each profile:

• codepipeline:GetPipelineState
• cloudformation:DescribeStacks
• ecs:DescribeServices, ecs:ListTasks, ecs:DescribeTasks

Finding stacks and services when you add a project (see Project manager) also needs codepipeline:GetPipeline, codepipeline:ListTagsForResource, cloudformation:DescribeStackResources and cloudformation:ListStackResources.

The actions behind f, a and x write to AWS, and each needs its own permission:

• Restart a pipeline: codepipeline:StartPipelineExecution
• Continue a rollback: cloudformation:ContinueUpdateRollback
• Cancel a stalled stack update: cloudformation:CancelUpdateStack
• Force a new ECS deployment: ecs:UpdateService
• Approve or reject (a / x): codepipeline:PutApprovalResult on the pipeline

Keybindings

Dashboard

Key	Action
↑ / k	Navigate up
↓ / j	Navigate down
enter / space	Expand / collapse project row
r	Force refresh
f	Smart fix (restart pipeline / force deploy / continue rollback / cancel a stack update running past stuck_threshold_minutes)
a / x	Approve / reject the selected pipeline's pending manual approval (⏸)
o	Open pipeline in AWS Console
m	Open project manager
q / ctrl+c	Quit
?	Toggle help overlay
esc	Close help overlay

f, a and x ask before they act: enter runs the action, esc cancels it.

Project manager (m)

Key	Action
↑ / k	Navigate up
↓ / j	Navigate down
t / space	Toggle enable / disable
a	Add project
e	Edit project
d	Delete project
esc	Back to dashboard

Changes are written to config.toml immediately and the poller reloads automatically. Disabled projects make no AWS API calls.

When you add a project, or edit one that has a pipeline but no stacks or ECS services yet, aws-green looks up the stacks that share the pipeline's ProjectName tag (the tag CDK blueprints set) and the ECS services those stacks created. It lists them with the ones named after the project pre-selected: space toggles an item, enter saves the selection, and esc saves the project without them. A pipeline with no ProjectName tag is saved as-is, and you add its stacks and services to config.toml by hand.