---
title: tld CRUD Commands
description: Programmatic element and connector management. Add, connect,
  remove, rename, and update directly from the terminal.
editUrl: true
head: []
template: doc
sidebar:
  hidden: false
  attrs: {}
pagefind: true
draft: false
---

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.

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

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

## tld connect

Create a connector (edge) between two elements.

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

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

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

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

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