ctl: Bulk List Commands

Reading many objects at once instead of clicking through the web UI one at a time. The companion to ctl: Bulk Import Commands, which covers creating them.

Naming: this article uses the v5.5.4 product names - Gateway (formerly CSG) and Manager (formerly XCM). Appliances on older versions, and their documentation, use the old names for the same things.

ℹ First time using ctl?

This article assumes ctl already points at your appliance and is logged in. If not, work through ctl: Getting Started first - the first API key has to be created in the web UI before ctl can log in at all.

At a glance

To list...	Command	Works via Manager?
Connections	`ctl conn list`	Yes
Users	`ctl users list`	Yes
Groups	`ctl groups list`	Yes
Relays	`ctl relay list`	Gateway only
X-Connections	`ctl x-connect list`	Gateway only

Every one of these prints a readable table by default. Add --fmt json to any of them for structured output instead - useful for scripting, filtering with jq, or searching for something specific.

Read this first if you manage a fleet through a Manager

OK - Connections, users, groups

Work whether ctl points at a Gateway or at a Manager. Against a Manager, ctl conn list shows every connection across every managed Gateway, with an extra column naming the owning Gateway.

NO - Relays and X-Connections

No Manager view at all. Pointed at a Manager, these commands do not even appear as available - so a “command not found” here is expected behaviour, not a broken install.

To list relays or X-Connections, point ctl at that specific Gateway first:

Re-point ctl at one Gateway - ctl
`ctl config set addr https://your-csg.example.com`

Listing connections

Table output - ctl
`ctl conn list`

Columns: ID, name, protocol. Against a Manager, an extra column shows which Gateway each connection belongs to.

Every property, not just the table columns - ctl
`ctl conn list --fmt json`

One entry looks like this - json
`{ "name": "Finance Server", "protocol": "rdp", "disabled": false, "approvalLifetimeMin": 120, "properties": { "hostname": "10.10.2.4", "port": "3389", "username": "jsmith", "enable-clipboard": "true" } }`

Listing users

Table output - ctl
`ctl users list`

Columns: ID, username, disabled status, full name, email, organization.

ℹ The Source column means record origin, not auth type

Run against a Gateway directly, there is an extra Source column showing whether the record originates at the Manager (Manager) level or was created locally on this Gateway. It is easy to misread this as telling you how the user authenticates - it does not. It only tells you where the record came from, which matters when the Gateway is part of a Manager-managed fleet.

Include deleted users - ctl
`ctl users list --deleted`

Structured output - and the one command that also does CSV - ctl
`ctl users list --fmt json ctl users list --fmt csv # spreadsheet-ready; users only`

Listing groups

Table output - ctl
`ctl groups list`

Columns: ID, name, SSO name, AD name. Run against a Gateway directly there is an extra SOURCE column, with the same Manager-vs-Gateway meaning described under users above.

Structured output - ctl
`ctl groups list --fmt json`

Listing relays Gateway only

Table output - ctl
`ctl relay list`

Columns: ID, name, host, source port, destination port, max duration, protocol, allow-list IPs.

Structured output - ctl
`ctl relay list --fmt json`

Listing X-Connections Gateway only

Table output - ctl
`ctl x-connect list`

Columns: ID, name.

Structured output - ctl
`ctl x-connect list --fmt json`

Tips

✓ Pull out a single field with jq

Every user's email address, one per line - ctl + jq

ctl users list --fmt json | jq '.[].email'

--fmt json behaves identically across every command here - it is not specific to one object type.
ctl users list is the only command that also accepts --fmt csv. Everything else supports json only.
The default table view is for reading in a terminal. If you are piping into another program, use --fmt json rather than trying to parse the table.