Quick Start

1. Install

Pick your method:

# Direct download (Linux, macOS)
curl -LsSf https://tldiagram.com/install.sh | sh

# Homebrew (macOS)
brew install --cask Mertcikla/tap/tld

# Windows PowerShell
irm https://tldiagram.com/install.ps1 | iex

Verify it worked:

tld version
# tld v2.x.x

2. Start the local server

tld serve --open

The full editor opens at http://127.0.0.1:8060. Everything runs locally against an embedded SQLite database.

3. Build your first diagram

Pick the path that fits.

Path A: Use the web editor

Create elements and connectors directly on the canvas. When you’re done, run tld pull to refresh your workspace YAML from the browser state:

tld pull

See the editor docs for a walkthrough of the interface.

Path B: Use an AI agent

Install the tld skill for your AI coding agent:

# For agents that support the skills protocol
npx skills add Mertcikla/tld

# For Gemini
gemini extensions install https://github.com/Mertcikla/tld

Then ask:

“Create a diagram of this codebase”

The agent uses tld add, tld connect, and tld validate to build your architecture. Guide it as it goes:

“Add more detail on the authentication flow in the backend”

Path C: Let the CLI map your code

If you have a codebase with Go, TypeScript, Python, or another supported language:

tld index .

This indexes your source into a code graph and publishes a snapshot. Open Repositories in the local editor to browse it, or add --map to group the graph into architectural components. To visualize a set of changes:

tld git compare HEAD~1 HEAD

This map is useful for grounding and linking your architectural abstracts to the actual code. Helps keep your diagrams accurate and up to date, and allows new team members to explore the codebase from the diagram.

Path D: Write YAML by hand

Create your elements:

tld add api-gateway --kind service --technology Go
tld add user-db --kind database --technology PostgreSQL
tld add auth-svc --kind service --technology Rust

Connect them:

tld connect --from api-gateway --to auth-svc --label "authenticates"
tld connect --from auth-svc --to user-db --label "queries"

Commands apply immediately and write through to .tld/elements.yaml and .tld/connectors.yaml. Check your work:

tld validate

4. Log in for cloud sync (optional)

Connect the CLI to your cloud account and point commands at the remote target:

tld login
tld add my-service --target remote

Installation troubleshooting

“command not found: tld” — The binary went somewhere your shell doesn’t know about. Add the install path to your PATH. By default it’s $HOME/.local/bin or /usr/local/bin.

Homebrew: “cask not found” — Make sure you tapped the repo first: brew tap Mertcikla/tap && brew install --cask tld.

“Permission denied” with curl install — The install script needs write access to the install directory. Run with sudo or install to a user-owned directory: curl -LsSf https://tldiagram.com/install.sh | INSTALL_DIR=~/.local/bin sh.

“Unsupported platform” — We build for macOS, Linux, and Windows on amd64/arm64. Compile from source if you’re on something else.

VS Code Extension

If you use VS Code, install the official extension. It lets you:

• Open .tld files directly in your IDE
• Preview diagrams alongside your source code
• Link architecture elements to specific files
• Edit YAML with autocompletion for element refs

It’s the same YAML, just a nicer editing experience.