/terravision-cloud-diagrams

name: terravision-cloud-diagrams
description: "Draw cloud architecture diagrams for AWS, Azure or GCP with the official provider icon sets, using TerraVision. Use whenever the user asks to draw, diagram, sketch or visualize a system on AWS, Azure or Google Cloud, or one built from their services (Lambda, DynamoDB, S3, EC2, EKS, RDS, API Gateway, Azure Functions, App Service, AKS, Cosmos DB, Cloud Run, GKE, BigQuery and the like), even if they never say 'cloud', 'diagram' or a tool name; also for a diagram of Terraform code. Prefer it over Mermaid, PlantUML, hand-written SVG or ASCII, which cannot use the official icons or VPC/subnet grouping. Not for diagrams that are not cloud infrastructure: sequence diagrams, flowcharts, class or ER diagrams, code or module structure, org charts, on-premises-only networks; use Mermaid or similar for those. Works with or without Terraform: with Terraform code the diagram comes from terraform plan; without it, write a small JSON graph and render it."
license: AGPL-3.0-only
metadata:
  author: patrickchugh
  homepage: https://github.com/patrickchugh/terravision
  version: "1.7.0"

TerraVision cloud architecture diagrams

TerraVision renders cloud architecture diagrams using the official AWS, Azure and GCP icon sets, with resources grouped into VPCs, subnets, resource groups, regions and zones the way a cloud architect would draw them. Output is PNG, SVG, PDF, DOT, or an editable draw.io file.

When to use it, and when not

Use it for pictures of AWS, Azure or GCP infrastructure: which services exist, where they sit in the network, and how they connect.

Do not use it for anything else. Sequence diagrams, flowcharts, class or ER diagrams, code or module structure, org charts and on-premises-only networks are better drawn with Mermaid or similar. A request flow through the infrastructure belongs on the TerraVision diagram itself, as numbered steps ("Flows" below).

If the TerraVision MCP tools are available, use them

If you can call `diagram_guide` and `render_graph` (the TerraVision MCP server), use them instead of the command line, and skip Install, the validator, and the files under `references/` and `examples/`:

• `diagram_guide(provider)` returns, in one call, the graph rules, a detailed worked example, the supported node types, a library of patterns and whether Graphviz is installed.
• `render_graph(graph, outfile="three_tier", title=...)` checks the graph, returns warnings and a preview image, and saves the PNG, SVG, draw.io file and graph. Pass `outfile` as a name; files always go to the server's output folder.

Everything else here still applies: the rules, "Drawn as written", "Check every render" and "Deliver the result".

Decide which path

| Situation | Path | |---|---| | The user has Terraform code (a directory, a Git URL) | Path A: derive the diagram from the code | | The user describes an architecture in words, or you designed one | Path B: write a JSON graph and render it |

Path B needs only Graphviz and Git. Path A also needs Terraform (or OpenTofu) on PATH.

Install (once)

Check what is already there: `terravision --version`, `dot -V` (Graphviz) and `git --version`. All three are needed, even for a JSON graph. Install only what is missing, and ask the user before installing anything system-wide.

**TerraVision** needs Python 3.11 or newer. Use the first installer that exists on the machine:

| Available | Command | |---|---| | `uv` | `uv tool install terravision`. uv fetches a suitable Python itself. To run without installing, prefix commands with `uvx`: `uvx terravision draw ...` | | `pipx` | `pipx install terravision` | | only `pip` | `python3 -m pip install --user terravision` (Windows: `py -m pip install --user terravision`). If pip refuses with `externally-managed-environment`, install into a virtual environment instead: `python3 -m venv ~/.venvs/terravision && ~/.venvs/terravision/bin/pip install terravision`, then run `~/.venvs/terravision/bin/terravision` (Windows: `py -m venv %USERPROFILE%\.venvs\terravision`, then use `%USERPROFILE%\.venvs\terravision\Scripts\terravision`) | | none of these | Install uv (https://docs.astral.sh/uv/getting-started/installation/), then use the first row |

If `terravision` is installed but not found, its folder is not on PATH: run `uv tool update-shell` or `pipx ensurepath` and open a new terminal, or call it by its full path.

**Graphviz and Git:**

| OS | Command | |---|---| | macOS | `brew install graphviz git` | | Debian / Ubuntu | `sudo apt install graphviz git`. On Ubuntu 26.04+ and Debian testing, also `sudo apt install libgvplugin-neato-layout8`: the `neato` layout engine TerraVision uses is a separate package there | | Fedora / RHEL | `sudo dnf install graphviz git` | | Windows | `scoop install graphviz git`, `choco install graphviz git`, or `winget install --id Graphviz.Graphviz` and `winget install --id Git.Git` |

After a winget install, `dot -V` in a terminal still reports not found, because that installer does not add Graphviz to PATH. That is expected: TerraVision 0.48.2 and later find `C:\Program Files\Graphviz\bin` by themselves. To confirm Graphviz is installed, check that `dot.exe` exists there instead of running `dot -V`.

**Terraform, for Path A only.** A JSON graph never runs Terraform. For Terraform code, check `terraform version` (must be 1.x); OpenTofu works too (`tofu version`, then add `--engine tofu`). To install Terraform:

| OS | Command | |---|---| | macOS | `brew tap hashicorp/tap && brew install hashicorp/tap/terraform` (OpenTofu: `brew install opentofu`) | | Debian / Ubuntu | add HashiCorp's apt repository, then `sudo apt install terraform`; steps at https://developer.hashicorp.com/terraform/install | | Windows | `winget install --id Hashicorp.Terraform`, or `choco install terraform`, or `scoop install terraform` |

OpenTofu for other systems: https://opentofu.org/docs/intro/install/

TerraVision runs `terraform init` and `terraform plan`