---
title: tld login & pull
description: Connect the CLI to tlDiagram and pull server state into your workspace YAML.
editUrl: true
head: []
template: doc
sidebar:
  hidden: false
  attrs: {}
pagefind: true
draft: false
---

tlDiagram keeps three things in sync: your local YAML files, the local app database, and the cloud server. This page covers authentication and pulling state down.

## Where commands write

Every mutating command — `add`, `connect`, `update`, `remove`, `view`, `import` — applies to a **target** and then write-through updates your YAML cache. The target is resolved in this order:

| Target | Behavior |
|---|---|
| `auto` | Remote when `api_key` and `org_id` are set, otherwise local. Default. |
| `local` | The local app database, no cloud. |
| `remote` (alias `cloud`) | The tlDiagram cloud server. |

Override per command with `--target`, or set a default in global config:

```bash
tld config set apply.target local
```

Because commands apply immediately, there is no separate plan/apply step. Preview with `--dry-run`, and refresh YAML after browser edits with `tld pull`.

## tld login

`tld login` authenticates the CLI with a tlDiagram server using a device-code flow and writes the resulting key to your global config.

```bash
tld login
```

It prints a verification URL and a short code. Open the URL (or the browser opens automatically), enter the code, and the CLI polls until you approve. On success it writes `server_url`, `api_key`, and `org_id` to `tld.global.yaml`.

```bash
# Print the URL instead of opening a browser
tld login --no-browser
```

## tld pull

`tld pull` downloads the current state from the target and refreshes your local YAML files. Use it after making changes in the web editor.

```bash
tld pull
```

By default it does a **surgical merge**: updates existing resources and adds new ones without blindly overwriting local edits. If it detects uncommitted local changes it warns first:

```
Local workspace has uncommitted changes. Pull will overwrite them.
  Continue? [yes/no]:
```

### Flags

| Flag | What it does |
|---|---|
| `--force` | Overwrite local changes without prompting |
| `--dry-run` | Show what would be pulled without writing |
| `--target local` | Pull from the local app database |
| `--target remote` | Pull from the cloud server |
| `--data-dir` | Data directory for local target state |

Remote pulls require a configured API key and an `org_id` in global config — both are written by `tld login`.

```bash
tld pull --dry-run
# Would pull: 42 elements, 12 diagrams, 35 connectors

tld pull
# Pulled 42 elements, 12 diagrams, 35 connectors
```

## The sync point

After a successful pull, `.tld.lock` records the new sync point: the version, a hash of the workspace, resource counts, and per-resource metadata. It's how tld knows what changed since the last sync. Don't edit it by hand.

## Working with a team

Commit your `.tld/` directory so element and connector definitions travel with the code. Keep machine-specific state — credentials, local server settings, data directory — in global config, which stays on your machine.