---
title: Quick Start
description: Get the tld CLI installed, authenticated, and publishing diagrams
  in under five minutes.
editUrl: true
head: []
template: doc
sidebar:
  hidden: false
  attrs: {}
pagefind: true
draft: false
---

## 1. Install

Pick your method:

```bash
# 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:

```bash
tld version
# tld v2.x.x
```
## 2. Start the local server

```bash
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](/docs/tld/editor) for a walkthrough of the interface and features.

When you're ready to save:

```bash

### 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:

```bash
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:

```bash
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:

```bash
tld plan
```

Review what was found. If it looks good:

```bash
tld apply
```


### Path D: Write YAML by hand

Create your elements:

```bash
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:

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

Preview:

```bash
tld plan
tld apply
```


## 5. Log in for cloud sync (optional)

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

```bash
tld login
```

## 6. Next steps

Now that you've got the basics:

- Understand the [workspace structure](/docs/tld/workspace) , what's in those YAML files
- Read about [linting rules](/docs/tld/linting-rules) , keep your diagrams clean
- Learn the [sync commands](/docs/tld/pull-export) , 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](https://marketplace.visualstudio.com/items?itemName=tlDiagram-com.tldiagram). 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.