tld CRUD Commands

Commands apply immediately to the resolved target. YAML is refreshed only when a workspace is detected or --yaml is used. Run tld context to check the destination.

Targets and dry runs

Target mutations accept:

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 applying it; target reads may still occur.

See login, sync & 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 workspace refs and metadata
tld init
tld add api-gateway
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 \
  --view-label "Payments"

Flag	Description
--kind	Optional kind metadata, e.g. service or database
--description	Short description
--technology	Primary technology (normalized against the catalog)
--url, --logo-url	External and logo URLs
--link	Source file, folder, or anchor, e.g. internal/api.go#Handle
--tags	Comma-separated tags
--position-x, --position-y	Canvas position
--ref	Workspace-only alias (default: slugified name); requires YAML mode
--parent	Parent element ref (default root)
--view-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)
--no-reposition	Keep the newly connected target element’s position
--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/authenticates' 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

Use the exact key from tld list connectors: view/source~target[/label]. Numeric IDs also work.

• root/api-gateway~auth-svc — unlabeled connector in the root view
• root/api-gateway~auth-svc/calls — connector labeled calls

tld rename

tld rename is deprecated. Change a display name in either mode, or a workspace-local ref in YAML mode:

tld update element payment-svc name "Payments"
tld update element payment-svc ref payments

Ref changes update YAML references only; the persisted element ID stays the same.

tld link

Link an element to source or an external URL:

tld link api-gateway cmd/gateway/main.go#main
tld link api-gateway --external https://example.com/api
tld link --next

Use --unlink to clear a link or --dry-run to preview it.

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

# Place an existing element, move it, or remove just its placement
tld view place api-gateway payment-svc
tld view place root payment-svc --from api-gateway
tld view unplace root payment-svc

# 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. Remove or update affected connectors before moving/unplacing endpoints. view delete requires an empty view.

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 with a top-level elements: map and connectors: list. Existing items are matched and updated atomically; omitted resources and placements are preserved. Use tld import --schema for accepted fields. Connector tags require tld update connector.

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