actions-marketplace-validations/mertcikla_tld

tld is an opinionated, flexible diagramming tool with rich featureset to help you visualize, understand, and maintain your software architecture. Inspired by C4 model, designed with multiple opt-in features to answer evolving needs of software teams.

Highlights

• UI: A frontend optimized to handle complex architectures, with intuitive design and polished with tools to manage contextual views.

• Standalone Distribution: A single, dependency-free binary containing both the server and the web application. Available as CLI + WebUI or Native app(windows and macOS).

• CLI that speaks agent: Use the agent skill and use your agent to create a diagram of your codebase with the exact detail level you need. Prompt the agent to add/remove details you see fit. Here are some examples that were generated using the agent skill.

  • Kubernetes

  • pytorch

  • kafka

  • .NET eShop reference

• Editor and Github Integration: Jump to the code in your editor or Github from diagrams, or open the code symbol in diagram from your editor to visualize the code using the VSCode extension.

• Markdown Notes Support: Add notes and documentation for your diagram or link an existing one, preview and edit diagrams and markdown side-by-side.

• Mermaid Integration: Easily sync your diagrams with mermaid blocks in a markdown file for portable viewing in any markdown viewer docs.

• Bi-directional Sync: Seamlessly sync changes between your local YAML files, the self-hosted web UI, and the cloud version at tlDiagram.com.

• Git diff visualization: Sync and visualize the changes you or your agent are making live in diagram form. Inspect the dependencies and intervene when necessary.

• Codebase Mapping: Generate source grounded elements to jump-start your diagramming process.

• Visualize Code Changes: Visualize the changes between commits or a PR docs.

• PR Diagram Bot: Automatically generate a diagram for your PR and visualize the changes in your codebase docs.

• Diagrams as Code: Manage architectural evolution alongside your source code.

Quick Start

macOS and Linux

curl -LsSf https://tldiagram.com/install.sh | sh -s serve --open

Windows

powershell -ExecutionPolicy ByPass -c "irm https://tldiagram.com/install.ps1 | iex; tld serve --open"

tld has native-desktop builds for macOS and windows. Look for tld-desktop binaries in releases.

Documentation

Visit docs for more info.

Deployment & Self-Hosting

tld designed to be run fully offline, behind a reverse-proxy or in your infrastructure or as a local development tool.

Run tld serve to start a local SQLite-backed instance, or configure PostgreSQL in ~/.config/tldiagram/tld.global.yaml or via env vars

export TLD_DB_DRIVER=postgres
export TLD_DATABASE_URL='postgres://user:pass@postgres:5432/tld?sslmode=require'
export TLD_PUBLIC_URL='https://example.com'
export TLD_HOST=127.0.0.1
export PORT=8060

tld serve

Docker

# SQLite
docker compose up

# Or PostgreSQL with pgvector, required by the core migrations
docker compose -f docker-compose.postgres.yml up

Mobile

There are Mobile apps available in both App Store and Play Store they are mostly cloud-oriented and free but require tldiagram.com account. They are good for quickly checking stuff on-the-go, small screens are hard for full featured diagram authoring but they still received some development effort and attention to make authoring possible on mobile.

Commands Reference

Run tld --help for a local diagram walkthrough and repository-analysis examples. Use tld --help for details, including these discovery commands:

tld list elements                 # Element refs, names, and database IDs
tld list connectors               # Keys for inspecting and updating connectors
tld list views --tree             # View owners and drill-down hierarchy
tld update element --help         # Editable fields, name changes, and YAML ref changes
tld update connector --help       # Editable fields, connector keys, and direction values
tld view --help                   # Create and manage an element's owned view
tld render --help                 # Export a required view as Mermaid

An element can appear in multiple views. Adding a child with --parent creates the parent’s view automatically; tld view create creates it explicitly. Ordinary mutations apply to their configured target immediately and refresh workspace YAML when present. Workspace ref changes only affect YAML.