Engineering workflow

Using the tld CLI to make architecture work reproducible

A command line can turn architecture maintenance into a repeatable engineering habit. The value comes from small, reviewable steps and a shared understanding of which representation is authoritative.

Architecture work often happens in several places: a conversation, a canvas, a repository, and a release review. When each starts from a different copy of the system, even a modest change can lead to contradictory diagrams. A command-line workflow helps teams make the state they intend to keep explicit, inspectable, and repeatable.

The open-source tld CLI is designed to work with tlDiagram diagrams. It can run a local editor, edit and inspect diagram resources, validate a workspace, and synchronize local YAML with a configured target. The exact command behavior depends on whether a workspace is initialized and which target is selected, so begin with tld context and the help for your installed version.

Choose how the project stores its model

A tlDiagram workflow can use the configured database directly, or an optional YAML workspace—typically a .tld/ directory—committed with the project. The workspace contains configuration and architecture resources such as elements and connectors. It is useful when a team wants ordinary version control and code review around diagram changes. A local or cloud-backed target may make sense when the team’s main editing flow is through the browser.

Do not assume these modes are interchangeable in every command. Without a workspace, commands generally use the configured database. In a workspace, some commands read its cache by default, and options can select live state. Establish the intended target before automating edits; a script that writes to the wrong environment is repeatable but not useful.

Start a workspace and make a small change

From the project root, the documented initialization command is:

tld init
tld context

Initialization creates the workspace structure and configuration. The context command reports the effective workspace and target so you can check where subsequent commands will read or write. If the project already has diagrams in a database, read the sync documentation before deciding how to bring them into YAML; avoid making two people’s working copies diverge.

Use the CLI to make a change with a clear architectural purpose, such as adding a service element or connecting two components. Then inspect the result and validate it:

tld list elements
tld inspect api-gateway
tld validate

These commands have different jobs. Listing helps locate resource references. Inspecting shows a resource’s properties and, depending on state sources, its presence in YAML, local database, or cloud. Validation checks structural problems such as missing references and invalid placements, as well as configured architecture warnings. A clean validation result does not prove that the model tells the right story; review remains necessary.

Use version control for decisions worth reviewing

When YAML is part of the repository, a diagram update can live alongside the implementation change that prompted it. Reviewers can ask whether a new dependency crosses an important boundary or whether a system context view needs another external actor. Keep the model at an architectural level. A private helper refactor usually does not warrant a new box, while a new data store or externally visible integration may deserve one.

After a browser edit, the CLI’s pull and sync workflows can move information between the target and workspace. Read the current sync guide and preview changes where supported before applying them. Treat the generated lock file as tool-managed state; the workspace documentation says not to edit it by hand.

Make checks useful in automation

A validation command can fit into a local checklist or CI job when its workspace and target are deterministic. Start with structural validity and decide separately whether advisory architecture warnings should fail the build. The documented tld validate --strict mode exits non-zero on architectural warnings; apply it only after the team understands the rules and has an agreed way to address or suppress them.

Keep automated checks proportional. Requiring every code change to update a diagram creates noise; asking for an update when a boundary or important dependency changes creates context. A short pull request prompt can establish that expectation without turning a diagram into a second source of routine implementation bookkeeping.

Keep the workflow small

Pick one view people already use, initialize or connect its workspace carefully, and practice one full change cycle: inspect the effective context, update a resource, validate, review the diff, and synchronize only when the chosen workflow calls for it. Refine the process after real use. The CLI supplies consistent operations; engineers still decide which architecture is meaningful and whether the diagram remains accurate.

See the CLI quick start, workspace guide, and open-source tld repository for current commands and behavior.