ts channel

Show and change one channel — the named grouping a workspace uses to sort its apps and links into tabs.

Usage

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

Description

ts channels 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 channel's slug, its display name, when it was created, and its ID — the ID is what every ts channel action takes.

Channels are read and written as JSON documents rather than through a flag per field, for the same reason sites and apps are: the document is the whole record, and a round-trip through it cannot silently drop something this version of ts does not know about. ts channel <id> prints what the server holds, verbatim, and ts channel set <id> --file= sends it back. A channel document is small — name and slug are the parts you edit — but it travels the same path as the larger ones, so the same habits work everywhere.

set replaces both fields, and both are required: a document without a name or a slug is rejected. new reads three fields — workspaceId, which is the workspace's GUID, plus name and slug — so write it by hand rather than editing a printed channel. A printed channel's workspaceId is the server's internal numeric id, not the GUID new expects, and sending it back is rejected. Slugs are unique across the whole server, not just within one workspace, so a slug already taken elsewhere fails with a conflict.

For a single field there is a shorter path. ts channel <id> <property> reads one field, and ts channel 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. On a record this small the accessor covers most of what you will do — renaming a channel is a single set — and --file stays the right tool when you are changing the name and the slug together, or working from an edited file.

Property names are kebab-case and map to the document's camelCase key. Values are typed from the field being replaced, so a numeric field stays numeric and a boolean stays boolean and 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.

The accessor is a read-modify-write: it fetches the document, changes the one field, and sends the whole document back. That keeps the set-replaces-both-fields rule from biting you — the field you did not name is sent back as it was — and it is safe because the document round-trips untyped, so a field this version of ts does not know about is preserved rather than dropped.

What a channel contains is not managed here. ts channel covers the channel itself; adding an app or a link to a channel, or taking one out, stays in the Administration site.

delete is a soft delete: the channel stops appearing but the row is retained, and ts has no undo for it. Apps and links that were in the channel are not deleted with it. Deleting 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

# How is this workspace organized?
ts channels acme

# One channel in full
ts channel 5c1d0b88-2a6f-4b7d-91a4-4f21c8e08e33

# Just one field
ts channel 5c1d0b88-2a6f-4b7d-91a4-4f21c8e08e33 slug

# Rename without opening an editor — the slug is sent back unchanged
ts channel set 5c1d0b88-2a6f-4b7d-91a4-4f21c8e08e33 name "Engineering Tools"

# Changing the name and the slug together: the document round trip
ts channel 5c1d0b88-2a6f-4b7d-91a4-4f21c8e08e33 > channel.json
$EDITOR channel.json
ts channel set 5c1d0b88-2a6f-4b7d-91a4-4f21c8e08e33 --file=channel.json

# Create one — hand-written, not a printed document
echo '{"workspaceId":"9b336df2-2599-490b-99bc-e17f2bf50f66","name":"Design","slug":"design"}' \
  | ts channel new --file=-

# Full slugs and IDs, nothing truncated
ts channels acme --csv

# Retire a channel, unattended
ts channel delete 5c1d0b88-2a6f-4b7d-91a4-4f21c8e08e33 --force

Changing a slug changes the URL segment users have bookmarked, and nothing redirects the old one. Rename the display name when you only want the label to read differently.

Output

print emits the server's JSON document unchanged, so it pipes into jq and back into set. 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 — design, not "design" — 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.slug.

Exit Codes

0 on success. -2 when ts channels is run without a workspace. -6 when the workspace or the channel 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 the slug is already in use, 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 channel belongs to.
• ts app — The apps a channel groups.
• ts link — The link shortcuts a channel groups.