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

3. Build your first diagram

You have four paths from here. Pick the one that fits.

Path A: Use the web editor

The editor is designed hopefully intuitive enough to get you going without a tutorial. But if you want some guidance, check out the editor docs for a walkthrough of the interface and features.

When you’re ready to save:

### Path B: Use an AI agent

Install the tld skill for your AI coding agent:

```bash
# 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 commands to build your architecture. You can guide it:

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

Review and publish when ready:

tld plan
tld apply

Path C: Let the CLI scan your code

If you have a codebase with Go, TypeScript, Python, or other supported languages:

tld analyze .

This scans your source code, identifies architecture elements (services, databases, functions), maps their relationships (imports, calls, dependencies), and writes everything into .tld/elements.yaml and .tld/connectors.yaml.

It’ll take a few seconds. When it’s done:

tld plan

Review what was found. If it looks good:

tld apply

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"

Preview:

tld plan
tld apply

5. Log in for cloud sync (optional)

Connect the CLI to your cloud account, and apply your local diagrams.

tld login

6. Next steps

Now that you’ve got the basics:

• Understand the workspace structure , what’s in those YAML files
• Read about linting rules , keep your diagrams clean
• Learn the sync commands , how push/pull actually works

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.