CLI Reference

cdk-starter CLI

An interactive CLI for scaffolding production-ready AWS CDK apps. No install required — just run it with npx. Use npx cdk-starter --help to see all commands.

1 Quick start

Run the command below — no install needed. It fetches the latest starters list, lets you filter and pick one, then scaffolds the project and runs npm install automatically.

terminal

$ npx cdk-starter create

◇ Found 14 starters

◆ How would you like to find a starter?

● Browse all starters

○ Search by name or keyword

○ Filter by tag

◆ Pick a starter Serverless REST API beginner

◆ Project name my-api

✔ Scaffolded! cd my-api && npx cdk deploy

2 Usage

npx cdk-starter <command> [options]

Commands: create list info compose

Commands

create	Scaffold a new CDK app from a starter. Runs an interactive picker, or use --starter to skip it.
list	List all available starters. Supports --tag filtering, --repo for custom repos, and --json output for scripting.
info <name>	Show full details for a specific starter — description, tags, difficulty, GitHub link, and scaffold command.
compose	Build a custom CDK stack component by component. Pick from 15 components across Networking, Compute, Data, and Utility layers. Generates a ready-to-deploy stack with all wiring done for you.

Shared flags (all commands)

--help

-h

Print help for the current command and exit.

create flags

--starter <name>	-s	Skip the interactive picker and scaffold a specific starter directly by name.
--repo <owner/repo>	-r	Use a custom GitHub repo instead of the default. Accepts owner/repo, owner/repo#branch, or a full GitHub URL.

list flags

--tag <tag>	-t	Filter results by tag. Can be passed multiple times to require all listed tags.
--repo <owner/repo>	-r	Use a custom GitHub repo instead of the default.
--json		Print raw JSON output instead of formatted text. Useful for scripting.

info flags

--repo <owner/repo>	-r	Use a custom GitHub repo instead of the default.
--json		Print raw JSON output instead of formatted text. Useful for scripting.

3 Examples

Interactive scaffold — browse and pick from all starters

npx cdk-starter create

Skip the picker — scaffold a specific starter directly

npx cdk-starter create --starter serverless-api

List all available starters

npx cdk-starter list

Filter the list by tag

npx cdk-starter list --tag serverless

Filter by multiple tags (must match all)

npx cdk-starter list --tag serverless --tag api

Machine-readable JSON output

npx cdk-starter list --json

Show full details for a specific starter

npx cdk-starter info serverless-api

Get starter info as JSON

npx cdk-starter info serverless-api --json

Use your own fork of the starters repo

npx cdk-starter create --repo myfork/cdkapp-starters

Use a specific branch of a custom repo

npx cdk-starter create --repo myorg/my-templates#develop

Fully non-interactive — custom repo + specific starter

npx cdk-starter create --repo myfork/cdkapp-starters --starter serverless-api

Compose a custom stack from individual components

npx cdk-starter compose

4 What happens when you run it

1

Fetches the starters index

Pulls index.json from the starters repo (GitHub raw URL — no auth required).
2

Choose how to browse

Browse all starters, search by name/keyword, or filter by tag. Skipped entirely if you passed --starter.
3

Starter picker

Browse the matching starters with difficulty labels and short descriptions.
4

Project name prompt

Enter a name for your project directory. Press Enter to use the starter name as the default.
5

Scaffold via degit

Downloads only the chosen starter's subfolder from GitHub — no need to clone the whole repo.
6

Dependency install

Runs install automatically using whichever package manager is found first: pnpm → yarn → npm.
7

Next steps printed

Shows the commands to cd in, bootstrap your AWS account, and deploy.

5 Using a custom repo

You can point the CLI at any GitHub repo — a fork, a private team repo, or a completely different template collection — as long as it follows this layout:

your-repo/

├── index.json ← starters manifest

└── starters/

└── my-starter/

├── cdkapp.json ← metadata

├── README.md

└── ... ← CDK app files

cdkapp.json schema

{

"name": "my-starter",

"title": "Human Readable Title",

"description": "Short description shown in the CLI and on the website.",

"tags": ["serverless", "api"],

"author": "your-github-username",

"difficulty": "beginner" // beginner | intermediate | advanced

}

The index.json at the repo root is the manifest the CLI fetches first. You can generate it automatically with a script — see the build-index.js script in the default starters repo for reference.

6 compose — build a stack from scratch New

Don't have a starter that fits? Use npx cdk-starter compose to build a custom stack interactively. You walk through four infrastructure layers, pick the components you need, and get a ready-to-deploy CDK stack with all the wiring done automatically.

terminal

$ npx cdk-starter compose

◆ Stack name my-stack

◆ Networking vpc api-gateway

◆ Compute lambda

◆ Data dynamodb s3-bucket

◆ Utility sqs-queue cloudwatch-alarms

┌─ Your stack ──────────────────────────────┐

│ Networking vpc, api-gateway

│ Compute lambda

│ Data dynamodb, s3-bucket

│ Utility sqs-queue, cloudwatch-alarms

└───────────────────────────────────────────┘

✔ 7 components assembled — cd my-stack && npx cdk deploy

Available components

Networking

vpc Public + private subnets, NAT gateway

api-gateway REST API with access logs, X-Ray, CORS

alb Application Load Balancer (HTTP/HTTPS)

nlb Network Load Balancer (TCP/UDP, static IPs)

route53 Hosted zone + alias records

Compute

lambda Node.js 22 with esbuild, X-Ray, log retention

ecs-fargate Serverless containers, ECR, auto-scaling

Data

dynamodb On-demand table, encryption, PITR

s3-bucket Versioned, encrypted, block public access

rds-aurora Aurora Serverless v2 PostgreSQL

Utility

sqs-queue Queue + dead-letter queue, 3 retries

sns-topic Pub/sub, auto-wires SQS & Lambda subs

eventbridge Scheduled or pattern-matched rule

cloudwatch-alarms Error/depth/CPU alarms per service

secrets-manager Encrypted secret, auto-granted to compute

Automatic wiring

Components that work together are wired automatically in the generated stack — IAM grants, environment variables, subscriptions, and event sources. For example: selecting lambda + dynamodb adds grantReadWriteData and sets TABLE_NAME in the function environment. Selecting sns-topic + sqs-queue adds an SQS subscription. VPC is auto-added if ECS Fargate or RDS Aurora is chosen.

7 After scaffolding

terminal

# Move into your project

$ cd my-api

# Bootstrap your AWS account (once per account/region)

$ npx cdk bootstrap

# Preview what will be deployed

$ npx cdk diff

# Deploy to AWS

$ npx cdk deploy