Installation Guide

Complete guide to installing and setting up CDK Insights. Choose the installation method that best fits your workflow.

Installation Methods

Recommended

Project Install (Recommended)

Add CDK Insights as a dev dependency to your project

npm install --save-dev cdk-insights

✅ Pros

Version locked to your project
Team members get the same version
Works reliably in CI/CD
Faster execution after install

⚠️ Considerations

Requires one-time installation
Manual version updates

NPX (Quick Try)

Try CDK Insights without installing it

npx cdk-insights@latest scan

✅ Pros

No installation required
Good for one-off testing

⚠️ Considerations

Slower startup (downloads each time)
May use cached old versions
Not recommended for regular use

Global Install

Install CDK Insights globally on your system

npm install -g cdk-insights

✅ Pros

Available system-wide
Fast execution

⚠️ Considerations

Global dependency
Version conflicts possible
Not recommended for teams

System Requirements

Node.js

20.0.0 or higher

CDK Insights is built with Node.js and requires a modern version

AWS Credentials

Configured

AWS credentials configured via AWS CLI, environment variables, or IAM role

AWS CDK

2.0.0 or higher

CDK Insights analyzes CDK applications, so you need CDK installed

Setup Steps

Verify Prerequisites

Ensure you have the required tools installed

# Check Node.js version
node --version

# Check AWS CLI version
aws --version

# Check CDK version
cdk --version

Install CDK Insights

Install as a dev dependency in your project

npm install --save-dev cdk-insights

Initialize npm Scripts

Add convenient npm scripts to your package.json

# Add recommended scripts automatically
npx cdk-insights init

# Or add all optional scripts too
npx cdk-insights init --all

Run Your First Scan

Use the familiar npm run command

npm run cdk-insights

NPM Script Setup (Recommended for Teams)

For team projects, we recommend using the init command to automatically add npm scripts:

1. Install CDK Insights

npm install --save-dev cdk-insights

2. Initialize npm Scripts

npx cdk-insights init

This adds the following scripts to your package.json:

{
  "scripts": {
    "cdk-insights": "cdk-insights scan",
    "cdk-insights:all": "cdk-insights scan --all",
    "cdk-insights:json": "cdk-insights scan --output json",
    "cdk-insights:markdown": "cdk-insights scan --output markdown",
    "cdk-insights:ci": "cdk-insights scan --all --output json --fail-on-critical"
  }
}

Use npx cdk-insights init --all to include additional scripts for GitHub issues and summary output.

3. Run Analysis

npm run cdk-insights

Common Installation Issues

❌ "cdk-insights: command not found"

This usually means CDK Insights isn't installed or not in your PATH.

# Try using npx instead
npx cdk-insights scan

❌ "AWS credentials not configured"

CDK Insights requires AWS credentials for CDK synthesis.

# Configure via AWS CLI (recommended)
aws configure

# Or set environment variables
export AWS_ACCESS_KEY_ID=your_key
export AWS_SECRET_ACCESS_KEY=your_secret

❌ "CDK not found"

Make sure AWS CDK is installed and configured.

# Install CDK globally
npm install -g aws-cdk
# Verify installation
cdk --version

Ready to Start Analyzing?

Now that CDK Insights is installed, you're ready to run your first analysis.

Your First Scan Learn About Features

Documentation

Installation

Docs Home