Version: 19.x (unreleased)

Desktop Access CLI Reference

Is this page helpful?

This page lists the tctl commands that you can use to manage the Teleport Windows Desktop Service.

Check that you can connect to your Teleport cluster and verify that you can run tctl and tsh commands using your current credentials.
1. Assign teleport.example.com to the domain name of the Teleport Proxy Service in your cluster and [email protected] to your Teleport username.
2. Authenticate to your Teleport cluster. This depends on whether your shell is interactive or not.
  
  In an interactive shell: Run the following command. By default, this triggers a multi-factor authentication prompt:
```
tsh login --proxy=teleport.example.com --user=[email protected]
tctl status
Cluster  teleport.example.com
Version  19.0.0-dev
CA pin   sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678
```
  On non-interactive environments: If you are running tsh and tctl as an AI agent, in a CI/CD environment, or similar, make sure the TELEPORT_IDENTITY_FILE environment variable is assigned to a valid file path with credentials for your cluster. tsh and tctl read the file path from the environment variable and do not require a separate authentication step. If there is no identity file available, we recommend that you set up Machine ID to provision one automatically.
  
  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. Update 443 to 3025 if you are contacting the Auth Service directly with tctl:
```
tctl status --auth-server=teleport.example.com:443
```
  For tsh commands that read an identity file, you must pass the --proxy flag, which points tsh to the address of the Teleport Proxy Service:
```
tsh status --proxy=teleport.example.com
```
  Ensure client commands can access your identity file. Replace path/to/identity/file with the path to your identity file:
```
export TELEPORT_IDENTITY_FILE="${TELEPORT_IDENTITY_FILE:-path/to/identity/file}"
```
  Add the --auth-server or --proxy flags to all subsequent tctl and tsh commands.
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.

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

Was this page helpful?