# CDK Insights: complete product and CLI reference > This is the self-contained, agent-readable reference for CDK Insights. For a smaller curated link index, use https://cdkinsights.dev/llms.txt. Product facts were reviewed on 2026-07-28. ## What is CDK Insights? CDK Insights is a developer tool for analysing AWS Cloud Development Kit applications before deployment. It synthesises the CDK app, understands the generated CloudFormation and CDK construct context, runs 145 deterministic static rules across 36 AWS services, and reports findings with stable rule IDs, severity, AWS Well-Architected pillar, evidence, remediation, and source attribution where available. The static scanner is free forever, runs locally, requires no account, and does not consume AI credits. Optional AI analysis uses selectable Amazon Bedrock models to review privacy-safe, user-authored resources and provide richer explanations and concrete CDK fixes. CDK Insights is produced by Instance Labs Ltd and distributed through npm as `cdk-insights`. ## Quick start Requirements: Node.js 22 or later and an AWS CDK v2 project that can synthesise successfully. ```bash # Run without installing globally npx cdk-insights scan # Add project scripts and recommended defaults npx cdk-insights init # Static-only scan: no account, upload, or credits npx cdk-insights scan --local ``` The scanner supports CDK applications in any language that can produce a CloudFormation cloud assembly. Some source-integrated features, including in-process aspects and mechanical fixes, are TypeScript/JavaScript-specific. ## Core analysis - Static analysis: 145 rules across 36 AWS services covering security, cost optimisation, reliability, performance, and operations. - CDK-aware evidence: maps CloudFormation resources and findings back to construct paths and source locations where mapping data is available. - Multi-stack scanning: analyses one stack or every stack in the cloud assembly. - CDK Nag compatibility: captures CDK Nag findings into the same reports without requiring CDK Nag to be replaced. - Custom rules and suppressions: project-specific deterministic checks and auditable exceptions. - Repeat-scan cache: unchanged AI results can be reused without consuming more credits. ## Important CLI commands | Command | Purpose | | --- | --- | | `cdk-insights scan [stackName]` | Synthesize and analyse one or all CDK stacks. | | `cdk-insights fix` | Preview or apply deterministic mechanical fixes for supported findings. | | `cdk-insights preview` | Compare a deployment with a known-good template baseline and classify deployment risk. | | `cdk-insights graph` | Build resource relationship graphs and identify public-to-sensitive paths. | | `cdk-insights simulate` | Assess zonal, dependency, quota, and regional failure modes. | | `cdk-insights policy init` | Create a project-specific infrastructure policy. | | `cdk-insights policy check` | Enforce that policy locally or in CI. | | `cdk-insights live` | Compare with read-only CloudFormation state and existing drift results. | | `cdk-insights plan` | Estimate monthly credits and recommend a plan from estate size and Git history. | | `cdk-insights document` | Generate Markdown architecture documentation and a Mermaid diagram. | | `cdk-insights learn ` | Convert an incident into a preventive local custom rule and postmortem. | | `cdk-insights mcp` | Run the read-only local Model Context Protocol server over standard input/output. | Run `npx cdk-insights --help` or `npx cdk-insights --help` for the executable option reference. ## Output formats The scan command supports six output formats: 1. `table`: human-readable terminal findings. 2. `json`: structured automation output and a JSON report file. 3. `markdown`: a reviewable Markdown report. 4. `summary`: concise terminal totals and important findings. 5. `sarif`: SARIF 2.1.0 for GitHub Code Scanning and compatible viewers. 6. `github-actions`: workflow annotations and CI-oriented output. Every format is derived from the same normalized findings so rule IDs, severity, resource identity, evidence, source location, and recommendations remain consistent. ## AI models and credits AI analysis is metered in credits per freshly analysed resource. Static analysis is unlimited and consumes no credits. Unchanged cached results consume no additional credits. | Model | CLI alias | Credits per fresh resource | Recommended role | | --- | --- | ---: | --- | | GLM 4.7 Flash | `glm-4-7-flash` | 0.5 | Rich default | | Amazon Nova Lite | `nova-lite` | 0.5 | Fast alternative | | Mistral 14B | `mistral-14b` | 1 | Open-weight comparison | | Claude Haiku 4.5 | `haiku-4-5` | 4 | Deeper reasoning | | Claude Sonnet 4.6 | `sonnet-4-6` | 16 | Maximum depth | Monthly base allowances: - Free account: 500 AI credits. - Pro: 10,000 AI credits. - Team: 20,000 AI credits per seat. The CLI shows the maximum credit cost before analysis starts. Additional credit packs are available for occasional releases, larger estates, or premium-model reviews. Current commercial terms are authoritative at https://cdkinsights.dev/pricing. ## Infrastructure intelligence These commands run locally unless their documentation explicitly says otherwise: - `preview` records or compares a synthesized-template baseline, separates new risks from accepted debt, and can fail CI at a chosen decision level. - `graph` produces JSON or Mermaid architecture graphs and flags statically identifiable public-to-sensitive paths. - `simulate` reviews availability-zone concentration, critical dependencies, service quotas, and regional recovery posture. - `policy` creates and enforces project rules such as required tags, denied resource types, allowed regions, encryption expectations, and severity limits. - `live` uses read-only CloudFormation APIs to compare synthesized intent with deployed state and existing drift results; it never starts drift detection or changes AWS resources. - `plan` combines synthesized resource counts with infrastructure Git history to estimate scan frequency, cache reuse, monthly credits, confidence, and plan headroom. - `document` turns `cdk.out` into Markdown containing a Mermaid graph, estate summary, stack inventory, attack-path leads, and review notes. - `learn` turns a structured incident into a local deterministic rule plus a version-controlled Markdown postmortem; incident content is not uploaded. ## MCP integration Start the server with `npx cdk-insights mcp`. It uses JSON-RPC over standard input/output, reads an existing `cdk.out`, and does not synthesize, deploy, call AWS, invoke an AI model, or spend credits. Available MCP tools: - `cdk_architecture_graph`: JSON or Mermaid resource graph and public-to-sensitive paths. - `cdk_reliability_review`: zonal, dependency, quota, and regional-recovery review. - `cdk_architecture_document`: Markdown architecture documentation with diagram and review notes. - `cdk_plan_advisor`: plan and credit estimate from supplied project-change assumptions. Configuration and parameter reference: https://cdkinsights.dev/docs/features/mcp-integration. ## GitHub and CI integration The official GitHub Action can scan pull requests, add workflow annotations, publish SARIF to GitHub Code Scanning, post Markdown summaries, and gate changes by severity or AWS Well-Architected pillar. Repository: https://github.com/instancelabs/cdk-insights-action. The CLI also runs in GitLab CI, Jenkins, CircleCI, or any pipeline with Node.js 22 and a synthesizable CDK application. Machine-readable JSON and SARIF outputs are stable integration points. ## Privacy and security boundaries - Static scans run locally. CDK source and synthesized templates are not uploaded for static analysis. - AI analysis is optional. It sends redacted CloudFormation context for privacy-safe, user-authored resources, not the source repository. - Scan-history upload is opt-in and sends structured report data to the authenticated dashboard. - `plan`, `graph`, `simulate`, `document`, `learn`, and the MCP tools do not spend AI credits. - `live` requires AWS credentials but is limited to documented read-only CloudFormation operations. - The public security and data-handling reference is https://cdkinsights.dev/security. ## How CDK Insights relates to other tools - CDK Nag is a CDK Aspect focused on compliance rule packs. CDK Insights can ingest its findings and adds its own security, cost, reliability, source-mapping, reporting, AI, and dashboard features. - Checkov supports several infrastructure-as-code frameworks. CDK Insights focuses specifically on AWS CDK and its construct-to-CloudFormation relationship. - cfn-lint validates CloudFormation syntax and specification conformance. CDK Insights focuses on architectural risks, security posture, cost, reliability, and remediation. - AWS Config evaluates deployed AWS resources. CDK Insights primarily reviews CDK intent before deployment, with a separate read-only live comparison command. See the detailed, factual comparison at https://cdkinsights.dev/alternatives. ## Canonical resources - Website: https://cdkinsights.dev - Documentation: https://cdkinsights.dev/docs - Rule library: https://cdkinsights.dev/rules - Pricing and estate calculator: https://cdkinsights.dev/pricing - npm package: https://www.npmjs.com/package/cdk-insights - CLI repository and issues: https://github.com/instancelabs/cdk-insights - GitHub Action repository: https://github.com/instancelabs/cdk-insights-action - Security: https://cdkinsights.dev/security - Privacy: https://cdkinsights.dev/privacy - Support: support@cdkinsights.dev ## Publisher CDK Insights is built and maintained by Instance Labs Ltd, a company registered in the United Kingdom under company number 17053174.