ts channel

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

Usage

ts channels <workspace> [--csv] [--no-trunc]
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]
ts channel permissions <id>
ts channel grant <id> <user-or-group> [--group]
ts channel revoke <id> <user-or-group> [--group]

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. An administrator of the workspace or the server sees every channel; anyone else sees the channels granted to them or to a group they are in.

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. Slugs are unique across the whole server, not just within one workspace, so a slug already taken elsewhere fails with a conflict, and a printed channel sent to new unchanged fails on its own slug.

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 and who sees it; 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.

Who Sees a Channel

permissions prints the accounts and groups granted the channel as the server's JSON list; userType is 0 for an account and 1 for a group. grant gives an account, or with --group a group, permission to see the channel, and revoke takes it away. Name an account by its login name or ID and a group by its name or ID; where two identity sources hold a group's name, put the source's login prefix and a backslash before it (CORP\Sales). A deleted account or group keeps its permissions until they are revoked, so name it by the userGuid that permissions prints. A grantee that already holds a permission on the channel is refused, and so is a grant in a personal workspace. Grants and revocations are recorded in the audit trail.

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.
--group	The user-or-group is a group.		grant and revoke only. Without it the name is an account.
--csv	Tab-separated output, nothing truncated.		ts channels only.
--no-trunc	Do not truncate columns.		ts channels only.

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

# Who sees it, and let the Engineering group see it too
ts channel permissions 5c1d0b88-2a6f-4b7d-91a4-4f21c8e08e33
ts channel grant 5c1d0b88-2a6f-4b7d-91a4-4f21c8e08e33 Engineering --group

# Take it away from one account
ts channel revoke 5c1d0b88-2a6f-4b7d-91a4-4f21c8e08e33 alice

# 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, when set is given both a property and --file, and when the accessor names a field holding an object or array. -6 when the workspace, the channel ID, or the --file path does not exist, when the channel is not one you see, when a single-field read or write names a property the document does not carry, and when revoke names a grantee with no permission on the channel. -5 when the account does not administer the workspace. -1 when the document lacks a name or slug, when the slug is already in use, when the grantee already holds a permission, when a field written through the accessor does not read back, and when you decline the delete prompt.

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.
• ts group — The groups a channel is granted to.