ts link

Show and change one workspace link — a shortcut to an external URL that appears in a workspace beside its apps.

Usage

ts links <workspace>
ts link <id>
ts link <id> <property>
ts link new --file=<path>
ts link set <id> <property> <value>
ts link set <id> --file=<path>
ts link delete <id> [--force]

Description

ts links needs a workspace; there is no default. Give it the workspace ID (the short name in URLs, such as acme) or its GUID. The listing shows each link's name, its URL, whether it opens in a new tab, and its ID — the ID is what every ts link action takes.

Links are read and written as JSON documents rather than through a flag per field, the same way apps and channels are. The record carries more than a name and a URL — the new-tab behavior and an optional uploaded icon travel with it — and reading and writing the whole document means a round-trip cannot quietly discard a field this version of ts does not know about. ts link <id> prints what the server holds, verbatim, and ts link set <id> --file= sends it back.

set is a full replace of the link's editable fields. name and url are both required; omitting openInNewTab clears it rather than leaving it alone. Edit the printed document instead of composing a fresh one and that stays true by construction. The icon is the exception in the other direction: a printed link includes its icon inline as base64 in iconData, but set ignores it. Uploading or removing a link icon stays in the Administration site.

For a single field there is a shorter path. ts link <id> <property> reads one field, and ts link set <id> <property> <value> writes one. The two write forms are complementary rather than alternatives: the accessor changes one field and leaves the rest of the document as it was, while --file replaces the whole document. Repointing a link that moved is one set; reach for --file when you are editing several fields at once or working from a file you already have.

The accessor is the safe way to make a one-field change here, because it is a read-modify-write: it fetches the document, changes the one field, and sends the whole document back. openInNewTab therefore goes back as it was, instead of being cleared the way a hand-written minimal document clears it. The round trip is also untyped, so a field this version of ts does not know about is preserved rather than dropped.

Property names are kebab-case and map to the document's camelCase key, so open-in-new-tab addresses openInNewTab. Values are typed from the field being replaced — that boolean stays a boolean, a numeric field stays numeric — so you never have to know a field's wire type. A field that is currently null is the exception: there is nothing to infer a type from, so the value goes in as a string.

A structured field has no accessor form. A property holding an object or an array is refused with a pointer at --file, and so is a property the document does not carry. Both refusals happen before anything is written, so a typo cannot half-apply. iconData is a string rather than a structure, so the CLI accepts it and the server then ignores it — the icon is not settable by either form.

new reads four fields — workspaceId, which is the workspace's GUID, plus name, url, and optionally openInNewTab — so write it by hand. A printed link's workspaceId is the server's internal numeric id, not the GUID new expects, and sending a printed document back to new is rejected.

delete is a soft delete: the link stops appearing but the row is retained, and ts has no undo for it. It prompts first unless you pass --force, and where there is no terminal --force is required rather than assumed.

Options

Flag	Description	Default/Values	Notes
--file	JSON document to send.	Path, or - to read stdin	Required by new. set needs it only for the whole-document form.
--force, -f	Delete without confirming.		Required when there is no terminal.

Examples

# What shortcuts does this workspace publish?
ts links acme

# One link in full
ts link 7d2e4a10-5b93-4c61-8f07-1e9a3c4d5b62

# Just one field
ts link 7d2e4a10-5b93-4c61-8f07-1e9a3c4d5b62 url

# Repoint a link that moved, keeping everything else — openInNewTab survives
ts link set 7d2e4a10-5b93-4c61-8f07-1e9a3c4d5b62 url https://wiki.example.net/design

# Stop it opening in a new tab — typed from the field, so this writes false
ts link set 7d2e4a10-5b93-4c61-8f07-1e9a3c4d5b62 open-in-new-tab false

# Name and URL together: the document round trip
ts link 7d2e4a10-5b93-4c61-8f07-1e9a3c4d5b62 > link.json
$EDITOR link.json
ts link set 7d2e4a10-5b93-4c61-8f07-1e9a3c4d5b62 --file=link.json

# Create one — hand-written, not a printed document
echo '{"workspaceId":"9b336df2-2599-490b-99bc-e17f2bf50f66","name":"Design Wiki","url":"https://wiki.example.net","openInNewTab":true}' \
  | ts link new --file=-

# Full URLs and IDs, nothing truncated
ts links acme --csv

# Remove a stale shortcut, unattended
ts link delete 7d2e4a10-5b93-4c61-8f07-1e9a3c4d5b62 --force

Writing a minimal {"name":..., "url":...} document to set looks harmless and is not: the link comes back with its new-tab behavior cleared. Send back what print gave you, or change the one field with the accessor, which does that for you.

Output

print emits the server's JSON document unchanged, so it pipes into jq and back into set. A link with an uploaded icon carries it as base64, which makes the document large — pipe through jq 'del(.iconData)' when you only want to read it, or read the one field you care about with ts link <id> <property>. Under --format=json the document is nested as entity inside the standard result envelope, which is not the shape set --file consumes — keep the default text output for round trips.

A single-field read prints the bare value — https://wiki.example.net, not "https://wiki.example.net" — so it drops straight into a shell variable. Under --format=json that value comes back in the envelope under the document's own key, result.url.

Exit Codes

0 on success. -2 when ts links is run without a workspace. -6 when the workspace or the link ID does not exist, and when a single-field read names a property the document does not carry. -5 when the account is not a Server Administrator. -1 when the document is missing or unreadable, when name or url is absent, when you decline the delete prompt, and for the accessor's write-side refusals — an unknown property, or one holding an object or array.

Related Commands

• ts workspace — The workspace a link belongs to.
• ts app — The apps a link sits beside.
• ts channel — The channels that group links and apps.