---
title: tld apply
description: Materialize your local workspace to the configured target. Apply
  handles conflicts, drift, and version tracking.
editUrl: true
head: []
template: doc
sidebar:
  hidden: false
  attrs: {}
pagefind: true
draft: false
---

```bash
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

```bash
# 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:

```bash
# 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:

```yaml
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**:
```bash
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**:
```bash
tld plan
# review output...
tld apply
# confirm with 'yes'
```

**Team flow with pull first**:
```bash
tld pull
tld plan --verbose
tld apply
```

**Force overwrite (I know what I'm doing)**:
```bash
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.