Configuration

tld has two layers of configuration.

Global config lives at ~/.config/tldiagram/tld.global.yaml. It’s machine-wide: credentials, server preferences, indexing tools, and defaults that apply to every project.

Workspace config lives at .tld/.tld.yaml inside each project for settings like: project name, repositories, and exclude patterns.

Environment variables

Global config values can be overridden with env vars. Workspace config stays in .tld/.tld.yaml.

Variable	What it does
`TLD_CONFIG_DIR`	Override global config directory (default: `~/.config/tldiagram/`)
`TLD_DATA_DIR`	Override data directory (SQLite + logs)
`TLD_SERVER_URL`	Cloud server URL (default: `https://tldiagram.com`)
`TLD_API_KEY`	API key for cloud sync
`TLD_ORG_ID`	Default organization/workspace identifier
`TLD_HOST`	Host for `tld serve` (default: `127.0.0.1`)
`TLD_ADDR`	Bind address for `tld serve` (`host:port`; overrides host and port)
`PORT`	Port for `tld serve` (default: `8060`)
`TLD_DB_DRIVER`	`sqlite` or `postgres`
`TLD_DATABASE_URL`	PostgreSQL URL when the driver is postgres
`TLD_APPLY_TARGET`	Default target: `auto`, `local`, or `remote`

Global config reference

Manage it with tld config.

Connection and sync

Key	Default	Notes
`server_url`	`https://tldiagram.com`	Cloud/server URL for sync
`api_key`		Secret. Set by `tld login`
`org_id`		Organization/workspace id for remote operations
`apply.target`	`auto`	`auto`, `local`, or `remote`

Database

Key	Default	Notes
`database.driver`	`sqlite`	`sqlite` or `postgres`
`database.url`		Secret. Required when the driver is postgres

Serve

Key	Default	Notes
`serve.host`	`127.0.0.1`	Bind host
`serve.port`	`8060`	Listen port
`serve.data_dir`		Database and log directory
`serve.public_url`		Public root URL for reverse-proxied deployments
`serve.allowed_origins`		Extra comma-separated CORS origins

Validation

Key	Default	Notes
`validation.level`	`2`	Warning strictness: 1 minimal, 2 standard, 3 strict
`validation.allow_low_insight`	`false`	Include low-insight generated warning groups
`validation.include_rules`		Rule codes to include (comma list)
`validation.exclude_rules`		Rule codes to suppress (comma list)

See Linting Rules for the rule codes.

Index tools

Overrides the external indexers tld index and tld git compare resolve on PATH.

Key	Default
`index.tools.scip_go`	`scip-go`
`index.tools.scip_typescript`	`scip-typescript`
`index.tools.scip_python`	`scip-python`
`index.tools.scip_java`	`scip-java`
`index.tools.scip_clang`	`scip-clang`
`index.tools.scip_dotnet`	`scip-dotnet`
`index.tools.scip_dart`	`scip-dart`
`index.tools.scip_php`	`scip-php`
`index.tools.scip_ruby`	`scip-ruby`
`index.tools.rust_analyzer`	`rust-analyzer`
`index.tools.timeout_seconds`	`300`

Map grouping

Controls how tld index --map turns the dependency graph into architectural components.

Key	Default	Notes
`map.grouping.resolution`	`1.0`	Higher values produce more, smaller communities
`map.grouping.min_group_size`	`2`	Merge groups smaller than this into a sibling
`map.grouping.min_root_groups`	`3`	Minimum root components
`map.grouping.max_root_groups`	`20`	Maximum root components
`map.grouping.max_children`	`8`	Max fan-out of one subdivision
`map.grouping.max_depth`	`4`	Max depth of the group hierarchy
`map.grouping.max_leaf_files`	`40`	Files per leaf view before subdivision
`map.budget.max_connectors_per_view`	`40`	Max rolled-up connectors in one map view
`map.budget.max_leaf_connectors_per_view`	`12`	Max connectors in a file-only map view

System

Key	Default	Notes
`completion.remote`	`false`	Allow shell completion to query remote resources
`updates.auto`	`false`	Auto-install CLI updates during startup checks
`updates.check_interval`	`24h`	Minimum time between update checks

Workspace config reference

project_name: my-project

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

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

Repository modes

Mode	Behavior
`upsert`	Indexing adds new symbols and updates existing ones. Never deletes. Default.
`manual`	No automatic changes from indexing. YAML stays the source of truth.
`auto`	Indexing creates, updates, and deletes based on source. Use with caution.

Exclude patterns

Glob patterns matching files to skip during indexing. The defaults cover most build artifacts; add your own for custom generated directories.

Priority order

When a setting exists in multiple places, higher wins:

CLI flag (e.g. --port 9090)
Environment variable (e.g. PORT=9090)
Global config (~/.config/tldiagram/tld.global.yaml)
Built-in default

Setting up for a team

Commit your .tld/ directory (including .tld.yaml) to version control so element and connector definitions travel with the code. Keep machine-specific state — credentials, local server settings, data directory, indexer paths — in global config.

Quick config inspection

# Where is my global config?
tld config path

# What's currently set?
tld config list

# Show secrets too (be careful)
tld config list --show-secrets

# One specific value
tld config get serve.port

# Change something
tld config set serve.port 9090

# Reset to defaults
tld config reset

# Validate your config
tld config validate