tld CRUD Commands

These were designed for agentic workflows in mind. Brief, token efficient, predictable commands that can return instant feedback to the agent. Show informative warnings about potential issues, and guide it towards a well-structured architecture.

If you are using these with scripting to manage your diagrams programmatically, please let us know!

tld add

Create or update an element.

# Minimal
tld add my-service

# With details
tld add payment-svc \
  --ref payment-svc \
  --kind service \
  --description "Handles payment processing" \
  --technology Go \
  --parent api-gateway \
  --position-x 100 \
  --position-y 200 \
  --diagram-label "Payments"

Flags

Flag	Description
--ref	Override the generated ref (defaults to a slugified name)
--kind	Element kind: service, database, queue, person, system, container, component
--description	Short description string
--technology	Technology stack label
--url	External URL (repository link, docs, etc.)
--parent	Parent element ref (default: root)
--position-x	Horizontal canvas position
--position-y	Vertical canvas position
--diagram-label	Optional label for the element’s canonical diagram

If an element with the same ref already exists, tld add updates it. It’s an upsert , safe to run multiple times, safe to script.

# Add with JSON output
tld add cache-redis --kind database --technology Redis --format json

tld connect

Create a connector (edge) between two elements.

# Basic
tld connect --from api-gateway --to auth-svc

# With details
tld connect \
  --from api-gateway \
  --to payment-svc \
  --label "processes payments" \
  --description "Sends payment requests via gRPC" \
  --relationship "calls" \
  --direction forward

# Bidirectional
tld connect --from auth-svc --to user-db --direction both --label "reads/writes"

Flags

Flag	Description
--from	Source element ref (required)
--to	Target element ref (required)
--label	Edge label text
--description	Longer description
--relationship	Semantic type (e.g. “calls”, “publishes”, “queries”)
--direction	forward, backward, both, or none
--url	External URL

The view is inferred automatically based on the elements’ placements. If both elements share a parent, the connector goes in that parent’s view. Otherwise, it goes in the root view.

tld remove

Delete elements or connectors.

# Remove an element by ref
tld remove element payment-svc

# Remove a connector
tld remove connector --view root --from api-gateway --to auth-svc

Removing an element also cleans up all connectors that reference it. Removals are local , they don’t affect the cloud version until you tld apply.

tld rename

Rename an element. All references in connectors and other elements are updated automatically.

tld rename --from old-ref --to new-ref

This is a safe refactor. Every connector that referenced old-ref now references new-ref. Every placement is preserved. It’s a one-liner.

tld update

Change a specific field on an element or connector.

# Update element field
tld update element api-gateway description "Routes external requests to internal services"

# Update connector field
tld update connector root:api-gateway:auth-svc:calls label "validates JWT"

Connector ref format

Connectors use a compound key: view:source:target[:label]

• root:api-gateway:auth-svc , connector in root view between those two elements
• root:api-gateway:auth-svc:calls , with a label to disambiguate

JSON output

All CRUD commands support --format json:

tld add my-service --format json
# {"command":"add","status":"ok","action":"add","ref":"my-service"}

tld connect --from api-gateway --to auth-svc --format json
# {"command":"connect","status":"ok","action":"connect","ref":"api-gateway:auth-svc"}