tld CRUD Commands

These commands are designed for agentic and scripted workflows: brief, token-efficient, predictable. They apply immediately to the resolved target and write through to your YAML cache.

Targets and dry runs

Every mutating command accepts:

Flag	What it does
--target auto|local|remote|cloud	Where the change applies. auto picks remote when api_key and org_id are set, otherwise local.
--data-dir	Data directory for local target state.
--dry-run	Preview the change without writing files or calling the server.

See login & pull for how targets resolve.

tld add

Create or update an element. Upsert semantics: running it twice is safe.

# 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 \
  --tags payments,critical \
  --diagram-label "Payments"

Flag	Description
--kind	Element kind (default service)
--description	Short description
--technology	Primary technology (normalized against the catalog)
--url, --logo-url	External and logo URLs
--owner	Owning repository key (must be registered in .tld.yaml)
--symbol	Named code symbol to link
--tags	Comma-separated tags
--density-level	Canvas density level [-2..2]
--bypass-noise-gate	Exempt from the view noise gate (default true)
--position-x, --position-y	Canvas position
--ref	Override the generated ref (default: slugified name)
--parent	Parent element ref (default root)
--diagram-label	Label for the diagram created when this element becomes a parent
--dry-run, --target, --data-dir	See above

tld connect

Create a connector between two elements.

tld connect --from api-gateway --to auth-svc --label "authenticates"

tld connect \
  --from api-gateway \
  --to payment-svc \
  --label "processes payments" \
  --relationship calls \
  --direction forward \
  --tags payments

Flag	Description
--from	Source element ref (required)
--to	Target element ref (required)
--label	Edge label
--description	Longer description
--relationship	Semantic type (e.g. calls, publishes, queries)
--direction	forward, backward, both, or none (default forward)
--url	External URL
--tags	Comma-separated tags
--view	Explicit connector view (default: source element’s view)
--dry-run, --target, --data-dir	See above

tld remove

# Remove an element
tld remove element payment-svc

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

Removing an element cleans up all connectors that reference it and its owned view. Removal runs against the target (--target, --dry-run, --data-dir supported).

tld update

Change a specific field.

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

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

# Tags: append or remove instead of replacing
tld update element payment-svc tags critical --append
tld update element payment-svc tags legacy --remove

--append and --remove are only valid with the tags field. Updating ref also moves the element’s metadata.

Connector ref format

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

• root:api-gateway:auth-svc — connector in the root view
• root:api-gateway:auth-svc:calls — disambiguated with a label

tld rename

Rename an element. Every connector and placement that referenced the old ref is updated automatically.

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

tld view

Views are the drill-down diagrams owned by elements. An element has a view when has_view is true.

# Create (or ensure) the view owned by an element
tld view create api-gateway --name "API Gateway" --label Container

# Rename it
tld view rename api-gateway "Gateway"

# Set its level label
tld view set-level api-gateway Container

# Delete it (the element is kept; the view must be empty)
tld view delete api-gateway

The owning element must already exist — create it first with tld add. view delete requires the view to be empty: remove or reparent its elements and delete its connectors first.

tld import

Bulk add or update elements and connectors from a file, atomically.

tld import diagrams.yaml
cat diagrams.yaml | tld import -

The file is YAML or JSON shaped like workspace files, with a top-level elements: map and connectors: list. Existing items are matched and updated, so re-running is safe. Any failure commits nothing.

Flag	What it does
--dry-run	Validate and report changes without applying
--target, --data-dir	See above

JSON output

All commands support --format json (and --compact):

tld add my-service --format json
# {"command":"add","status":"ok","items":[{"ref":"my-service","action":"add","resource_type":"element"}]}

tld import diagrams.yaml --format json
# {"command":"import","status":"ok","summary":{"elements_created":3,"connectors_created":2}}