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 thecdk-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 theamplifytemplate.
| Option | Description |
|---|---|
|
|
Template to use (default: |
|
|
Skip confirmation prompts |
|
|
Skip installing dependencies |
|
|
Show usage and the list of templates |
| Template | Description |
|---|---|
|
|
Vite frontend with auth, KVStore, and Realtime (todo app) |
|
|
Vite frontend with a single |
|
|
Vite and React 19 frontend with auth, KVStore, and Realtime (todo app) |
|
|
Next.js 16 App Router with Server and Client Components that call CDK Blocks |
|
|
Vite frontend that tours the |
|
|
Vite frontend with OIDC sign-in, using a local stub identity provider for development |
|
|
Fuller example with Auth, KVStore, FileBucket, AppSetting, Secret, AsyncJob, EmailClient, KnowledgeBase, and Database |
|
|
Backend only: a CDK Blocks API and CDK, no frontend |
|
|
Headless JSON API with a public health check and CRUD routes that require sign-in, no frontend |
|
|
PostgreSQL backend using the |
|
|
Vite frontend with an AI agent and a tool, using a canned model for development |
|
|
Backend only: scheduled CronJobs that record each run, no frontend |
|
|
Backend only: Logger, Metrics, Tracer, and a CloudWatch dashboard on one API call, no frontend |
|
|
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 underhttp://localhost:3000/aws-blocks/api/, with one path for each exported namespace, for example/aws-blocks/api/api. -
backend,api-only,sql,cron, andobservabilitytemplates: The dev server serves the API onhttp://localhost:3001. -
Amplify projects (the
amplifyoverlay): CDK Blocks does not add annpm run devscript. Runnpm run blocks:devto serve the API onhttp://localhost:3001, andnpm run blocks:stopto 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 |
|---|---|
|
|
Stops the dev server that |
|
|
Opens the CloudFormation console’s stack list, filtered to the stack from your last deploy, in the Region from your AWS configuration ( |
|
|
Runs the commands of the |
|
|
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. |
|
|
Manages the values for Hosting |
|
|
Generates typed keys for |
|
|
Generates the API spec file, |
|
|
Runs the TypeScript compiler without emitting files |
|
|
Runs the template’s end-to-end tests |
|
|
Copies a CDK Block package’s source into your project. Pass the package name after a |
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