terravision

Usage Guide

Quick Start Examples

Generate Your First Diagram

# Basic usage - analyze current directory
terravision draw

# Specify source directory
terravision draw --source ~/projects/my-terraform-code

# Open diagram automatically after generation
terravision draw --source ~/projects/my-terraform-code --show

---

Commands

terravision draw

Generates architecture diagrams from Terraform code.

Syntax:

terravision draw [OPTIONS]

Common Options:

Option	Description	Default	Example
--source	Source location (folder, Git URL, or JSON)	Current directory	./terraform
--format	Output format (png, svg, pdf, bmp)	png	--format svg
--outfile	Output filename	architecture	--outfile my-diagram
--workspace	Terraform workspace	default	--workspace production
--varfile	Variable file (can use multiple times)	None	--varfile prod.tfvars
--show	Open diagram after generation	False	--show
--simplified	Generate simplified high-level diagram	False	--simplified
--annotate	Path to annotations YAML file	None	--annotate custom.yml
--aibackend	AI backend (bedrock, ollama)	bedrock	--aibackend ollama
--planfile	Pre-generated Terraform plan JSON	None	--planfile plan.json
--graphfile	Pre-generated Terraform graph DOT	None	--graphfile graph.dot
--debug	Enable debug output	False	--debug

terravision graphdata

Exports resource relationships and metadata as JSON.

Syntax:

terravision graphdata [OPTIONS]

Common Options:

Option	Description	Default	Example
--source	Source location	Current directory	./terraform
--outfile	Output JSON filename	architecture.json	--outfile resources.json
--show_services	Show only unique services list	False	--show_services
--planfile	Pre-generated Terraform plan JSON	None	--planfile plan.json
--graphfile	Pre-generated Terraform graph DOT	None	--graphfile graph.dot

---

Usage Examples

Local Terraform Directory

# Generate PNG diagram
terravision draw --source ./terraform

# Generate SVG diagram with custom name
terravision draw --source ./terraform --format svg --outfile my-architecture

# Use specific workspace
terravision draw --source ./terraform --workspace production

# Use variable files
terravision draw --source ./terraform --varfile prod.tfvars --varfile secrets.tfvars

Remote Git Repositories

# Analyze entire repository
terravision draw --source https://github.com/user/terraform-repo.git

# Analyze specific subfolder
terravision draw --source https://github.com/user/terraform-repo.git//aws/vpc

# Analyze specific branch
terravision draw --source https://github.com/user/terraform-repo.git?ref=develop

Multiple Output Formats

# Generate all formats
terravision draw --source ./terraform --format png --outfile arch-png
terravision draw --source ./terraform --format svg --outfile arch-svg
terravision draw --source ./terraform --format pdf --outfile arch-pdf

# Batch processing
for format in png svg pdf; do
  terravision draw --source ./terraform --format $format --outfile arch-$format
done

Working with Annotations

# Use annotations file
terravision draw --source ./terraform --annotate custom-annotations.yml

# Annotations file will be auto-loaded if named terravision.yml in source directory
terravision draw --source ./terraform

See ANNOTATIONS.md for annotation file format.

Export and Reuse Graph Data

# Export graph data
terravision graphdata --source ./terraform --outfile graph.json

# Generate diagram from exported data (faster)
terravision draw --source graph.json --format svg

# Show only services used
terravision graphdata --source ./terraform --show_services

Debug Mode

# Enable debug output
terravision draw --source ./terraform --debug

# This creates tfdata.json which can be reused
terravision draw --source tfdata.json --format svg

---

Output Formats

TerraVision supports all output formats provided by Graphviz. Use the --format option to specify your desired format.

Common Formats

Format	Description	Best For
png	Portable Network Graphics (default)	Documentation, wikis, presentations
svg	Scalable Vector Graphics	Web pages, scalable diagrams, editing
pdf	Portable Document Format	Reports, printing, professional docs
jpg / jpeg	JPEG image	Photos, web (lossy compression)
gif	Graphics Interchange Format	Simple graphics, animations
bmp	Windows Bitmap	Windows applications
eps	Encapsulated PostScript	Print publishing, LaTeX
ps / ps2	PostScript	Print publishing
tif / tiff	Tagged Image File Format	High-quality archival
webp	WebP format	Modern web (good compression)
dot	Graphviz DOT source	Further editing, custom rendering
json	Graphviz JSON with layout info	Advanced programmatic processing (note: different from graphdata output)
xdot	Extended DOT with layout	Advanced rendering applications

For the complete list of supported formats, see the Graphviz Output Formats documentation.

Note: --format json produces Graphviz’s internal JSON format with layout coordinates. For TerraVision’s simple graph dictionary (just nodes and connections), use the graphdata command instead.

PNG (Default)

• Use for: Documentation, wikis, presentations
• Pros: Universal support, good quality
• Cons: Not scalable, larger file size

terravision draw --source ./terraform --format png

SVG

• Use for: Web pages, scalable diagrams
• Pros: Scalable, smaller file size, editable
• Cons: Some tools don’t support SVG

terravision draw --source ./terraform --format svg

PDF

• Use for: Reports, documentation, printing
• Pros: Professional, portable, printable
• Cons: Larger file size

terravision draw --source ./terraform --format pdf

Pre-Generated Plan Input

If you already have Terraform plan and graph output files (e.g. from a CI/CD pipeline), you can generate diagrams without running Terraform. This is useful when:

• Terraform runs in a separate pipeline step or environment
• Cloud credentials are not available in the diagram generation environment
• You want to generate diagrams from archived plan files

Step 1: Generate plan and graph files (in your Terraform environment):

cd /path/to/terraform
terraform init
terraform plan -out=tfplan.bin
terraform show -json tfplan.bin > plan.json
terraform graph > graph.dot

Step 2: Generate diagrams (no Terraform or cloud credentials needed):

# Draw diagram from pre-generated files
terravision draw --planfile plan.json --graphfile graph.dot --source ./terraform

# Export graph data from pre-generated files
terravision graphdata --planfile plan.json --graphfile graph.dot --source ./terraform --outfile resources.json

# Combine with other options
terravision draw --planfile plan.json --graphfile graph.dot --source ./terraform \
  --format svg --outfile my-architecture --annotate custom.yml

Requirements:

• --planfile must be a JSON file from terraform show -json (not a binary .tfplan file)
• --graphfile must be a DOT file from terraform graph
• --source must point to the Terraform source directory (for HCL parsing)
• All three options (--planfile, --graphfile, --source) are required together

Notes:

• --workspace and --varfile are ignored when --planfile is used (a warning is printed)
• Terraform does not need to be installed when using --planfile mode
• The plan JSON must contain resource_changes with at least one resource

See CI/CD Integration for pipeline examples using pre-generated plan files.

---

Advanced Usage

Multiple Environments

# Generate diagrams for different environments
terravision draw --source ./terraform --varfile dev.tfvars --outfile arch-dev
terravision draw --source ./terraform --varfile staging.tfvars --outfile arch-staging
terravision draw --source ./terraform --varfile prod.tfvars --outfile arch-prod

Simplified Diagrams

For large infrastructures, generate high-level overview:

terravision draw --source ./terraform --simplified --outfile overview

AI-Powered Refinement

# Use AWS Bedrock (default)
terravision draw --source ./terraform --aibackend bedrock

# Use local Ollama
terravision draw --source ./terraform --aibackend ollama

See AI_REFINEMENT.md for setup instructions.

---

Performance Tips

Large Terraform Projects

1. Use simplified mode for overview diagrams:

   terravision draw --source ./terraform --simplified
   

2. Export to JSON first, then generate multiple variants:

   terravision graphdata --source ./terraform --outfile graph.json
   terravision draw --source graph.json --format png
   terravision draw --source graph.json --format svg
   

3. Use specific workspaces to reduce scope:

   terravision draw --source ./terraform --workspace production
   

Batch Processing

# Process multiple Terraform directories
for dir in terraform/*; do
  terravision draw --source $dir --outfile $(basename $dir)
done

---

Common Workflows

Daily Development

# Quick check of current infrastructure
terravision draw --show

Code Review

# Generate diagram for PR review
terravision draw --source ./terraform --format svg --outfile pr-${PR_NUMBER}

Documentation Updates

# Generate all formats for documentation
terravision draw --format png --outfile docs/images/architecture
terravision draw --format svg --outfile docs/images/architecture

CI/CD Pipeline

# Generate diagram with build number
terravision draw --format svg --outfile architecture-${BUILD_NUMBER}

See CICD_INTEGRATION.md for complete CI/CD examples.

---

Next Steps

• Annotations Guide - Customize your diagrams
• CI/CD Integration - Automate diagram generation
• Troubleshooting - Common issues and solutions

This site is open source. Improve this page.