tld apply

tld apply

tld apply takes your local YAML workspace and materializes it to the configured target: the local app database or the cloud server.

The flow

Here’s what happens when you type tld apply:

1. Load and validate reads your YAML files, checks structure and references
2. Build a plan diffs your current workspace against the last sync point
3. Check for conflicts sends a dry-run when the target supports it to check if the target has diverged
4. Show the plan displays what will be created, updated, or deleted
5. Ask for confirmation unless you use --force
6. Apply sends the plan to the configured target
7. Update lock file records the new sync point and version
8. Show results what was created, any drift detected

Flags

# Skip all interactive prompts
tld apply -f

# Verbose, see every resource as it's created
tld apply --verbose

# Let the server generate fresh IDs
tld apply --recreate-ids

# Show detailed network request logging
tld apply --debug

# JSON output
tld apply --format json

# Choose a target explicitly
tld apply --target local
tld apply --target remote

Handling conflicts

If someone changed the target since your last tld pull or if you made changes from the browser, you’ll hit a version conflict. You can resolve it interactively:

Version conflict detected:
  Remote has newer version v47 (2026-05-11T15:30:00Z) via cli

  3 conflicts detected:
    * element "api-gateway" (local 2026-05-11T14:00:00Z, remote 2026-05-11T15:30:00Z)
    * connector "api-gateway:auth-svc:calls" (local ..., remote ...)
    * view "api-gateway" (local ..., remote ...)

  Options:
    [1] Abort and review changes
    [2] Pull & Merge (fetch server state and merge locally)
    [3] Force Apply (overwrite remote changes)

  Choose option [1-3]:

Option 1 , Abort: Review the changes. Figure out what happened. Solve it manually, most cautious, safest.

Option 2 , Pull & Merge: The CLI fetches the latest target state, merges it with your local changes, rebuilds the plan, and tries again. Best for collaborative workflows.

Option 3 , Force Apply: Overwrite whatever’s on the server. Use this when you’re certain your local state is the correct one.

When you use --force, option 2 is attempted automatically. If it can resolve the conflict, it does.

Drift detection

Even without explicit conflicts, the target might have changes your local YAML doesn’t know about. tld apply checks for this when the target supports dry-run:

# Target has changes not in your YAML? You'll be warned:
tld apply
#   The server has changes that are not in your local YAML.
#   Run `tld pull` to merge them first, or use --force-apply to overwrite.
#   Continue anyway? [yes/no]:

The --force-apply flag bypasses this warning. Use it when you need to overwrite server changes.

The lock file

After a successful apply, .tld.lock is updated:

version: v1
version_id: v47
applied_at: "2026-05-11T15:32:00Z"
applied_by: cli
workspace_hash: abc123def456
resources:
  elements: 42
  views: 12
  connectors: 35
metadata: ...

This lock file is the source of truth for sync state. It’s how tld diff, tld sync status, and tld plan know what changed.

Common patterns

Safe preview in CI:

tld plan --format json

Non-interactive, machine-readable, fails hard on errors. Follow with tld apply --force when the plan is acceptable.

Interactive dev flow:

tld plan
# review output...
tld apply
# confirm with 'yes'

Team flow with pull first:

tld pull
tld plan --verbose
tld apply

Force overwrite (I know what I’m doing):

tld apply -f --force-apply

Troubleshooting

“Apply failed: …” with a transaction error: Something on the server couldn’t be applied. The transaction rolls back automatically. Fix the issue locally and try again.

Long list of conflicts: Someone’s been busy in the browser. Run tld pull first, review the merged state, then apply.

“workspace has N validation error(s)”: Your YAML has structural problems. Fix them. tld validate --verbose shows details.

ConnectRPC errors with codes: If you see gRPC status codes (Unauthenticated, PermissionDenied, etc.), it means the server rejected the request. Check your api_key, check your permissions on the cloud version.