TL;DR: Run npx infrasketch . in any IaC repository to instantly open an interactive architecture diagram in your browser. No login, no install, no file upload. Works with Terraform, Kubernetes, Pulumi, CloudFormation, CDK, Bicep, Terragrunt, and Docker Compose.

The copy-paste problem with IaC diagrams

You finish a Terraform module, open Lucidchart or draw.io, manually drag in an EC2 box, an RDS cylinder, an ALB arrow — 45 minutes recreating what the code already describes. Two weeks later the code changes, the diagram doesn't, and you've got a lie pinned to your Confluence page. I've seen this on every team I've worked with.

The browser-based InfraSketch tool at infrasketch.cloud cuts most of that: paste your HCL, YAML, or JSON and get an interactive diagram instantly, no account required. But there was still friction. You had to leave your terminal, copy the file contents, navigate to a website. For anyone living in the command line, that adds up over a day.

The CLI removes that last step. Point it at a file, a directory, or a raw GitHub URL, and it generates the diagram and opens your browser — usually in under two seconds. In CI where there's no browser to open, --no-open prints the shareable URL to stdout so you can pipe it wherever you need it.

What npx infrasketch does (and what it doesn't)

The CLI is a thin Node.js wrapper published to npm as infrasketch. When you run it, it reads your IaC file or directory, serializes the content into a base64-encoded JSON fragment, appends that fragment to the InfraSketch web app URL, and opens the result in your default browser.

What it doesn't do matters more than you'd expect:

• Your code never leaves your machine — no upload, no server processing.
• No account, no API key, nothing to sign up for.
• It doesn't touch your IaC files. Read-only.
• No background process. It runs, opens the browser, and exits.

The diagram is rendered entirely in the browser using the URL fragment. Browsers don't send the hash to the server — they only transmit the path and query string. So when you open https://infrasketch.cloud/#eJy..., the server gets a plain GET / with no idea what's in the fragment. That's not a hack; it's just how HTTP works, and we're leaning into it deliberately. It also means the tool works in air-gapped environments as long as the browser can load the InfraSketch page.

Zero-install usage: your first diagram in 10 seconds

Because the CLI is on npm, you can run it immediately with npx without installing anything globally. Navigate to any directory that contains IaC files and run:

npx infrasketch .

That's it. The CLI will scan the current directory, detect the format automatically, and open your browser. If you have a mixed repository with, say, a terraform/ subdirectory and a k8s/ subdirectory, run it from the root — it will pick the dominant format or let you point it at a subdirectory.

If you prefer a permanent global install to skip the npx overhead on every invocation, add it to your PATH once:

npm install -g infrasketch

After that, infrasketch . works from any directory, just like terraform or kubectl.

Single file mode

When you want to diagram a specific file rather than an entire directory, pass the file path directly:

npx infrasketch main.tf

Single file mode is useful when you're working on a large module and want to check just the resources you're currently editing. The CLI reads only that file, so it's faster for large repositories where a full directory scan would pull in many files you don't care about right now.

The format is auto-detected from the file extension and content. .tf files are parsed as Terraform HCL, .yaml and .yml files trigger heuristic detection to distinguish between Kubernetes manifests, Docker Compose files, and CloudFormation templates. For ambiguous cases you can override with the --type flag:

npx infrasketch template.yaml --type cloudformation

Supported values for --type are: terraform, kubernetes, pulumi, cloudformation, cdk, bicep, terragrunt, docker-compose.

Directory scan mode — multi-file Terraform projects

Real Terraform projects rarely live in a single file. A production module typically spans main.tf, variables.tf, outputs.tf, locals.tf, and any number of resource-specific files. Directory scan mode reads all of them and stitches them into one diagram:

npx infrasketch ./terraform/environments/prod/

The CLI recursively finds all .tf files under the given path, concatenates their contents, and feeds the combined HCL to the diagram renderer. This gives you a complete picture of the environment rather than a partial view of whichever file you happened to open first.

For Terragrunt projects where each module lives in its own subdirectory with a terragrunt.hcl, point the CLI at the root of the deployment tree:

npx infrasketch ./live/prod/ --type terragrunt

It will discover all terragrunt.hcl files and combine the dependency graph across modules, giving you visibility into how modules reference each other — something that's notoriously hard to visualize manually.

Tip: For very large Terraform codebases (hundreds of files), consider running the CLI against a specific module subdirectory rather than the repository root. The URL fragment has a practical size limit around 2 MB of raw content, which covers most real-world modules comfortably.

Kubernetes and Pulumi projects

Kubernetes works the same way. Point it at a directory of YAML files and it picks up Deployments, Services, Ingresses, ConfigMaps, StatefulSets, DaemonSets — and renders how they connect:

npx infrasketch ./k8s/ --type kubernetes

The --type flag is optional here if your YAML files have the standard apiVersion and kind fields — the auto-detector recognizes Kubernetes manifests reliably. But if you have a directory that mixes Kubernetes YAML with other YAML (for example, a Helm chart with both templates and values files), being explicit avoids ambiguity.

For more detail on the Kubernetes diagram format and what relationships are visualized, see the Kubernetes diagram generator guide.

Pulumi projects work similarly. Navigate to a Pulumi project directory (the one containing Pulumi.yaml) and run:

npx infrasketch . --type pulumi

The CLI reads the Pulumi program source — TypeScript, Python, Go, or YAML — and extracts resource declarations. Because Pulumi programs are general-purpose code rather than declarative config, the extraction is necessarily heuristic: it looks for new aws.ec2.Instance()-style patterns in TypeScript/Python and equivalent patterns in other languages. Coverage is good for standard resource declarations but may miss resources created inside complex loops or conditional logic.

Remote GitHub raw URL mode

You don't have to clone a repository to diagram it. Pass any raw GitHub URL (or any other URL that returns plain text) and the CLI will fetch it, parse it, and open the diagram:

npx infrasketch https://raw.githubusercontent.com/hashicorp/terraform-provider-aws/main/examples/two-tier/main.tf

This mode is particularly useful for:

• Reviewing open-source Terraform modules before adding them as dependencies
• Quickly understanding the architecture of a reference implementation you found
• Sharing a diagram of a public repository without cloning it locally
• Generating diagrams in documentation pipelines where the source lives in a separate repo

The URL is fetched by the CLI process on your machine (not by the browser or any server), parsed locally, and then encoded into the diagram URL. Your network request goes to GitHub's raw content CDN, not to InfraSketch servers.

CI/CD pipeline integration (--no-open flag)

In a headless CI environment there's no browser to open, so the default behavior would hang or error. The --no-open flag suppresses browser launch and instead prints the diagram URL to stdout:

npx infrasketch main.tf --no-open

This emits a single line like:

https://infrasketch.cloud/#eJyVVdtu2zgQ...

You can capture this URL and use it anywhere: a PR comment, a Slack notification, a build artifact, a release note. Here's a complete GitHub Actions workflow that posts the diagram URL as a PR comment whenever Terraform files change:

name: Terraform Diagram

on:
pull_request:
paths:
- '**.tf'
- '**.tfvars'

jobs:
diagram:
runs-on: ubuntu-latest
permissions:
pull-requests: write
steps:
- uses: actions/checkout@v4

- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: '20'

- name: Generate diagram URL
id: diagram
run: |
URL=$(npx infrasketch . --no-open)
echo "url=$URL" >> "$GITHUB_OUTPUT"

- name: Post diagram comment
uses: actions/github-script@v7
with:
script: |
const url = '${{ steps.diagram.outputs.url }}';
await github.rest.issues.createComment({
owner: context.repo.owner,
repo: context.repo.repo,
issue_number: context.issue.number,
body: `## Architecture Diagram\n\n[View interactive diagram](${url})\n\n> Generated by InfraSketch CLI`
});

If you'd rather use the purpose-built GitHub Action instead of the raw CLI in CI, see the GitHub Action guide — it handles the comment posting and diff detection automatically with less boilerplate.

How it works under the hood (URL encoding, no upload, privacy)

If you're going to run a tool against production Terraform code, you should know what it actually does. Here's the full flow:

1. Reads file contents from disk (or fetches from URL). No preprocessing — the raw content goes through as-is, including variable references and module calls.
2. Wraps the content in a JSON envelope: {"type":"terraform","code":"..."}. Multi-file mode concatenates everything into the code field with separator comments between files.
3. Gzip-compresses the JSON and base64-encodes the result into a compact ASCII string.
4. Appends the encoded string to the InfraSketch URL as a hash fragment: https://infrasketch.cloud/#.
5. Opens that URL in your default browser (open on macOS, xdg-open on Linux, start on Windows). The web app decodes the fragment entirely client-side.

The key detail is step 5. The URL fragment — everything after the # — is never transmitted in HTTP requests. When your browser loads https://infrasketch.cloud/#eJy..., the actual HTTP request to the server is just GET /. No server ever sees your infrastructure code. That's a browser standard, not something we're doing specially — we're just building on top of it.

This also means the diagram URL is a permanent, shareable link with no expiry. The entire diagram state is encoded in the URL itself — there's no server-side session or storage. You can bookmark it, share it in Slack, or save it in documentation and it will work forever, as long as the InfraSketch web app is running.

Combining CLI with GitHub Action for full automation

The CLI is for you while you're coding. The GitHub Action is for your reviewers when they're not.

Practically, the workflow goes: you write a new Terraform module for a VPC peering connection, run npx infrasketch . locally to make sure the diagram looks right (subnets, route tables, peering connections all there), then open a PR. The GitHub Action (pandey-raghvendra/infrasketch@v4) fires automatically and posts the diagram as a comment. Reviewers click the link, see the architecture interactively, no tooling required on their end.

The CLI is fast and zero-ceremony — just a command. The Action is automated and requires no one to remember to run anything. They cover different moments in the same workflow, not the same moment twice.

Comparison table: CLI vs browser vs GitHub Action vs MCP

FAQ

Does npx infrasketch work without internet access?

First run via npx needs to download the package, so yes, internet required there. After that, npm install -g infrasketch once and it runs offline. The generated URL needs a browser to load the InfraSketch web app — so some internet to load the page initially, though your IaC code never gets uploaded to any server regardless.

What happens with .tfvars files that contain secrets?

The code goes into the URL fragment, which is never sent to a server. But the fragment does show up in browser history and in any URL you share. So treat the URL like you'd treat the source code — don't paste it in a public Slack channel if the file has real credentials in it. Stick to main.tf or module directories for diagramming; leave the .tfvars with the actual secrets out of it.

Can I use the CLI with Terraform workspaces?

Yes, workspaces only affect state — the HCL source files are the same regardless of which workspace you're on. npx infrasketch . works normally. If you have workspace-specific variable files like prod.tfvars, you can point the CLI at them directly.

How large can the IaC file be before the URL gets too long?

HCL compresses well — gzip typically gets 5-10x reduction before base64, so a 500 KB Terraform project ends up under 100 KB in the URL. In practice, URL length limits never bite you with normal module-sized codebases. If you're running against an entire monorepo root with hundreds of files, run it against a subdirectory instead.

Can I get the diagram URL without opening the browser, even locally?

--no-open works anywhere, not just CI. npx infrasketch main.tf --no-open on your laptop prints the URL to stdout without touching the browser. Pipe it to pbcopy, drop it in a script, whatever you need.

Diagram your infrastructure in 10 seconds Run npx infrasketch . in your IaC repo right now — or try the browser tool directly with no install required. Try InfraSketch Free →