Skip to main content
Version: 19.x (unreleased)

Desktop Access CLI Reference

Report an IssueView as Markdown

The following tctl commands are used to manage the Teleport Windows Desktop Service.

  • To check that you can connect to your Teleport cluster, sign in with tsh login, then verify that you can run tctl commands using your current credentials. For example, run the following command, assigning teleport.example.com to the domain name of the Teleport Proxy Service in your cluster and [email protected] to your Teleport username: 
    tsh login --proxy=teleport.example.com --user=[email protected]
    tctl status
    Cluster  teleport.example.com
    Version  19.0.0-dev
    CA pin   sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678
    If you can connect to the cluster and run the tctl status command, you can use your current credentials to run subsequent tctl commands from your workstation. If you host your own Teleport cluster, you can also run tctl commands on the computer that hosts the Teleport Auth Service for full permissions.
    Running tctl on a Teleport beam

    In some environments, for example on a Teleport beam, Teleport authentication must take place through a local identity file. On a Teleport beam, the identity file is available automatically, and tctl reads the file path from the TELEPORT_IDENTITY_FILE environment variable.

    When executing tctl commands with an identity file, you must pass the --auth-server flag to provide the Teleport Auth Service address, which is not included in the identity file. If you provide the Proxy Service address, tctl connects to the Proxy Service, which forwards traffic to and from the Teleport Auth Service.

    On a beam, you must use the Proxy Service address, as the Auth Service is not exposed to the public internet. You can do so by using the TELEPORT_PROXY environment variable:

    tctl status --auth-server=${TELEPORT_PROXY}

Generate a join token for a Windows Desktop Service:

$ tctl tokens add --type=WindowsDesktop

List registered Windows Desktop Services:

$ tctl get windows_desktop_service

List registered Windows desktops:

$ tctl get windows_desktop