---
title: Configuration
description: Full reference for tld configuration , global config, workspace
  config, environment variables, and all available settings.
editUrl: true
head: []
template: doc
sidebar:
  hidden: false
  attrs: {}
pagefind: true
draft: false
---

tld has two layers of configuration. They're simple but knowing what goes where saves you time.

## The two config layers

**Global config** lives at `~/.config/tldiagram/tld.yaml`. It's machine-wide , credentials, server preferences, and defaults that apply to every project on your computer.

**Workspace config** lives at `.tld/.tld.yaml` inside each project. Project-specific settings: project name, repository mappings, and exclude patterns.

## Environment variables

Global config values can be overridden with env vars. Workspace config is separate and stays in `.tld/.tld.yaml`.

| Variable | What it does |
|---|---|
| `TLD_CONFIG_DIR` | Override global config directory (default: `~/.config/tldiagram/`) |
| `TLD_DATA_DIR` | Override data directory for `tld serve` (SQLite + logs) |
| `TLD_SERVER_URL` | Cloud server URL (default: `https://tldiagram.com`) |
| `TLD_API_KEY` | API key for cloud sync commands |
| `TLD_ORG_ID` | Default organization/workspace identifier |
| `TLD_HOST` | Host for `tld serve` |
| `TLD_ADDR` | Bind address for `tld serve` (format: `host:port`) |
| `PORT` | Port for `tld serve` (default: `8060`) |
| `DEV` | Enable dev mode (internal) |

## Global config reference

Manage it with `tld config list`, `tld config get <key>`, and `tld config set <key> <value>`.

### Watch settings, explained

These control how `tld watch` and `tld watch diff` behave. Tuning them is how you get clean, readable diagrams instead of walls of boxes.

**Watcher modes**:
- `auto` , picks the best backend for your platform (fsnotify on Linux/macOS, polling fallback)
- `fsnotify` , event-based, fast, uses very little CPU
- `poll` , scans periodically, good for network drives or Docker volumes where fsnotify can't see changes

**Poll interval and debounce**: How often to check for changes, and how long to wait before reacting. Shorter values mean snappier updates but more CPU. The defaults (10s poll, 500ms debounce) are good for most projects.

**Embedding providers**: `tld watch` can optionally use vector embeddings to group related components semantically rather than just by folder structure. Supports any OpenAI-compatible endpoint. Set `provider` to `none` to disable entirely.

**Thresholds**: These are your noise control knobs. Thresholds collapse high-degree connections into a single group connector. Raise them for denser diagrams, lower them for cleaner ones.

**Visibility weights**: Fine-grained control over what gets shown vs hidden. The weights above are defaults that work well. Only tweak these if you really know what you're doing.

## Workspace config reference

```yaml
# .tld/.tld.yaml
project_name: my-project

repositories:
  my-repo:
    url: https://github.com/org/my-repo
    localDir: "."
    config:
      mode: upsert

exclude:
  - vendor/
  - node_modules/
  - .venv/
  - "**/*_test.go"
  - "**/*.pb.go"

```

### Repository modes

Each repo in your workspace gets a mode:

| Mode | Behavior |
|---|---|
| `upsert` | Scan adds new symbols, updates existing ones. Never deletes. Safe. Default. |
| `manual` | No automatic changes from scanning. You control everything. Use when YAML is the source of truth. |
| `auto` | Scan creates, updates, *and deletes* elements based on source. Use with caution , removed code means removed diagram elements. |

### Validation levels

Validation level is a global setting. It controls how strict `tld plan`, `tld validate`, and `tld check` are. See the full [linting rules reference](/docs/tld/linting-rules).

```yaml
validation:
  level: 2  # 1=Minimal, 2=Standard, 3=Strict
```

### Exclude patterns

Glob patterns matching files to skip during `tld analyze`. The defaults cover most build artifacts. Add your own if your project has custom generated directories or if we missed any.

## Priority order

When a setting exists in multiple places, settings are applied in this order of precedence (highest to lowest):

1. CLI flag (e.g., `--port 9090`)
2. Environment variable (e.g., `PORT=9090`)
3. Global config (`~/.config/tldiagram/tld.yaml`)
4. Built-in default

So `tld serve --port 9090` overrides everything. `TLD_ADDR=:9090` overrides config files but not flags.

## Setting up for a team

Commit your `.tld/` directory (including `.tld.yaml`) to version control. This shares the element and connector definitions with every team member.

For shared repository mappings and exclude rules, put them in the workspace `.tld.yaml`. Machine-specific credentials, local server settings, and watch thresholds belong in global config.

## Quick config inspection

```bash
# Where is my global config?
tld config path

# What's currently set?
tld config list

# Show secrets too (be careful)
tld config list --show-secrets

# One specific value
tld config get serve.port

# Change something
tld config set serve.port 9090

# Validate your config
tld config validate
```