Configuration

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

.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.

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

# 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