tld login, sync & pull

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:

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.

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

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.

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:

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.