---
title: tld config
description: Inspect and manage your global tld configuration from the command line.
editUrl: true
head: []
template: doc
sidebar:
  hidden: false
  attrs: {}
pagefind: true
draft: false
---

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

```bash
tld config
```

## Subcommands

### config path

Where is your global config file?

```bash
tld config path
# /Users/you/.config/tldiagram/tld.yaml
```

### config list

See everything that's currently configured:

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

```bash
tld config list --show-secrets
```

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

### config get

Read one specific value:

```bash
tld config get serve.port
# 8060

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

### config set

Change a value:

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

Check your config for issues:

```bash
tld config validate
# Global config valid.
```

If there are problems, it lists them:

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

All config subcommands support `--format json`:

```bash
tld config list --format json
```

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

See the full [configuration reference](/docs/tld/configuration) 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

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