Planwright is a local-first infrastructure planning engine. It turns typed plans and selected infrastructure-as-code artefacts into a reviewable architecture graph then generates evidence: validation results, security notes, cost notes, loss reports, diagrams and deployment packs.
Planwright treats infrastructure conversion as a migration and evidence problem, not a syntax conversion problem.
- INSTALLATION
- Release Files
- Update
- Dependencies
- Compile
- Quick Proof Path
- Usage and Options
- Examples
- What Planwright Is Not
- Current Scope
- Compatibility
- Safety Boundaries
- Documentation
- Development
- Contributing
- Governance
- Support
- Security
- Sponsoring
- Licence
- Changelog
You can install Planwright using release binaries or by compiling from source.
| File | Description |
|---|---|
| planwright_windows_amd64.exe | Windows x64 standalone executable, recommended for Windows x64 |
| planwright_linux_amd64 | Linux x64 standalone executable, recommended for Linux x64 |
| planwright_darwin_arm64 | macOS Apple Silicon standalone executable, recommended for Apple Silicon Macs |
| File | Description |
|---|---|
| planwright_windows_arm64.exe | Windows Arm64 standalone executable |
| planwright_linux_arm64 | Linux Arm64 standalone executable |
| planwright_darwin_amd64 | macOS Intel standalone executable |
| planwright_linux_amd64_desktop.zip | Linux x64 desktop metadata package with the Planwright icon |
| planwright_linux_arm64_desktop.zip | Linux Arm64 desktop metadata package with the Planwright icon |
| planwright_darwin_amd64_app.zip | macOS Intel .app bundle with the Planwright icon |
| planwright_darwin_arm64_app.zip | macOS Apple Silicon .app bundle with the Planwright icon |
| File | Description |
|---|---|
| SHA2-256SUMS | SHA-256 checksum manifest |
| SHA2-256SUMS.sig | OpenPGP signature for SHA2-256SUMS |
| SHA2-512SUMS | SHA-512 checksum manifest |
| SHA2-512SUMS.sig | OpenPGP signature for SHA2-512SUMS |
| public.key | Convenience copy of the release public key |
| planwright_sbom.spdx.json | SPDX JSON SBOM |
| planwright_sbom.cdx.json | CycloneDX JSON SBOM |
Planwright signs checksum manifests with a maintainer-controlled OpenPGP release key. Treat the documented fingerprint in docs/releases/signing.md, a maintainer-controlled announcement or another trusted channel as the trust root; public.key is only a convenience release asset.
Example verification on Linux:
curl -LO https://github.com/steadytao/planwright/releases/latest/download/public.key
curl -LO https://github.com/steadytao/planwright/releases/latest/download/SHA2-256SUMS
curl -LO https://github.com/steadytao/planwright/releases/latest/download/SHA2-256SUMS.sig
gpg --import ./public.key
gpg --verify ./SHA2-256SUMS.sig ./SHA2-256SUMS
sha256sum -c ./SHA2-256SUMS --ignore-missing
gh attestation verify ./planwright_linux_amd64 -R steadytao/planwrightExample verification on Windows:
Invoke-WebRequest -Uri "https://github.com/steadytao/planwright/releases/latest/download/public.key" -OutFile "public.key"
Invoke-WebRequest -Uri "https://github.com/steadytao/planwright/releases/latest/download/SHA2-256SUMS" -OutFile "SHA2-256SUMS"
Invoke-WebRequest -Uri "https://github.com/steadytao/planwright/releases/latest/download/SHA2-256SUMS.sig" -OutFile "SHA2-256SUMS.sig"
gpg --import .\public.key
gpg --verify .\SHA2-256SUMS.sig .\SHA2-256SUMS
(Get-FileHash .\planwright_windows_amd64.exe -Algorithm SHA256).Hash.ToLower()
Select-String -Path .\SHA2-256SUMS -Pattern "planwright_windows_amd64.exe"
gh attestation verify .\planwright_windows_amd64.exe -R steadytao/planwrightPlanwright does not currently include a self-update command. Download the new release binary and replace the old executable after verifying the checksum manifest.
Planwright release binaries are intended to run without Terraform, OpenTofu, AWS CLI, kubectl, Helm, Kustomize, OPA or Rego installed. Those tools are not invoked by Planwright currently; they may still be useful around Planwright for preparing input files or reviewing generated output.
For source builds, install:
- Go as declared by go.mod
- Git
- OpenPGP tooling such as GnuPG if you want to verify release manifests
Build the CLI from source:
git clone https://github.com/steadytao/planwright.git
cd planwright
go build -o planwright ./cmd/planwright
./planwright versionOn Windows:
git clone https://github.com/steadytao/planwright.git
cd planwright
go build -o planwright.exe ./cmd/planwright
.\planwright.exe versionThe quickest useful Planwright path is the AWS web application example:
go run ./cmd/planwright validate examples/aws-webapp-basic/planwright.yaml
go run ./cmd/planwright risks examples/aws-webapp-basic/planwright.yaml
go run ./cmd/planwright cost-notes examples/aws-webapp-basic/planwright.yaml
go run ./cmd/planwright generate terraform examples/aws-webapp-basic/planwright.yaml --out ./generated/terraform
go run ./cmd/planwright generate mermaid examples/aws-webapp-basic/planwright.yaml --out ./generated/diagrams
go run ./cmd/planwright pack examples/aws-webapp-basic/planwright.yaml --out ./planwright-packThat path produces:
- validation output
- Markdown security and cost notes
- Terraform/OpenTofu-oriented review files
- a Mermaid architecture diagram
- a directory-based Planwright pack with a manifest, graph, reports, generated files and diagrams
Read the full walkthrough in examples/aws-webapp-basic/README.md.
Planwright is CLI-first. The current command surface is:
planwright validate <planwright.yaml>
planwright validate-graph <planwright.graph.json>
planwright explain <planwright.yaml>
planwright generate terraform <planwright.yaml> --out <dir>
planwright generate mermaid <planwright.yaml> --out <dir>
planwright risks <planwright.yaml>
planwright cost-notes <planwright.yaml>
planwright docs check [path ...]
planwright import cloudformation <template.yaml> --out <graph.json> --loss-report <loss.md>
planwright import sam <template.yaml> --out <graph.json> --loss-report <loss.md>
planwright import k8s <manifest-path-or-dir> --out <graph.json> --loss-report <loss.md>
planwright import awsscan <bundle-dir> --out <graph.json> --loss-report <loss.md>
planwright diff <old.graph.json> <new.graph.json> --out <review.md>
planwright schema graph --out <schema.json>
planwright policy profiles
planwright policy graph <planwright.graph.json> --profile <profile> --out <policy.md> --sarif <policy.sarif>
planwright pack <planwright.yaml> --out <dir>
planwright review terraform-plan <tfplan.json> --out <review.md> --sarif <planwright.sarif>
planwright serve [project-dir] [--addr 127.0.0.1:5786]
planwright version
Planned commands such as tui, scan aws, generate kubernetes, custom policy packs and OPA/Rego policy execution are not part of v0.11.
Canonical walkthrough:
- examples/aws-webapp-basic/README.md, the current v0.12 proof path
Validate the example plan:
go run ./cmd/planwright validate examples/aws-webapp-basic/planwright.yamlGenerate Terraform/OpenTofu-oriented review files:
go run ./cmd/planwright generate terraform examples/aws-webapp-basic/planwright.yaml --out ./generated/terraformGenerate a Mermaid diagram:
go run ./cmd/planwright generate mermaid examples/aws-webapp-basic/planwright.yaml --out ./generated/diagramsCreate a local Planwright pack directory:
go run ./cmd/planwright pack examples/aws-webapp-basic/planwright.yaml --out ./planwright-packReview a Terraform plan JSON fixture:
go run ./cmd/planwright review terraform-plan examples/terraform-plan-risk-review/tfplan.json --out ./generated/terraform-review.md --sarif ./generated/planwright.sarifStart the current local browser workbench:
go run ./cmd/planwright serve . --addr 127.0.0.1:5786Planwright is in the v0.12 usability and proof stage. The immediate focus is making the existing engine easy to understand, run and review through one polished proof path rather than expanding the feature surface.
Current implemented surfaces:
- Go CLI
planwright.v1typed plan parserplanwright.graph.v1architecture graph model- JSON Schema 2020-12 export and local graph validation
- graph lowering for the first AWS web application pattern
- Terraform/OpenTofu-oriented review output for that first AWS pattern
- Mermaid architecture diagram output
- Markdown reports for security, cost, deployability, cleanup and assumptions
- directory-based Planwright pack output
- CloudFormation and SAM subset import with loss reports
- rendered Kubernetes manifest import with Gateway API and Cilium inventory support
- local AWS scan bundle import from selected AWS CLI JSON artefacts
- Terraform plan JSON review with Markdown and SARIF output
- local graph JSON diff review
- built-in
lab,small-businessandproductionpolicy profile review - text-and-table local browser workbench through
planwright serve - GitHub Actions CI for tests, linting, static analysis, vulnerabilities, docs, workflow validation and supply-chain hygiene
Important deferred surfaces:
- Terraform state import
- Terraform HCL or module evaluation
- Terraform provider schema ingestion
- Pulumi import
- Kubernetes generation
- Kubernetes live cluster scans
- live AWS account scans
- AWS SDK integration
- AWS credential loading
- complete CloudFormation or SAM import
- lossless conversion or round-trip import
- zip archive pack output
- hosted demo
- drag-and-drop visual canvas editing
- resource-card graph planning
- Terraform/OpenTofu execution
- live drift proof
- custom policy packs
- OPA/Rego integration
- compliance certification
- reproducible build guarantees
| Level | Meaning |
|---|---|
| 0 | Preserved only as original source |
| 1 | Syntax parsed |
| 2 | Resource inventory extracted |
| 3 | Relationships inferred |
| 4 | Lowered into Planwright graph |
| 5 | Generated into another format |
| 6 | Round-trip tested with fixtures |
| 7 | Deployability tested in a sandbox |
| 8 | Production-profile validated |
Current support is intentionally partial. The typed plan path reaches level 5 for the first built-in AWS web application pattern. CloudFormation, SAM, rendered Kubernetes manifests and local AWS scan bundles reach level 4 for their supported subsets. Terraform plan JSON review is level 2 plus selected review findings because it does not lower Terraform plans into the Planwright graph yet.
See docs/compatibility.md for the matrix and current limitations.
Planwright defaults to local analysis.
In the current implementation it:
- reads explicit local plan, graph, template, manifest and scan-bundle files
- emits local validation, review and explanation output
- writes local generated artefacts only when explicitly asked
- runs a loopback-only local browser workbench when explicitly started
- rejects unexpected Host headers in the local web server
- does not read cloud credentials
- does not contact cloud APIs
- does not contact Kubernetes clusters
- does not deploy or destroy infrastructure
- does not execute imported content
- does not run the AWS CLI, AWS SDK,
kubectl, Helm, Kustomize, Terraform, OpenTofu, OPA or Rego - does not certify compliance
Future live scan features must remain read-only by default and require explicit account, region and identity confirmation.
Start with docs/README.md.
Core documents:
- docs/roadmap.md, full version-gated roadmap
- docs/compatibility.md, compatibility matrix and import boundaries
- docs/architecture/design.md, engine design and product boundary
- docs/architecture/threat-model.md, current local-first threat model
- docs/architecture/decisions/, ADRs
- docs/releases/README.md, release process
- docs/releases/signing.md, release signing model
Useful local checks:
go test ./...
go vet ./...
go build ./cmd/planwright
golangci-lint config verify --config .github/config/golangci.yml
golangci-lint fmt --config .github/config/golangci.yml --diff
golangci-lint run --config .github/config/golangci.yml
go test -race ./...
staticcheck ./...
gosec ./...
govulncheck ./...
go mod verify
go mod tidy -diff
go run ./cmd/planwright docs check .
npx --yes cspell@10.0.1 lint "**/*.md" ".github/**/*.yml" ".github/**/*.yaml" --config .github/config/cspell.json --no-progress --no-summary --no-must-find-files
python3 .github/scripts/ci/check_action_pins.py
python3 .github/scripts/ci/check_file_headers.py
python3 .github/scripts/release/generate_contributors.py --check
actionlint
pre-commit run --all-filesEach roadmap version must finish with a full codebase pass for security, correctness, compatibility, documentation consistency and accidental generated artefacts before the next version starts.
Before opening an issue or pull request, read .github/CONTRIBUTING.md.
All commits must be signed off in accordance with the Developer Certificate of Origin. See docs/project/DCO.md.
Governance is documented in docs/project/GOVERNANCE.md, docs/project/MAINTAINERS.md and .github/CODEOWNERS.
Support expectations are documented in .github/SUPPORT.md.
Please do not report security vulnerabilities in public issues.
See .github/SECURITY.md for reporting guidance.
Planwright is independent open-source infrastructure tooling.
If Planwright is useful to your work or organisation, sponsorship helps fund maintenance, compatibility fixtures, security review and release infrastructure.
Sponsor the project through GitHub Sponsors.
Planwright is released under the Apache License 2.0. See LICENSE.
AUTHORS is the curated copyright-purpose author list.
CONTRIBUTORS is the contributor-recognition list.
See CHANGELOG.md.