CLI Commands

Complete reference for the keel CLI, generated from the command tree. Access levels: admin > developer > viewer; commands without a listed level need no Keel role (though most still need keel auth login for AWS calls).

Global flags

Available on every command:

Flag	Type	Default	Description
--region	string	—	AWS region override
-v, --verbose	bool	false	Enable debug logging
--config	string	./keel.yml	Config file path
--env	string	—	Target environment (overrides KEEL_ENV and the active environment)
--no-color	bool	false	Disable color output
--cautious	bool	false	Preview and confirm every action before changing AWS state

Core

keel init

Initialize a new Keel project by creating a keel.yml in the current directory. Interactive: app name (default: directory name), region (default us-east-1), mode (default advanced), service port (default 8080), pipeline source (default github) and repository. Errors if the config file already exists.

Also writes keel.yml.example alongside it — an annotated reference listing every option Keel understands, to copy from as the app grows. Keel never reads it, and an existing one is left alone. (The notes live in a sidecar because Keel round-trips keel.yml through the YAML parser, which would drop comments.)

keel up admin

Provision all infrastructure defined in keel.yml. Generates OpenTofu configuration and runs plan + apply to create the VPC, ECS cluster, ALB, ECR repositories, and any add-on services. Registers the app+environment in the DynamoDB registry and (when Keel manages the CodeCommit repo) adds a git remote named keel.

keel deploy [service] developer

Deploy your application to ECS Fargate — one named service, or all of them. Runs preflight git checks, builds via CodeBuild (or locally with --local), registers a task-definition revision per service, runs the release command once, then promotes each service.

Flag	Default	Description
--watch	false	Stay attached and stream deployment progress
--local	false	Build locally instead of using CodeBuild
--lock-timeout	30	Deploy lock timeout in minutes
--force	false	Override an existing deploy lock
--skip-release	false	Skip the release command for this deploy
--release-timeout	—	Override release.timeout for this deploy (e.g. 20m)
--allow-dirty	false	Deploy with uncommitted changes in the working tree
-y, --yes	false	Accept every preflight warning without prompting
--no-push	false	Never push to the Keel-managed source repository

The release timeout must fit inside --lock-timeout.

keel deploy reconcile developer

Find deployment records stuck in a non-terminal state (e.g. because the CLI was interrupted mid-deploy), check what actually happened on AWS, and offer to resume, mark succeeded/failed, or skip each. Finally offers to release a leftover deploy lock.

keel rollback [service] developer

Point a service back at the task-definition revision it ran previously. Nothing is rebuilt; completes in seconds. The release command is not re-run.

Flag	Default	Description
--to	0	Roll back to a specific task definition revision (default: the previous one)
--watch	false	Stay attached and stream rollback progress
--lock-timeout	30	Deploy lock timeout in minutes
--force	false	Override an existing deploy lock

Refuses to roll back to a revision whose image has been expired from ECR.

keel status

Show the current status of all ECS services: running task count, health, last deployment time, and CPU/memory utilization.

keel history

Show the deployment history for this application environment. --limit (default 20) caps the number of entries. The history is Keel's own record of what it deployed — not a view of AWS: a service updated outside Keel leaves no entry, and entries survive the environment they describe being torn down.

keel history prune admin

Delete every deployment record for this app environment. Irreversible — there is no copy anywhere else. Confirms with the record count; -y, --yes skips the prompt. (keel destroy deliberately keeps history; use this, or keel destroy --prune-history, when it genuinely isn't wanted.)

keel rescue admin

Diagnose and repair an environment left inconsistent by an interrupted operation. By default it only reports: the state lock (who took it, what they were doing, how long ago) and untracked resources (tagged ManagedBy=keel but absent from OpenTofu's state). Repairs are opt-in and untracked resources are never deleted automatically — each is listed with the command that deletes it. See Interruptions & Rescue.

Flag	Default	Description
--unlock	false	Release the state lock (only when nothing holds it; always confirms)
--converge	false	Re-run the apply to finish an interrupted keel up
--finish-destroy	false	Re-run the teardown to finish an interrupted keel destroy
--delete-retained	false	With --finish-destroy, delete retain: true resources instead of leaving them

--converge and --finish-destroy together is an error. Within one run the order is: report → unlock → converge/finish-destroy.

keel plan

Preview all infrastructure changes that will be applied on the next keel up.

keel dashboard

Launch the interactive TUI dashboard for the selected environment. Live ECS/RDS/ElastiCache/ALB/CloudWatch/SSM state; actions are gated by your access level inside the TUI. See The Dashboard.

keel destroy admin

Tear down all infrastructure Keel provisioned for this application. Resources declared retain: true are left running in AWS and released from Keel's state; the database is deleted after a final snapshot unless --no-final-snapshot. Confirmation requires typing the app name.

Flag	Default	Description
--force	false	Skip confirmation prompt
--delete-retained	false	Delete resources declared retain: true instead of leaving them in AWS
--no-final-snapshot	false	Delete the database without taking a final snapshot
--prune-history	false	Also delete this environment's deployment history (irreversible)

A successful destroy also releases the deploy lock if one was held, and reports how many deployment records were kept. An interrupted destroy points at keel rescue.

keel apps

List all Keel applications registered in the DynamoDB app registry for the current AWS account. The registry is created by the first keel up.

keel version

Print the version, commit hash, and build date of the Keel binary.

Runtime operations

keel logs [service]

Stream or tail CloudWatch logs for one service (default: the first service in keel.yml).

Flag	Default	Description
-f, --follow	false	Stream logs in real time
--since	10m	How far back to fetch logs (e.g. 10m, 1h, 2d)
--filter	—	CloudWatch Logs filter pattern

keel exec [service] developer

Open an interactive shell or run a command inside a running container via ECS Exec. -c, --command (default /bin/sh).

keel run -- <command>... developer

Run a one-off command — a migration, a backfill, a console — as a new ECS task using a service's task definition, IAM role, security group, and environment.

Flag	Default	Description
-s, --service	release service	Service whose task definition and role to use
-i, --interactive	false	Attach a terminal, for a console or a REPL
--timeout	1h	Give up and stop the task after this long
--cpu	—	Task CPU units for this run (e.g. 1024)
--memory	—	Task memory in MiB for this run (e.g. 2048)

keel scale <service> <count> developer

Scale a service to the specified number of running tasks (updates the ECS desired count immediately).

Services & environments

keel services

• services list — list configured services with type and status
• services add <type> — add a database or cache add-on to keel.yml (run keel up after)
• services remove <type> — remove an add-on service

keel env

• env list — list environments, regions, accounts, and the active one
• env use <environment> — persist the active environment for this app under ~/.keel
• env current — show the environment the current context targets
• env add <environment> — declare a new environment in keel.yml (edits the YAML in place, preserving comments). Flags: --env-region (default: the app's region), --account (opts into account isolation). Adding the first environment to a config that declares none also writes out the implicit default environment and makes it the default, so the existing stack keeps its name. Nothing is provisioned — run keel up --env <name> afterward.

keel db admin

Read the managed database's connection details and admin credentials. The master password is generated and rotated by AWS and stored in Secrets Manager; Keel never holds a copy — these commands read it from there, which needs secretsmanager:GetSecretValue (admin). See Database Credentials.

• db credentials (alias creds) — host, port, database, username, and the password masked; --show prints it
• db url — one-line admin connection string (postgresql://... or mysql://...), e.g. psql "$(keel db url)"

The database lives in private subnets, so a laptop can't reach it whatever credentials you hold — for interactive SQL from inside the VPC use keel exec (developer access suffices; tasks already carry the injected DATABASE_* variables).

Config variables & settings

keel config

Values are stored in SSM Parameter Store as SecureStrings at /keel/<app>/<env>/<key> and injected into ECS task definitions.

• config set KEY=VALUE [KEY=VALUE ...]
• config get KEY
• config list — names/type/version only; values never printed. Also lists the AWS-managed block (e.g. @database credentials and the DATABASE_* variables it injects) so the full set of variables your containers see is in one place.
• config unset KEY [KEY ...]

Managed variable names (DATABASE_USER, DATABASE_PASSWORD, DATABASE_CREDENTIALS) are refused by set/get/unset — they come from a secret AWS generates and rotates; read them with keel db credentials.

keel settings

Project-level CLI behavior, persisted in keel.yml and shared across environments.

• settings / settings list — show all settings
• settings get <setting> — print one value
• settings set <setting> <true|false> — change and persist (verbose, cautious)

Resources & access

keel resources

Summarize built-in (@vpc, @cluster, @registry, @load-balancer, @logs, @pipeline, @database, @cache, @domain, @waf), managed, and linked resources with bindings, IAM capabilities, network rules, and ownership. Flags: --service, --managed, --existing, --json.

• resources show <name> — effective bindings and rules for one resource (--json)
• resources add <type> <name> — declare a managed s3, sns, or sqs resource. Flags: --bind SERVICE:CAP[,CAP] (repeatable), --versioning, --fifo, --visibility-timeout (default 30), --retain (default true)
• resources link <arn-or-identifier> — link an existing resource. Flags: --as (required), --type, --url, --endpoint, --port, --security-group, --secret-arn, --secret-env, --kms-key-arn, --bind
• resources bind <resource> <service> — grant capabilities. Flags: --access (required, comma-separated), --prefix (S3), --env
• resources unbind <resource> <service>
• resources remove <name> — refuses while bound (--force) or protected by retain: true

keel access

• access show <service> — the service's task role, security group, bindings, add-ons, and custom IAM (--json)
• access explain <service> <resource> — why a service can access a resource

Domains & WAF

keel domains

• domains add <domain> admin — add a custom domain (updates keel.yml; run keel up after). --zone overrides the auto-detected hosted zone.
• domains remove <domain> admin
• domains list

keel waf

• waf enable admin — default rule set AWSManagedRulesCommonRuleSet; --rules for a comma-separated list
• waf disable admin
• waf status

Infrastructure

keel infra

• infra plan admin — preview infrastructure changes; --json emits OpenTofu's JSON plan schema on stdout. --keep-plan leaves the saved plan in place so the next apply is bound to it (by default the plan file is discarded when the command ends — it embeds a state snapshot including sensitive values).
• infra apply admin — apply pending changes. When a saved plan exists (from infra plan --keep-plan), the change set that runs is exactly the one that was displayed; otherwise a fresh apply.
• infra output — show outputs from the last apply (ALB DNS name, ECR URLs, VPC IDs)
• infra unlock <LOCK_ID> admin — release a stale OpenTofu state lock left by an interrupted operation. LOCK_ID is the "ID:" field of the "Error acquiring the state lock" message. Confirms first; --yes for scripts. Only break a lock nobody holds. (keel rescue finds the lock ID and holder for you — see Interruptions & Rescue.)

Auth & teams

keel auth

• auth login — start a session, prompting for an MFA code. --mfa-serial overrides device discovery. Sessions last 8 hours and are not auto-renewed.
• auth logout — clear the cached session; --purge also removes the stored access key
• auth setup — guided one-time setup: creates the three roles, your Keel admin user, and its MFA device. --dry-run prints every policy document without touching AWS; --force skips confirmation. Needs elevated AWS credentials, held in memory only.
• auth whoami — current identity, account, role, access level, and credential expiry
• auth join — configure auth from an admin-issued access key. --account (required), --role (expectation only; IAM decides)
• auth connect github <organization> admin — create the CodeConnections connection CodeBuild uses to clone from GitHub; prints the console authorization URL and waits (--timeout, default 15m)

keel auth mfa

• mfa enroll — register an authenticator app against your Keel IAM user; the secret never leaves your machine
• mfa status admin — enforcement per role and enrollment per member
• mfa open admin — grant enrollment rights to existing members when migrating a team to MFA (--force)
• mfa enforce admin — require MFA to assume any Keel role (--disable to remove, --force to skip confirmation)

keel auth team

• team list viewer — list members (--all includes disabled)
• team add <email> <role> admin — provision a member's IAM user and access key, pending MFA enrollment (--no-user for SSO-managed accounts, --force)
• team activate <email> admin — grant access once they have enrolled exactly one MFA device
• team reenroll <email> admin — reset a lost MFA device and reissue their key (--keep-key, --force)
• team remove <email> admin — revoke access, delete their access keys and IAM user (--purge, --force, --allow-self)
• team set <email> <role> admin — change a member's role, re-scoping their IAM user

Diagnostics

keel debug

• debug logs — recent diagnostic log entries (-n lines, default 50; -f, --follow; --all)
• debug path — print the log file path (~/.keel/logs/keel.log)
• debug info — version, platform, and log diagnostics for bug reports