---
title: tld plan
description: Preview what tld apply will do. See conflicts, drift, and
  architectural warnings before pushing.
editUrl: true
head: []
template: doc
sidebar:
  hidden: false
  attrs: {}
pagefind: true
draft: false
---

Always plan before you apply. It's the tlDiagram equivalent of `terraform plan`.

```bash
tld plan
```

## What it shows

`tld plan` builds a plan from your local YAML workspace, then sends a dry-run request to the server. The server responds with what would change, plus any conflicts or drift it detects.

The output has three sections:

**Resource summary**: How many elements, diagrams, and connectors will be created or updated.

**Conflicts and drift**: If someone changed diagrams in the browser (or another team member pushed via CLI) since your last sync, `tld plan` tells you. Conflicts are version mismatches. Drift is when the server has things your YAML doesn't know about.

**Architectural warnings**: Quality checks based on [linting rules](/docs/tld/linting-rules). Isolated nodes, high density, missing labels , the plan catches them all.

```
Plan                 12 elements, 5 diagrams, 8 connectors (25 total resources)

  Resources to create:
    • db              /api gateway          (element) backend-pkg
    • db              /user-db              (element) backend-pkg
    ...

  Connectors to create:
    • api-gateway:user-db:queries users     (connector)
    • api-gateway:auth-svc:calls            (connector)
    ...

  Conflicts: 0

  ## Architectural Warnings (Level 2: Standard)

  [isolated-object] Isolated Object (1 violations)
  Consider removing or connecting these standalone objects.
    * cache-redis has no connectors in its view
```

## Flags

```bash
# Verbose , show every resource detail
tld plan --verbose

# Write plan to a file
tld plan --output plan.md

# Override validation strictness
tld plan --strictness 3

# Let the server generate fresh IDs for everything
tld plan --recreate-ids

# JSON output , machine-readable
tld plan --format json
```

## JSON output

When piped into scripts or CI, use `--format json`:

```bash
tld plan --format json | jq .
```

The JSON includes every resource, its action (create/update/delete), and all warnings. Consistent schema you can rely on.

## How it works under the hood

1. Loads your workspace YAML files
2. Validates them (structure, references, types)
3. Builds a plan , diffing your current state against the last sync point
4. Sends a dry-run to the server (`ApplyPlanRequest` with `dry_run = true`)
5. The server responds with what *would* happen, plus conflicts/drift
6. The CLI analyzes the plan for architectural issues
7. Renders everything as readable output

Nothing is committed. The server doesn't save anything. It's a preview, pure and simple.

## Plan vs validate

- `tld validate` checks your YAML for structural correctness. 
- `tld plan` does that *plus* checks against the server for conflicts, plus analyzes architectural quality

So: `validate` is local. `plan` is cloud-aware. Both are read-only.

## Next step

If `tld plan` looks good, no conflicts, warnings are acceptable, it's time to apply:

```bash
tld apply
```