# Dashboard

`keel dashboard` opens a full-screen terminal interface for live ECS, RDS, ElastiCache, ALB, CloudWatch, and SSM data. It refreshes automatically. When the optional control plane is present, reads use its shared cache; `--direct` forces the IAM path.

*Screenshot: The Keel dashboard: a service card each for web, sidekiq and a scheduled task, with live CPU and memory gauges, sparklines, autoscaling bounds and last-deploy age*

Three services in one environment. The web card is the only one with a URL row — it is the service the load balancer forwards to.

## Follow a deployment

Press `D` to review and start a deployment. The activity panel shows its current phase, progress for each new ECS task set, and resources being changed. The panel disappears when the environment is idle.

*Screenshot: A deploy progressing across seven dashboard frames: resolving the plan, building the image, running the release command, promoting web with its ECS rollout counted task by task, promoting sidekiq, and finally an idle environment with the activity panel gone*

Resolve → build → release → promote → steady state → idle. The rollout bar counts the tasks of the new task set, not the service's total, so a rollout that is stuck is visible as one.

Before deployment, Keel shows the commit, services, release command, and each preflight warning.

*Screenshot: The deploy plan card: target, commit, branch, build method, services, release command, the three things the deploy will do, and one waivable warning about uncommitted changes*

Enter accepts waivable warnings by name. Blocking errors, such as a missing git repository for a CodeBuild deployment, must be resolved first.

## Tabs

| Key | Tab | Shows |
|-----|-----|-------|
| `1` | **Dashboard** | Service cards with task counts, CPU and memory gauges, sparklines, autoscaling targets, last-deploy age, and the routed web service's URL. The activity panel tracks infrastructure changes, deployments, and ECS rollouts |
| `2` | **Services** | The same live service data as a table |
| `3` | **Logs** | CloudWatch log viewer with search, per-service filtering and follow/pause |
| `4` | **Deploys** | Deployment history, deploy locks, rollback, and live deployment progress |
| `5` | **Infra** | A navigable OpenTofu plan diff and per-resource apply progress |
| `6` | **Resources** | Live status and metrics for managed infrastructure, resource actions, and the topology diagram (`t`) |
| `7` | **Config** | Configuration variables from SSM (keys/type/version only — values hidden) |
| `8` | **Admin** | IAM members and operators, MFA state, operator grant counts, capability editing, authorization decisions, and recorded sessions |

The tab bar abbreviates labels in narrow terminals. Tabs, cards, tables, the environment selector, and dialogs support mouse input. The routed web service's URL opens in your browser.

An environment has at most one routed web service. The dashboard shows `https://<domain>` when a custom domain is configured and `http://<alb-dns>` otherwise. Worker services do not have a public URL.

### Services

*Screenshot: The Services tab: name, type, status, task counts, CPU and memory as a table*

The same data as the cards, as rows — for an environment with more services than fit as cards.

### Logs

`/` searches, `f` follows or pauses the tail, and `n` cycles the filter through your services. Recognized severity levels are color-coded; other lines use the default color.

*Screenshot: The Logs tab: a tail of CloudWatch lines, each with a wall-clock time and the service that wrote it, with WARN in amber and ERROR in red*

Every line carries the time it was written and the service that wrote it.

### Deploys

*Screenshot: The Deploys tab: deployment history with relative times, service, status, short commit hash and commit subject*

One row per service per deploy. Commit hashes are shortened and only the subject line is shown — a commit body would break the row.

### Infra

The Infra tab shows a navigable plan diff. `±` marks a replacement and identifies the field that requires it; `-` marks a deletion. Press `A`, then type `apply` to confirm. Keel applies the displayed plan and streams per-resource progress into the tab.

*Screenshot: The Infra tab: a plan summary reading 1 to add, 2 to change, 1 to replace, 1 to destroy, above five resource rows marked with add, change, replace and destroy symbols*

A replacement names the attribute that forces it — “replace” and “change” have very different consequences for a database.

### Resources

The Resources tab shows live RDS, ElastiCache, ALB, and domain state. It highlights non-zero error metrics such as 5xx responses, evictions, and rejected connections. Changes accepted by AWS but not yet complete appear as `pending`.

*Screenshot: The Resources tab: cards for the domain, load balancer, Postgres database and Valkey cache, each with live gauges, sparklines and statistics, the database showing its writer and reader nodes*

The domain appears above the load balancer. Database cards list writer and reader instances separately so you can compare their capacity.

Press `t` to view the environment as a topology diagram, including internet-facing resources, load-balancer routing, and service bindings.

*Screenshot: The topology diagram: internet to domain to load balancer to the web service, with WAF attached, and each service's resource bindings listed beneath it, workers and scheduled tasks shown outside the ingress path*

Bindings are shown with their access levels, so “which services can write to that bucket” is answerable without opening keel.yml.

### Config

*Screenshot: The Config tab: configuration variable names with their SSM parameter type and version, values hidden*

This tab displays keys, types, and versions, but not values. Press a to set a variable and d to unset one.

### Admin

*Screenshot: The Admin tab: MFA enforcement above a roster whose identity column distinguishes IAM members and operators, with role, access, grant count, MFA state and date added*

IAM members show their role and device enrollment; operators show grant-governed access and pool-enforced MFA.

Press `enter` on an operator to inspect every capability they can hold, including absent ones, and add or revoke grants across any declared environment. `i` invites, `s` suspends or restores without losing grants, and `x` ends an enrollment. `l` opens the authorization decision log; `t` opens recorded sessions.

More on [IAM team onboarding](./teams), [operators](./operators), and [audit records](./audit).

## Keybindings

| Key | Action |
|-----|--------|
| `1`–`8` | Switch tabs |
| `↑`/`↓` or `k`/`j` | Navigate the active list |
| `enter` | Open the actions menu (Dashboard/Services, or a person on Admin) |
| `ctrl+k` | **Command palette** — run any `keel` command |
| `/` | Search logs (Logs tab) |
| `f` | Follow / pause the log tail (Logs tab) |
| `n` | Filter logs to the next service (Logs tab) |
| `p` / `A` | Plan / apply infrastructure changes (Infra tab, admin) |
| `t` | Toggle the topology diagram (Resources tab) |
| `T` | Toggle per-task cards (Dashboard tab) — each task's ID, zone, uptime, revision, health, and its own CPU/memory |
| `D` | Deploy, with a plan card first (Deploys tab, developer) |
| `$` | Cost estimate overlay (any tab) — the monthly estimate for this environment, priced from config alone |
| `o` | Open the selected row's URL in a browser (when it has one) |
| `a` / `d` | Set / unset a config variable (Config tab, developer) |
| `i` | Invite an operator (Admin tab) |
| `s` / `x` | Suspend or restore / end an operator enrollment (Admin tab) |
| `l` / `t` | Authorization decisions / recorded sessions (Admin tab) |
| `r` | Refresh now |
| `e` | Environments — a picker showing each environment's region and account, which can also add a new environment to `keel.yml` |
| `s` | Settings overlay outside Admin (toggle verbose / cautious) |
| `?` | Help overlay |
| `esc` | Back / close a panel |
| `q` or `ctrl+c` | Quit |

The help overlay is rendered from the bindings themselves.

*Screenshot: The help overlay: every keybinding in columns, grouped by what it acts on, with a note that verbose narrates actions and cautious confirms them*

Press ? at any time.

## Per-task cards

`T` expands a service card into one card per running task, showing task ID, availability zone, uptime, task-definition revision, health, CPU, and memory.

*Screenshot: The dashboard with per-task cards expanded: three task cards nested inside the web service card and two inside sidekiq, each with its own zone, uptime, revision and gauges*

Per-task metrics reveal uneven load that a service-wide average can hide. The expanded view is off by default.

## When something is wrong

When a service has fewer tasks than desired, its status changes to `DEGRADED`. The card shows the container reason and the activity panel marks a failed rollout.

*Screenshot: A degraded dashboard: the activity panel shows a deploy at 4 of 6 phases and a failed rollout, the web card reads DEGRADED with 1 of 3 tasks running and a CannotPullContainerError beneath it, and the sidekiq card's gauges read as dashes because CloudWatch returned no data*

Failed rollouts are marked explicitly. Missing metrics appear as dashes rather than zero.

Press `enter` on a service to see stopped tasks, recent ECS events, and the reason it is unhealthy.

*Screenshot: The service drill-down: overview figures, load gauges against the autoscaling target, a “why it is unhealthy” section with the container reason, the failed task count, the stopped tasks and recent ECS service events, then the running tasks table*

The detail view combines container reasons, failure counts, stopped tasks, and recent ECS events.

## The command palette

`ctrl+k` opens a searchable list of **every** command in the CLI.

*Screenshot: The command palette: a search field above a list of keel commands with their descriptions, one entry grayed out and annotated “needs admin”*

Choosing one opens its command line, prefilled with the arguments and flags it takes.

## Cost estimate

`$` prices the environment from its configuration and the live task counts, broken down by what is charged for.

*Screenshot: The cost overlay: an estimated monthly range at the top, then compute, data, network, observability, pipeline and Keel's own line items, each with the assumption it was priced under*

Priced from the live desired count, not the one in keel.yml — keel scale moves the count through the ECS API and never writes the file.

Keel shows ranges when cost depends on unknown usage. Autoscaled services are priced from minimum to maximum capacity, for example. See [Cost Estimates & Budgets](/guide/cost).

## Environments

`e` opens the picker: each environment with its region and account. It can also add a new environment to `keel.yml`.

*Screenshot: The environment picker: staging and production, each with its region and AWS account, and an entry to add a new environment*

The one overlay that replaces the whole frame, chrome included.

## Service actions

Press `enter` on a service to open the actions menu:

*Screenshot: The action menu for a scheduled task: Details, Deploy, Rollback and Exec offered, with Scale, Autoscaling and Restart listed but disabled and each annotated with why it does not apply*

- **Details** — a drill-down with running tasks, utilization, and — when a service is short of tasks — why: the container reason from its stopped tasks, its failed task count, and recent ECS service events. This is what turns "0/3 running" into "CannotPullContainerError: manifest not found".
- **Scale** — change the desired task count (ECS `UpdateService`).
- **Autoscaling** — set the capacity bounds and what to scale on (CPU, memory, requests). Writes `keel.yml` and opens a plan on the Infra tab.
- **Restart** — force a new ECS deployment.
- **Deploy** — build and deploy this service, with a plan card first: enter confirms and progress streams into the Deploys tab.
- **Rollback** — preview the revision it would return to, the image that revision runs, and whether that image still exists in ECR, then apply it.
- **Exec** — open an interactive shell in a pane inside the dashboard. Keel speaks the session protocol itself, so the dashboard stays on screen and needs no AWS CLI or session-manager plugin. `ctrl+c` reaches the shell; `ctrl+]` closes the pane.

On an operator session, an authorization refusal is shown as a missing grant rather than as an API outage. If no environment was explicitly selected and several exist, the dashboard opens the picker instead of assuming the file's default, because the operator may not be able to read it.