Installation Guide

Name: CDK Insights
Author: CDK Insights

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

Installation Methods

Recommended

NPX (Recommended)

Run CDK Insights without installing it globally

npx cdk-insights scan

✅ Pros

No installation required
Always uses latest version
No global dependencies

⚠️ Considerations

Slightly slower first run
Requires internet connection

NPM Script

Add CDK Insights as a dev dependency to your project

npm install --save-dev cdk-insights

✅ Pros

Version locked to your project
Faster execution
Works offline

⚠️ Considerations

Requires installation
Manual version updates

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

18.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

Choose Installation Method

Select the installation method that works best for your workflow

We recommend using NPX for most users, or NPM Script for team projects.

Test Installation

Verify CDK Insights is working correctly

# Test with NPX
npx cdk-insights --version

# Or test with npm script (after installation)
npm run scan -- --version

NPM Script Setup (Recommended for Teams)

For team projects, we recommend adding CDK Insights as a dev dependency and creating npm scripts:

1. Install CDK Insights

npm install --save-dev cdk-insights

2. Add Scripts to package.json

{
  "scripts": {
    "scan": "cdk-insights scan",
    "scan:all": "cdk-insights scan --all",
    "scan:json": "cdk-insights scan --output json",
    "scan:markdown": "cdk-insights scan --output markdown"
  }
}

3. Run Analysis

npm run scan

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