---
title: tld pull & export
description: Pull target state into local YAML, or export an entire
  organization's cloud diagrams as code.
editUrl: true
head: []
template: doc
sidebar:
  hidden: false
  attrs: {}
pagefind: true
draft: false
---

Two commands that move data down to your local machine. They're related but different.

## tld pull

`tld pull` fetches the current state from the configured target and writes it into your local YAML files. By default, the target is resolved automatically; use `--target local` or `--target remote` when you need to be explicit.

```bash
tld pull
```

### When to use it

- Someone made changes in the browser and you want those changes locally
- You're setting up on a new machine and want to clone your existing diagrams
- You need to resolve conflicts before applying your own changes
- You just want a backup of everything in YAML

### What it does

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

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

By default, `tld pull` performs a **surgical merge**. It updates existing resources and adds new ones , but it won't blindly overwrite local changes you haven't pushed yet. If it detects uncommitted local changes, it warns and asks:

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

### Flags

```bash
# Skip the warning, overwrite everything
tld pull --force

# Preview what would happen without modifying files
tld pull --dry-run

# Pull from the local app database
tld pull --target local

# Pull from the cloud server
tld pull --target remote
```

### How merging works

Pull doesn't just dump server state over your local files. It does a **three-way merge**:

1. It knows your **last sync point** (from `.tld.lock`)
2. It knows the **current target state** (from the local database or the API)
3. It knows your **current local state** (from YAML files)

Resources you've modified locally since the last sync are preserved if the target hasn't touched them. Resources the target has modified are updated. New resources on either side are added. Deletions propagate.

If there's a genuine conflict (both you and the target modified the same thing), the target version wins. But the lock file records the conflict so `tld sync status` and `tld diff` can show you what happened.

## tld export

`tld export` is similar but more thorough. It exports **every diagram, element, and connector** from an organization into your workspace.

```bash
tld export [org-id]
```

If you don't pass an org ID, it uses the one in your `.tld.yaml`.

### When to use it

- Migrating from the cloud version to a code-centric workflow
- Creating a complete local backup of an organization
- Sharing your architecture with someone who uses the CLI
- Moving diagrams between organizations

### What it does

Unlike `pull` (which uses your lock file for smart merging), `export` does a full wholesale replacement:

1. Fetches all diagrams, elements, and connectors from the server
2. Writes them into your local YAML files
3. Updates the lock file to reflect the new state

```bash
tld export
# Exported 156 elements, 34 diagrams, 89 connectors to .tld/
```

## Comparison

| | tld pull | tld export |
|---|---|---|
| **Merge strategy** | Surgical three-way merge | Full replacement |
| **Uses lock file** | Yes, for conflict detection | Only updates it after |
| **Preserves local changes** | Tries to | Overwrites everything |
| **Primary use case** | Day-to-day sync | Initial setup, migration, backups |
| **Format** | Writes to current workspace | Writes to current workspace |
| **Dry run** | `--dry-run` | Not available |

If you're working day-to-day, use `tld pull`. If you're setting up fresh or migrating, use `tld export`.

## The full sync lifecycle

```
Your machine                    Cloud version
    │                                │
    ├──── tld apply ────────────────►│  (push local changes)
    │                                │
    │◄──── tld pull ─────────────────┤  (fetch cloud changes)
    │                                │
    │◄──── tld export ───────────────┤  (full download)
    │                                │
    ├──── tld diff ─────────────────►│  (compare local vs cloud)
    ├──── tld sync status ──────────►│  (check sync health)
```

All of these are read/write-ordered. Nothing happens to the server without `tld apply`. Nothing changes locally without `tld pull` or `tld export`. You're always in control.

## CI and automation

For automated workflows, use `--force` to skip interactive prompts:

```bash
# In your CI pipeline
tld pull --force
tld plan
tld apply --force
```