---
title: tld login, sync & pull
description: Connect the CLI, push workspace YAML, and pull current target state.
editUrl: true
head: []
template: doc
sidebar:
  hidden: false
  attrs: {}
pagefind: true
draft: false
---

CLI commands use one target at a time: the local database or cloud server. YAML workspaces are optional; `sync` pushes YAML to the target and `pull` refreshes it from the target.

## Where commands write

Resource mutations apply to a **target** and refresh the YAML cache when present. Select the target as follows:

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

Ordinary mutations apply immediately. Preview with `--dry-run`; use `tld context` to check the destination.

## 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` refreshes YAML from the target after browser edits. Run `tld init` first, or specify an export directory with `--workspace`.

```bash
tld pull
```

Pull can overwrite local YAML edits. If it detects changes since the last sync, it prompts 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
```

## tld sync

Apply hand-edited workspace YAML to the target in one transaction:

```bash
tld sync --dry-run
tld sync --target local
# Or: tld sync --target remote
```

Existing resources are matched and updated. Sync YAML edits before running another mutation that refreshes the cache.

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