tld login & pull

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:

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.

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.

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

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.

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.