tld plan

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

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

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

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:

tld apply