Architecture diagrams can become stale in quiet ways: a connector points to a removed element, a source symbol moves, or a view accumulates enough detail to stop helping readers. The open-source tld CLI includes tld validate to check workspace structure and report architectural warnings. It gives a repeatable review step, while leaving architectural judgment with the team.
Run validation where the diagram lives
From a project with an initialized .tld/ workspace, start with:
tld validateThe command reads workspace YAML when present; otherwise it uses the configured database. You can explicitly choose a live source with --source live. Since CLI commands can target local or cloud state, check tld context if the active target is not obvious. Validation results are only meaningful when the command is checking the data you intended to review.
The structural checks cover issues such as connectors referring to nonexistent elements, duplicate refs, invalid placements, broken view references, and stale source symbols. Those are usually actionable errors: the model or source link no longer has a coherent target. Correct the underlying data before relying on a diagram in a review.
Understand warnings as signals
After structural validation, the CLI runs the architectural linter and groups findings by rule code. Rules flag common risks including overly dense views, isolated elements, missing metadata, vague names, unlabeled connectors, and limited source-link coverage. The checks are heuristics. A crowded view may be acceptable for a particular technical audience; an isolated element may be intentional. The output is a prompt to investigate, not proof that a design is wrong.
There are three strictness levels: minimal, standard (the documented default), and strict. You can select one for a run:
tld validate --strictness 1
tld validate --strictness 2
tld validate --strictness 3 --verboseThe levels progressively enable more checks. Use tld validate rules to see the current rule catalog and tld validate ARC001 to inspect details for a specific rule code, including violations and suggested remediation. Rule catalogs evolve, so consult the CLI output or current docs rather than hard-coding assumptions about every warning.
Choose how CI treats architectural warnings
By default, architectural warnings are advisory. They appear in validation output and in the editor, but do not make the command fail. This lets a team learn where its diagrams have quality gaps without unexpectedly blocking routine changes.
Once a team is ready to enforce selected expectations, pass --strict in CI:
tld validate --strictWith that flag, architectural warnings cause a non-zero exit status. Structural and source-symbol errors already fail validation regardless. In other words, strict mode changes the treatment of warnings; it is not required for structural failures to be detected.
Tune findings with care
Rule inclusion and exclusion are configurable in global CLI settings. For example, tld config set validation.exclude_rules ARC002 suppresses an identified rule, while include settings can add checks beyond the selected level. Read the current rule description first and make the change intentional: suppressing a warning changes what future reviews see.
When a finding appears, trace it back to a view and ask what the diagram is meant to communicate. A high-density warning may suggest splitting a context view into a few purposeful nested views. A missing description could mean that a team needs to record why a component exists. A low link-coverage warning may reveal that the model cannot yet be verified against indexed source. It can also reflect a deliberate choice to diagram external systems or conceptual boundaries that have no code symbol.
Fit validation into the review loop
For local work, run validation after editing YAML or making a significant visual change. In CI, validate the same workspace version that reviewers will inspect. Include the selected target and strictness policy in the team's contribution guidance so an engineer can reproduce the result. Keep the output near the change under review and address structural errors before debating heuristic warnings.
Validation is most useful when it stays proportionate. A fast command can protect a diagram from broken references and expose patterns that merit discussion. It cannot decide whether a boundary reflects the organization, whether a dependency is acceptable, or whether the view tells the right story. Use its checks to make review more consistent, then bring human context to the findings.