View a markdown version of this page

CLI reference - AWS CDK Blocks

CLI reference

AWS CDK Blocks uses standard npm scripts for all development and deployment workflows. After scaffolding a project, all commands run from your project root.

For more information about CLI commands and options, see CDK Blocks CLI documentation on GitHub.

Create a project

npm create @aws-cdk-blocks/blocks-app@latest <project-name> [-- --template <template>]

Scaffolds a new CDK Blocks project. The command picks its mode from the target directory:

  • Empty or new directory: creates a standalone app from a template.

  • Existing project (has a package.json): adds the cdk-blocks/ backend workspace, cdk.json, and the CDK Blocks scripts to your project. Works with any frontend framework.

  • Amplify Gen 2 project (has amplify/backend.ts): adds CDK Blocks to your Amplify backend, using the amplify template.

Option Description

--template <name>

Template to use (default: default). In an existing project, it selects which cdk-blocks/ workspace to copy, for example nextjs for a Next.js dev server.

--yes, -y

Skip confirmation prompts

--skip-install

Skip installing dependencies

--help, -h

Show usage and the list of templates

Template Description

default

Vite frontend with auth, KVStore, and Realtime (todo app)

bare

Vite frontend with a single greet() API (smallest starter)

react

Vite and React 19 frontend with auth, KVStore, and Realtime (todo app)

nextjs

Next.js 16 App Router with Server and Client Components that call CDK Blocks

auth

Vite frontend that tours the Auth Block: email sign-up with a code, groups, and profile attributes. --template auth-cognito still works and creates this template

auth-oidc

Vite frontend with OIDC sign-in, using a local stub identity provider for development

demo

Fuller example with Auth, KVStore, FileBucket, AppSetting, Secret, AsyncJob, EmailClient, KnowledgeBase, and Database

backend

Backend only: a CDK Blocks API and CDK, no frontend

api-only

Headless JSON API with a public health check and CRUD routes that require sign-in, no frontend

sql

PostgreSQL backend using the Database Block with SQL migrations, foreign keys, and transactions (Aurora DSQL)

agent

Vite frontend with an AI agent and a tool, using a canned model for development

cron

Backend only: scheduled CronJobs that record each run, no frontend

observability

Backend only: Logger, Metrics, Tracer, and a CloudWatch dashboard on one API call, no frontend

amplify

Overlay for an existing Amplify Gen 2 app. Selected automatically; you cannot use it for a new app.

Local development

npm run dev

Starts the local development server, which runs your app and every CDK Block on your machine, with hot reload. CDK Blocks use local in-memory and filesystem storage. No AWS account required.

  • Templates with a frontend: The dev server serves the frontend and API from a single front door at http://localhost:3000. The frontend dev server runs on port 3100 behind it. The API lives under http://localhost:3000/aws-blocks/api/, with one path for each exported namespace, for example /aws-blocks/api/api.

  • backend, api-only, sql, cron, and observability templates: The dev server serves the API on http://localhost:3001.

  • Amplify projects (the amplify overlay): CDK Blocks does not add an npm run dev script. Run npm run blocks:dev to serve the API on http://localhost:3001, and npm run blocks:stop to stop it.

npm run dev frees its ports at startup by stopping whatever process listens on them. If a dev server for this project is already running, the new one exits instead. For more information, see Port 3000 or 3001 already in use. To stop the dev server from another terminal, run npm run dev:stop.

Sandbox deployment

npm run sandbox

Deploys your own sandbox backend to AWS with a full CloudFormation deployment, which can take several minutes the first time. It then runs cdk watch, which hotswaps code changes into the Lambda function, and starts the local dev server against the deployed backend. Each developer gets an isolated sandbox.

npm run sandbox:deploy

Deploys the sandbox once and exits. Use it in scripts and CI.

npm run sandbox:preview

Deploys the sandbox with your frontend hosted in preview shape, prints the preview URL, and exits. Only templates with a frontend have this script.

npm run sandbox:destroy

Deletes every stack the sandbox deployed. A us-east-1 support stack that holds a Lambda@Edge function cannot be deleted for a few hours after its CloudFront distribution is gone; if the command reports this, run it again later.

Production deployment

npm run deploy

Deploys every stack in the application to AWS with CDK (CloudFormation), without an approval prompt for IAM changes. It always updates the production stack, <stackId>-prod. Add -- --wait-live to wait until CloudFront serves the new frontend build. For more information about staged deployments, see Staged deployments with a pipeline.

npm run destroy

Deletes the production stack. It keeps stateful resources such as tables, buckets, and Auth user pools. An Auth Block with removalPolicy: 'destroy' and deletionProtection: false loses its user pool. If a delete attempt fails, the command empties the buckets in every stack before it retries. On an app with more than one top-level stack, such as one with a us-east-1 support stack, the first attempt always fails. Do not use this command there. For more information, see Full deployment.

Other project scripts

Projects created from a template also have these scripts. Adding CDK Blocks to an existing project adds only the dev:server, dev:stop, sandbox, sandbox:destroy, sandbox:console, deploy, and destroy scripts.

Script Description

npm run dev:stop

Stops the dev server that npm run dev started. Add -- --port <n> for a port other than the default.

npm run sandbox:console

Opens the CloudFormation console’s stack list, filtered to the stack from your last deploy, in the Region from your AWS configuration (us-east-1 if none is set)

npm run db

Runs the commands of the Database Block. types --block <id> writes a Tables interface for Kysely from the CDK Block’s migration files, and status --block <id> lists the applied and pending files in the local database. For an existing database, connect stores the connection string and migrate applies pending files. Pass the command after a -- separator, as shown after this table.

npm run cleanup

Stops every process with a connection on ports 3000 to 3003 (3001 to 3003 in templates without a frontend), whatever the process is. This includes processes that only connect to those ports, such as a browser.

npm run secret

Manages the values for Hosting secret() in AWS Secrets Manager with the set <KEY>, list, and remove <KEY> subcommands. These are not Secret Block values. set prompts for the value, or reads it from standard input with --value-stdin. Pass the subcommand after a -- separator, as shown after this table.

npm run typegen

Generates typed keys for getSecret() and getConfig(). Add -- --check in CI to fail when the file is stale.

npm run spec

Generates the API spec file, cdk-blocks/blocks.spec.json

npm run typecheck

Runs the TypeScript compiler without emitting files

npm run test:e2e

Runs the template’s end-to-end tests

npm run vendorize

Copies a CDK Block package’s source into your project. Pass the package name after a -- separator, as shown after this table. For more information, see Pattern 4: Vendorize.

For example, to set a secret value, to list the migration files of the Database Block main, and to vendorize the KVStore package:

npm run secret -- set <KEY> npm run db -- status --block main npm run vendorize -- @aws-cdk-blocks/bb-kv-store

Related resources

For more information about advanced CLI options, environment variables, and CI/CD configuration, see CDK Blocks CLI reference on GitHub.