ctl: Bulk List Commands

First time using ctl? See the "Getting ctl talking to your appliance" section in ctl: Bulk Import Commands for one-time setup (pointing ctl at your appliance and logging in). This article assumes that's already done.

At a glance

Every one of these prints a readable table by default. Add --fmt json to any of them to get structured JSON output instead — useful if you want to feed the result into a script, filter it with a tool like jq, or search through it for something specific.

Important: which of these work through XCM, and which don't

If you manage a fleet through an XCM (Central Manager), read this before you start:

• Connections, users, and groups all work whether ctl is pointed at a CSG directly or at an XCM overseeing many CSGs. When pointed at an XCM, ctl conn list shows every connection across every CSG the XCM manages, with an extra column telling you which CSG each one belongs to.
• Relays and X-Connections have no XCM view at all. If ctl is configured against an XCM, ctl relay list and ctl x-connect list won't even show up as available commands. To list relays or X-Connections, point ctl at that specific CSG directly:

  ctl config set addr https://your-csg.example.com 

  then run ctl relay list / ctl x-connect list against that CSG.

Listing connections

ctl conn list 

Default output is a table with columns for ID, name, and protocol. If you're pointed at an XCM, an extra column shows which CSG each connection belongs to.

For structured output (every property of every connection, not just the table columns):

ctl conn list --fmt json 

Example of what one entry looks like:

{
    "name": "Finance Server",
    "protocol": "rdp",
    "disabled": false,
    "approvalLifetimeMin": 120,
    "properties": {
        "hostname": "10.10.2.4",
        "port": "3389",
        "username": "jsmith",
        "enable-clipboard": "true"
    }
}

Listing users

ctl users list 

Columns: ID, username, disabled status, full name, email, organization. When run against a CSG directly (not an XCM), there's an extra Source column showing whether that user record originates at the XCM (Manager) level or was created locally on this CSG (Gateway) - relevant if this CSG is part of an XCM-managed fleet.

To include deleted users in the list:

ctl users list --deleted 

For structured output:

ctl users list --fmt json

or

ctl users list --fmt csv

Listing groups

ctl groups list 

Columns: ID, name, SSO name, AD name. When run against a CSG directly (not an XCM), there's an extra SOURCE column with the same Manager-vs-Gateway meaning described under Listing users above.

For structured output:

ctl groups list --fmt json 

Listing relays (CSG only)

ctl relay list 

Only works when ctl is pointed directly at a CSG — see the callout above if you're managing a fleet through an XCM.

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

For structured output:

ctl relay list --fmt json 

Listing X-Connections (CSG only)

ctl x-connect list 

Columns displayed: ID, name

Same CSG-only rule as relays above.

For structured output:

ctl x-connect list --fmt json

Tips

• Adding --fmt json works the same way across every command above — it's not specific to any one object type. ctl users list is the one exception that also accepts --fmt csv; every other command here only supports json.
• If you have a tool like jq available, piping the JSON output through it is a quick way to pull out just the field you need, e.g. ctl users list --fmt json | jq '.[].email' to get a plain list of every user's email address.
• The default table view is meant for reading in a terminal. If you're piping the output into another program or script, use --fmt json instead of trying to parse the table.