---
title: tld validate
description: Check diagram structure, source links, and architectural warnings.
editUrl: true
head: []
template: doc
sidebar:
  hidden: false
  attrs: {}
pagefind: true
draft: false
---

`tld validate` checks diagram structure, source links, and architectural warnings. It reads workspace YAML when present, otherwise the configured database. Use `--source live` to check the target directly.

```bash
tld validate
```

## What it catches

- **Missing elements**: a connector references an element that doesn't exist
- **Duplicate refs**: two elements with the same key
- **Invalid placements**: missing parents or an element placed inside its own view
- **Broken view references**: connectors pointing to views that don't exist
- **Stale symbols**: an element points at a file or symbol that moved or disappeared
- **Architectural warnings**: crowded views, missing metadata, and weak source coverage

A clean workspace prints a summary:

```
✓ Workspace valid: 42 elements, 12 views, 35 connectors
```

## Strictness levels

The validation level controls how strict checks are. Set it globally or override per run:

```bash
tld validate --strictness 1   # Minimal
tld validate --strictness 2   # Standard (default)
tld validate --strictness 3   # Strict — checks labels, descriptions, naming
tld validate --strictness 3 --verbose
```

## Architectural warnings

After structural validation, `tld validate` runs the architectural linter and prints a summary grouped by rule code:

```
Architectural Warnings (Level 2: Standard)

CODE     RULE              VIOLATIONS
ARC001   High Density      1
ARC002   Isolated Element  1
```

Pass a rule code to see its full detail, including every violating element and how to fix it:

```bash
tld validate ARC001
```

Run `tld validate rules` for the current catalog, or see [Linting Rules](/docs/tld/linting-rules). An explicit rule code runs even when excluded or above the configured strictness level.

## Warnings in CI

Architectural warnings are advisory by default. In CI, make them fail the build:

```bash
tld validate --strict
```

`--strict` exits non-zero on architectural warnings. Structural and source-symbol errors already fail validation.

## Suppressing rules

Suppress specific rule codes in global config:

```bash
tld config set validation.exclude_rules ARC002
```

## Flags

| Flag | Default | What it does |
|---|---|---|
| `--strictness` | config / 2 | Override validation level [1-3] |
| `-v, --verbose` | `false` | Show full architectural warning output |
| `--strict` | `false` | Exit non-zero on architectural warnings |
| `--source` | `auto` | Read `cache` or `live`; explicit `--target`/`--data-dir` selects live in auto mode |