Workspace & Init

Your workspace is a directory — usually .tld/ at the root of your project — holding YAML files that describe your entire architecture. Clean, simple, version-controllable.

Initializing a workspace

tld init

This creates a .tld/ directory with four files:

.tld/
  .tld.yaml          # workspace config
  elements.yaml      # your architecture elements
  connectors.yaml    # relationships between elements
  .tld.lock          # sync state (created on first sync)

tld init also generates a sensible .tld.yaml for you: it takes the project name from the git root, picks an exclude profile based on the dominant language, and adds the git remote as a repository entry with mode: upsert.

tld init <dir> treats the argument as a content root and always creates the workspace in a .tld/ subdirectory, so tld init and tld init . behave the same. Arguments that already name a workspace (.tld, tld, or an existing workspace directory) are used as-is.

The wizard

For control over the details, use the wizard. It prompts for project name, repositories, and per-repository mode, and detects your git remote.

tld init --wizard

Workspace structure

.tld.yaml — workspace config

Project-level configuration, committed with your diagrams.

.tld.yaml

project_name: my-api

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

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

exclude keeps generated and vendored files out of indexing. repositories connects diagrams to source code: add one entry per repository in a multi-repo workspace and set localDir or root when source doesn’t live next to .tld/. Each repository has a mode: upsert (add and update, never delete), manual (no automatic changes), or auto (create, update, and delete from source).

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
  repository_id: github.com/org/my-api
  file_path: cmd/gateway/main.go
  symbol: main
  tags: [entrypoint, public]
  has_view: true
  placements:
    - parent: root
      position_x: 0
      position_y: 0

user-db:
  name: User Database
  kind: database
  technology: PostgreSQL
  placements:
    - parent: root
      position_x: 300
      position_y: 0

Elements with has_view: true can be drilled into — they contain nested/child diagrams. file_path and symbol link an element to a real code symbol; repository_id ties it to an indexed repository.

connectors.yaml — relationships

connectors.yaml

- view: root
  source: api-gateway
  target: user-db
  label: queries users
  direction: forward
  relationship: reads
  tags: [hot-path]

The view field places the connector in a specific diagram. Most connectors live in the root view.

Schema validation

tld init prepends a # yaml-language-server: $schema=... comment to elements.yaml and connectors.yaml, so editors with the YAML language server can run static checks.

.tld.lock — sync state

Generated automatically. Tracks the last sync point, resource counts, a hash of your workspace, and per-resource metadata. Don’t edit it by hand. It’s how tld pull and the CLI commands know what changed.

Global config

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

~/.config/tldiagram/tld.global.yaml

This holds cloud credentials (server_url, api_key, org_id) and machine preferences like the default server port and data directory. tld login writes here automatically. Manage it with tld config:

tld config list
tld config set serve.port 9090

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

Multiple workspaces

Each project gets its own .tld/. Run tld commands from within a project, or point at any workspace with -w:

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

For multiple repositories in one workspace, add each under repositories in .tld/.tld.yaml, then run tld index <path> against the repo you want to scan.