Workspace & Init

Your workspace is where everything lives. It’s a directory, usually .tld/ at the root of your project , containing YAML files that describe your entire architecture. Clean, simple, version-controllable.

Initializing a workspace

Run this at your project root:

tld init

That’s it. Here’s what happens:

.tld/
  .tld.yaml          # workspace config
  elements.yaml      # your architecture elements
  connectors.yaml    # relationships between elements

Three files. That’s your entire architecture, as code.

The wizard

Not sure what to configure? Use the wizard:

tld init --wizard

It’ll walk you through project name, repository setup, and even detect your git remote automatically. Perfect for first-timers or complex setups.

Custom directory

Default workspace is .tld/. If you want a different name:

tld init my-diagrams

All commands with -w flag can point to any workspace directory. But honestly, .tld/ is conventional and keeps things tidy.

Workspace structure

Let’s look at what’s inside.

.tld.yaml - Workspace config

This is your project-level configuration. It lives in your workspace directory and tells tld how to behave.

.tld.yaml

project_name: my-api

repositories:
  my-api:
    url: https://github.com/org/my-api
    config:
      mode: upsert

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

The exclude list keeps generated and vendor files out of your diagrams. Smart defaults, but you’ll want to tune them for your project.

The repositories map is how you connect diagrams to actual source code. For multi-repo workspaces, add one entry per repository and set localDir or root when the source does not live next to .tld/.

elements.yaml - Your architecture elements

Every service, database, queue, person, and system lives here. Each element has a reference key and properties:

elements.yaml

api-gateway:
  name: API Gateway
  kind: service
  technology: Go
  description: Routes incoming requests to internal services
  has_view: true
  placements:
    - parent: root
      position_x: 0
      position_y: 0

user-db:
  name: User Database
  kind: database
  technology: PostgreSQL
  description: Stores user accounts and profiles
  placements:
    - parent: root
      position_x: 300
      position_y: 0

Elements with has_view: true can be drilled into , they contain child diagrams showing their internal architecture.

connectors.yaml - Relationships

How elements talk to each other:

connectors.yaml

- view: root
  source: api-gateway
  target: user-db
  label: queries users
  direction: forward
  relationship: reads

The view field places the connector in a specific diagram. Most connectors live in the root view, but you can scope them to child views too.

.tld.lock - Sync state

Generated automatically. Tracks the last sync point with the configured target , when you last pushed or pulled, the version ID, and a hash of your workspace. Don’t edit this file. It’s how tld diff and tld sync status know what changed.

Global config

Separate from your workspace config, tld keeps a global configuration file:

~/.config/tldiagram/tld.yaml

This holds your cloud version credentials (server_url, api_key, org_id) and global preferences like default port and host for tld serve. The tld login command writes here automatically.

You can inspect it with:

tld config list

And change specific values:

tld config set serve.port 9090

Override the config directory with the TLD_CONFIG_DIR environment variable if you need a custom location.

Multiple workspaces

You can have as many workspaces as you want on the same machine. Each project gets its own .tld/ directory. Run tld commands from within your project directory, or point to any workspace with -w:

tld plan -w /path/to/other/.tld

For multiple git repositories inside a single workspace, add each repository under repositories in .tld/.tld.yaml, then run tld analyze <path> against the repo you want to scan.

Next steps

Once tld init is done, you’ll want to:

1. Run tld login to connect to the cloud version
2. Either tld analyze your codebase or manually write your YAML
3. Run tld plan to preview
4. Run tld apply to push