Region resolution

Choose the region with AWS_REGION or your AWS profile. This page gives the order cdkd reads those sources in, and the two places where the answer is not obvious: the bootstrap commands, and a region typed in upper case.

AWS_REGION=us-west-2 cdkd deploy MyStack
cdkd deploy MyStack --profile staging     # the profile's region

`--region` is deprecated on most commands

--region is a supported flag on two commands only, where it names the region to act on:

cdkd bootstrap --region us-west-2
cdkd gc --region us-west-2

On every other command the flag is deprecated. It is hidden from --help, it prints a deprecation warning, and a future release will remove it. Until then it still works, and it outranks the environment variable and the profile.

Resolution order

cdkd takes the first source in the list that has a value.

Commands	Order
`cdkd bootstrap`, `cdkd bootstrap --destroy`, `cdkd gc`	`--region`, `AWS_REGION`, `AWS_DEFAULT_REGION`, the profile's region, `us-east-1`
`cdkd local` commands	Per command. Each command's page gives its order.
Every other command	`--region`, `AWS_REGION`, `us-east-1`

The three commands in the first row share one order because they work on the same per-region record. cdkd bootstrap writes the bootstrap marker, a small file in the state bucket that records a region's asset bucket and ECR repository, and the other two read it.

An inferred region yields to existing asset storage

This rule applies to cdkd bootstrap, cdkd bootstrap --destroy and cdkd gc only. When cdkd took the region from your profile, and asset storage already exists in another region, cdkd uses the region that has the storage, so that a bare command does not strand it. A region you name yourself is always used as given.

Your profile	Existing asset storage	cdkd uses
`ap-northeast-1`	Marker in `ap-northeast-1`	`ap-northeast-1`
`eu-west-1`	Marker only in `us-east-1`	`us-east-1`, and says so
`eu-west-1`	None anywhere	`eu-west-1`

In the second row, cdkd prints:

cdkd asset storage exists in us-east-1, but your AWS profile resolves eu-west-1.
Continuing to use us-east-1 so the existing storage is not orphaned. Pass
'--region eu-west-1' to target your profile's region, or '--region us-east-1'
to silence this message.

Region spelling is lower-cased

cdkd lower-cases a region before it reaches an AWS client, so AWS_REGION=US-EAST-1 behaves as us-east-1. cdkd does this because request signing, endpoint resolution and ARNs are all case-sensitive, and an upper-cased region breaks each of them.

Which inputs are lower-cased depends on the command:

Command	What is lower-cased
Every command outside `cdkd local`	`--region`, `AWS_REGION` and `AWS_DEFAULT_REGION`
`local invoke`, `local run-task`, `local invoke-agentcore`	The flag and both environment variables
`local start-api`	The flag only
`local start-service`, `local start-alb`, `local start-cloudfront`, `local start-agentcore`	The flag, `--stack-region` and both environment variables

Edge cases

local start-api and the environment variables. An upper-cased AWS_REGION is not lower-cased there, so it reaches the Lambda containers that the command starts.
--stack-region on the four local start-* commands in the last row. The value is lower-cased, but your exact spelling is still used to match the state record.
The bootstrap marker keeps the spelling you typed. cdkd bootstrap builds the marker's key and the default asset-storage names from the region as you wrote it. Commands that read the marker try the lower-case key first and your spelling second, so a marker written under either is found. cdkd gc and cdkd bootstrap --destroy describe their own reads.

CLI Reference: every command and the shared options
cdkd bootstrap: the per-region asset storage and its marker
cdkd gc: collecting one region's asset storage