Skip to content
tlDiagram

tld config

View Markdown

tld config is the management interface for your global tld configuration file. Read values, change settings, validate your config , all from the terminal.

Terminal window
tld config

Subcommands

Section titled “Subcommands”

config path

Section titled “config path”

Where is your global config file?

/Users/you/.config/tldiagram/tld.yaml
tld config path

config list

Section titled “config list”

See everything that’s currently configured:

Terminal window
tld config list
KEY                     VALUE                     SOURCE  ENV         DESCRIPTION
server_url              https://tldiagram.com     file    TLD_SERVER_URL  tlDiagram server URL
api_key                 ********                  file    TLD_API_KEY     API key for authentication
org_id                  org_abc123                file    TLD_ORG_ID      Default organization ID
serve.host              127.0.0.1                 default TLD_ADDR       Host for local server
serve.port              8060                      file    PORT            Port for local server
watch.languages         go,typescript,python      default                 Languages to watch
watch.watcher           auto                      default                 Watcher backend
...

Each row shows the effective value, where it came from (config file, environment variable, or built-in default), and whether it’s a secret.

To see secret values unmasked:

Terminal window
tld config list --show-secrets

Be careful with that. It’ll show your API key in plain text.

config get

Section titled “config get”

Read one specific value:

Terminal window
tld config get serve.port
# 8060


tld config get server_url
# https://tldiagram.com

config set

Section titled “config set”

Change a value:

Terminal window
tld config set serve.port 9090
# Set serve.port


tld config set watch.languages go,python,rust
# Set watch.languages

The change is written to your global config file immediately. No restart needed , the next tld command picks it up.

config validate

Section titled “config validate”

Check your config for issues:

Terminal window
tld config validate
# Global config valid.

If there are problems, it lists them:

Terminal window
tld config validate
# ⚠ 2 config issues:
#   - watch.embedding.provider: "openi" is not a recognized provider
#   - serve.port: "abc" is not a valid port number

JSON output

Section titled “JSON output”

All config subcommands support --format json:

Terminal window
tld config list --format json
[
  {
    "key": "server_url",
    "value": "https://tldiagram.com",
    "source": "file",
    "env": "TLD_SERVER_URL",
    "description": "tlDiagram server URL",
    "secret": false
  },
  ...
]

What config keys are available?

Section titled “What config keys are available?”

See the full configuration reference for every available key, what it does, and its defaults.

Quick categories:

  • server_url, api_key, org_id , cloud version connection
  • serve.host, serve.port , local server settings
  • serve.data_dir , where SQLite and logs live
  • watch.* , language scanning, thresholds, embeddings, visibility

When to use this vs editing the file directly

Section titled “When to use this vs editing the file directly”

tld config is convenient and validates input. It’s the recommended way to change settings.

But for bulk edits or when you’re setting up a new machine from a template, editing ~/.config/tldiagram/tld.yaml directly is fine too. Just make sure the YAML is valid , run tld config validate after.