tld pull & export

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.

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

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

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

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

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:

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