---
title: Workspace & Init
description: Understand the tld workspace structure, initialization, and how
  your architecture diagrams live as code.
editUrl: true
head: []
template: doc
sidebar:
  hidden: false
  attrs: {}
pagefind: true
draft: false
---

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:

```bash
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:

```bash
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:

```bash
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.

```yaml
# .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:

```yaml
# 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:

```yaml
# 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:

```bash
tld config list
```

And change specific values:

```bash
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`:

```bash
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