ts site

Show and manage a site — the named location that the launch policy and proxy routing rules point at.

Usage

ts sites
ts site <id>
ts site <id> <property>
ts site new --file=<path>
ts site set <id> <property> <value>
ts site set <id> --file=<path>
ts site delete <id> [--force]

Description

Sites, proxies, and routing rules are the three infrastructure entities behind the served launch policy. A site names a location — an office, a data center, a VPN segment — and optionally anchors it to the proxies that reach it. A routing rule then says "traffic for these sites goes through that proxy". Create the proxy first, then the site that anchors to it, then the rule that ties them together.

A site carries typed fields plus an open extra bag, so you administer it as a JSON document rather than through a flag per field. ts sites lists the three things you need to find one: its entityKey, its display name, and its id. Every other action takes the id — the opaque GUID in the ID column — not the key.

ts site <id> prints the document exactly as the server stores it, and set consumes that same shape, so redirecting to a file, editing, and writing it back is a faithful round trip. new and set read the document from --file; pass - to read standard input instead.

For a single field there is a shorter path. ts site <id> <property> reads one field, and ts site 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. Reach for the accessor for a one-field change, and for --file when you are editing structure or several fields at once.

Property names are kebab-case and map to the document's camelCase key, so display-name addresses displayName. Values are typed from the field being replaced — a numeric field stays numeric, a boolean stays boolean — 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. Use --file for a field like extra that holds an object once it is populated.

A structured field has no accessor form. A property holding an object or an array — a site's anchor, for instance — is refused, and the error points you at --file. An unknown property is refused too. Both refusals happen before anything is written, so a typo cannot half-apply.

The accessor is a read-modify-write: it fetches the document, changes the one field, and sends the whole document back. That is safe here because the document round-trips untyped, so a field this version of ts does not know about is preserved rather than dropped.

The entityKey is what the policy and every routing rule reference, so it is immutable after create. Sending a set whose entityKey differs from the stored one is rejected rather than applied, whether it arrives in a document or through the accessor. An anchor may only be "type": "proxy", and every key in its proxyRefs must already exist — a document naming a proxy that does not is refused, so you cannot leave a dangling reference behind.

ts site delete prompts unless you pass --force, and the server refuses the delete outright while anything still points at the site: an app policy, a launch profile, or a routing rule. The error names the referrers, so it doubles as a way to find out what depends on the site before you retire it. Reading sites works for any signed-in account; creating, changing, and deleting them require a Server Administrator.

Options

Flag	Description	Default/Values	Notes
--file	JSON document to send.	PATH, or - for standard input	Required by new. set needs it only for the whole-document form.
--force, -f	Delete without confirming.		delete only.

Output

print writes the document and nothing else, so it pipes cleanly:

{
  "id": "9d1f3c72-5a4b-4e0e-9c11-7f8a2d6b4e30",
  "entityKey": "hq",
  "displayName": "Headquarters",
  "anchor": { "type": "proxy", "proxyRefs": ["hq-socks"] },
  "extra": null
}

Under --format=json the document is wrapped in the standard result envelope as result.entity, which is not what set consumes. Use the default text output for round trips.

A single-field read prints the bare value — Headquarters, not "Headquarters" — 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.displayName.

Examples

# What sites exist, and what are their ids?
ts sites

# One site as stored
ts site 9d1f3c72-5a4b-4e0e-9c11-7f8a2d6b4e30

# Just one field
ts site 9d1f3c72-5a4b-4e0e-9c11-7f8a2d6b4e30 display-name

# Change one field — no file, no editor
ts site set 9d1f3c72-5a4b-4e0e-9c11-7f8a2d6b4e30 display-name "Headquarters (HQ)"

# Several fields at once, or a structured one like anchor: the document round trip
ts site 9d1f3c72-5a4b-4e0e-9c11-7f8a2d6b4e30 > site.json
$EDITOR site.json
ts site set 9d1f3c72-5a4b-4e0e-9c11-7f8a2d6b4e30 --file=site.json

# Create one from a here-doc rather than a file
cat <<'JSON' | ts site new --file=-
{ "entityKey": "branch-west", "displayName": "West Branch",
  "anchor": { "type": "proxy", "proxyRefs": ["west-socks"] } }
JSON

# Full keys and names, untruncated, for a spreadsheet
ts sites --csv

# Retire a site
ts site delete 9d1f3c72-5a4b-4e0e-9c11-7f8a2d6b4e30 --force

# Gotcha: delete is silent about ids that were never there. A well-formed GUID
# that matches no site reports success and changes nothing, so confirm the id
# against 'ts sites' rather than trusting the "Deleted site" line.

Exit Codes

0 on success. -1 when the server rejects the document — a duplicate or changed entityKey, an anchor that is not "type": "proxy", a proxyRefs entry that does not exist — and when a delete is blocked because something still references the site; the message lists the referrers. -1 also covers the accessor's own refusals: a property that is not a field of the site, and a property holding an object or array. A single-field read of a property the document does not carry is -6 instead, the same code as an id that does not exist. -4 when no account is signed in. -5 when the account is not a Server Administrator, which affects new, set, and delete but not reads. -6 when the id is not a GUID or no site has it.

Related Commands

• ts proxy — The proxies a site's anchor points at; create these first.
• ts routing-rule — Which sites route through which proxy.
• ts policy — The composed launch policy these entities feed.