tctl CLI reference

tctl is a CLI tool that allows a cluster administrator to manage all resources in a cluster, including nodes, users, tokens, certificates, and devices.

tctl can also be used to modify the dynamic configuration of the cluster, such as creating new user roles or connecting to trusted clusters.

Authentication

Before running tctl commands, administrators must authenticate to a Teleport cluster. This section explains how tctl authenticates to the cluster.

tctl global flags

tctl acl get

Gets and displays information about a particular access list.

tctl acl get <id>

tctl acl ls

Lists Access Lists on the cluster.

tctl acl ls

tctl acl users add

Adds a user to an access list.

tctl acl users add <access-list-name> <user> [<expires>] [<reason>]

tctl acl users ls

Lists the users in an access list.

tctl acl users ls <access-list-name>

tctl acl users rm

Removes a user from an access list.

tctl acl users rm <access-list-name> <user>

tctl alerts ack

Temporarily acknowledges a cluster alert, preventing the alert from being displayed to users. Acknowledgements last for 24 hours by default. Users will begin seeing the alert again when the acknowledgement expires.

tctl alerts ack [<flags>] <id>

Arguments

• <id>: the ID of the cluster alert to acknowledge

Flags

Examples

Suppress the cluster alert notifying users that an upgrade is available:

tctl alerts ack --reason="upgrade scheduled" upgrade-suggestion
Successfully acknowledged alert 'upgrade-suggestion'. Alerts with this ID won't be pushed for 24h0m0s.

Clear an existing alert acknowledgement:

tctl alerts ack --clear upgrade-suggestion

tctl alerts ack ls

Lists alert acknowledgements.

tctl alerts ack ls
ID                 Reason                 Expires------------------ ---------------------- --------------------upgrade-suggestion "upgrade is scheduled" Wed Apr 12 16:52 UTC

tctl alerts create

Creates cluster alerts. Cluster alerts can be displayed to Teleport users in the web UI or upon logging via tsh.

tctl alerts create [<flags>] <message>

Arguments

• <message>: The message for the alert to display

Flags

While any labels can be applied to an alert, there are several internal labels that can be used to configure the behavior of alerts:

• teleport.internal/alert-on-login: yes: ensures that the alert is displayed to users upon login
• teleport.internal/alert-permit-all: yes: ensures that the alert is displayed to all users

If no labels are specified, tctl will automatically add both of these labels.

Examples

tctl alerts create \    --severity=low \    --ttl=4h \    "The system is under maintenance, functionality may be limited."

tctl alerts list

Lists cluster alerts. This command can also be invoked as tctl alerts ls.

Flags

Examples

tctl alerts list
ID                                   Severity Expires In Message------------------------------------ -------- ---------- ----------------------------------------------------------------da36b401-5688-426f-95b8-d0dd1ef27785 LOW      57m0s      "The system is under maintenance, functionality may be limited."

tctl auth export

Exports public cluster CA certificates. This is useful for configuring external systems to trust certificates issued by Teleport.

tctl auth export [<flags>]

Flags

Global flags

These flags are available for all commands --debug, --config. Run:

tctl help <subcommand>

or see the Global Flags section.

Examples

Export all keys
tctl auth export
Filter by fingerprint
tctl auth export --fingerprint=SHA256:8xu5kh1CbHCZRrGuitbQd4hM+d9V+I7YA1mUwA/2tAo
Export tls certs only
tctl auth export --type=tls-host

tctl auth rotate

Rotate certificate authorities in the cluster:

tctl auth rotate [<flags>]

Flags

Global flags

These flags are available for all commands --debug, --config . Run tctl help <subcommand> or see the Global Flags section.

Examples

Rotate only user certificates with a grace period of 200 hours:
tctl auth rotate --type=user --grace-period=200h

Rotate only host certificates with a grace period of 8 hours:
tctl auth rotate --type=host --grace-period=8h

tctl auth sign

Create an identity file(s) for a given user:

tctl auth sign -o <filepath> [--user <user> | --host <host>][--format] [<flags>]

Flags

Global flags

These flags are available for all commands --debug, --config. Run tctl help <subcommand> or see the Global Flags section.

Examples

Export identity file to teleport_id.pem
for user `teleport` with a ttl set to 5m
tctl auth sign --format file --ttl=5m --user teleport -o teleport_id.pem
Export identity formatted for openssh to teleport_id.pem
tctl auth sign --format openssh --user teleport -o teleport_id.pem
Export host identity, `--format openssh` must be set with `--host`
Generates grav-01 (private key) and grav-01-cert.pub in the current directory
tctl auth sign --format openssh --host grav-00
Invalid command, only one of --user or --host should be set
tctl auth sign --format openssh --host grav-00 --user teleport -o grav_host
error: --user or --host must be specified
create a certificate with a TTL of 24 hours for the jenkins user
the jenkins.pem file can later be used with `tsh`
tctl auth sign --ttl=24h --user=jenkins --out=jenkins.pem
create a certificate with a TTL of 3 months for the jenkins user
the jenkins.pem file can later be used with `tsh`
tctl auth sign --ttl=2190h --user=jenkins --out=jenkins.pem
create a certificate with a TTL of 1 day for the jenkins user
The kubeconfig file can later be used with `kubectl` or compatible tooling.
tctl auth sign --ttl=24h --user=jenkins --out=kubeconfig --format=kubernetes
Exports an identity from the Auth Server in preparation for remote
tctl execution.
tctl auth sign --user=admin --out=identity.pem

tctl bots add

Create a new Machine ID Bot:

tctl bots add <name> [<flags>]

Arguments

• <name> - name of Machine ID Bot to create.

Flags

Examples

Create a new bot named example that may assume the access role and log in as root:

tctl bots add example --roles=access --logins=root

Global flags

These flags are available for all commands: --debug, --config. Run tctl help <subcommand> or see the Global Flags section.

tctl bots instances add

Onboard a new instance of an existing bot with a one-time use join token:

tctl bots instances add <name> [flags]

Note that a new instance will not be generated immediately; the bot will appear in tctl bots instances list as soon as it joins the cluster and is allocated a UUID.

Arguments

• <name> - the name of the existing bot for which a new join token should be generated

Flags

Examples

This generates a new one-time use join token for the bot named "example", without modifying roles or other configuration:

tctl bots instances add example

Global flags

These flags are available for all commands: --debug, --config. Run tctl help <subcommand> or see the Global Flags section.

tctl bots instances list

List all current instances of a Machine ID bot:

tctl bots instances list [<name>]

Arguments

• [<name>] - an optional bot name. If provided, filters the result to show only instances for the named bot. Otherwise, shows all instances for all bots.

Examples

This shows all known instances for the bot named "example":

tctl bots instance list example

Global flags

These flags are available for all commands: --debug, --config. Run tctl help <subcommand> or see the Global Flags section.

tctl bots instances show

Shows details about a particular instance of a bot, including join metadata and current status:

tctl bots instances show <name>/<uuid>

Arguments

• <name> - the name of the existing bot
• <uuid> - the UUID of the existing bot instance, as shown in tctl bots instance list

Examples

tctl bots instances show example/28e605c9-2fe1-423f-afe1-5122335e1c75

Global flags

These flags are available for all commands: --debug, --config. Run tctl help <subcommand> or see the Global Flags section.

tctl bots ls

Lists all Machine ID Bots:

tctl bots ls [<flags>]

Global flags

These flags are available for all commands: --debug, --config. Run tctl help <subcommand> or see the Global Flags section.

tctl bots rm

Delete a Machine ID Bot:

tctl bots rm <name> [<flags>]

Arguments

• <name> - name of Machine ID Bot to delete.

Global flags

These flags are available for all commands: --debug, --config. Run tctl help <subcommand> or see the Global Flags section.

tctl bots update

Update a Machine ID bot:

tctl bots update <bot> [<flags>]

Arguments

• <name> - The name of the bot to update

Flags

Examples

Replace the bot example roles and add a new allowed Unix login:

tctl bots update example --add-logins=root --set-roles=access

Remove all implicitly allowed Unix logins from a bot named example by passing an empty list:

tctl bots update example --set-logins=,

Note that the bot may still be granted additional logins via roles.

Global flags

These flags are available for all commands: --debug, --config. Run tctl help <subcommand> or see the Global Flags section.

tctl create

Create or update a Teleport resource from a YAML file.

The supported resource types are: user, node, cluster, role, connector, and device. See the Resources Reference for complete docs on how to build these yaml files.

tctl create [<flags>] <filename>

Arguments

• <filename> resource definition file

Flags

Global flags

These flags are available for all commands --debug, --config. Run tctl help <subcommand> or see the Global Flags section.

Examples

Update a user record
tctl create -f joe.yaml
Add a trusted cluster
tctl create cluster.yaml
Update a trusted cluster
tctl create -f cluster.yaml

tctl devices add

Register a device.

tctl devices add --os=OS --asset-tag=SERIAL_NUMBER

Flags

Examples

tctl devices add --os=macos --asset-tag=C00AA0AAAA0A
Device C00AA0AAAA0A/macOS added to the inventory
tctl devices add --os=macos --asset-tag=C00AA0AAAA0A --enroll
Device C00AA0AAAA0A/macOS added to the inventoryRun the command below on device "C00AA0AAAA0A" to enroll it:tsh device enroll --token=AAAAAAAAAAAAAAAAAAAAAAAA-this-is-an-example

tctl devices enroll

Create an enrollment token for a device.

tctl devices enroll [--device-id=ID] [--asset-tag=ASSET_TAG]

Flags

One of --device-id or --asset-tag must be present.

Examples

tctl devices enroll --device-id=d40f2ee4-856d-4aef-b784-c4371e39c036
Run the command below on device "d40f2ee4-856d-4aef-b784-c4371e39c036" to enroll it:tsh device enroll --token=AAAAAAAAAAAAAAAAAAAAAAAA-this-is-an-example
tctl devices enroll --asset-tag=C00AA0AAAA0A
Run the command below on device "C00AA0AAAA0A" to enroll it:tsh device enroll --token=AAAAAAAAAAAAAAAAAAAAAAAA-this-is-an-example

tctl devices ls

List registered devices.

tctl devices ls

Examples

tctl devices ls

Asset Tag    OS    Enroll Status Device ID------------ ----- ------------- ------------------------------------C00AA0AAAA0A macOS enrolled      d40f2ee4-856d-4aef-b784-c4371e39c036

tctl devices rm

Removes a registered device.

A removed device is not considered a trusted device for future device authentication attempts.

tctl devices rm [--device-id=ID] [--asset-tag=ASSET_TAG]

Flags

One of --device-id or --asset-tag must be present.

Examples

tctl devices rm --device-id=d40f2ee4-856d-4aef-b784-c4371e39c036
Device "ac3590ec-87d4-4519-8e9e-2f35af0a9f85" removed
tctl devices rm --asset-tag=C00AA0AAAA0A
Device "C00AA0AAAA0A" removed

tctl edit

Modify a Teleport resource using your preferred text editor.

tctl edit <resource-type/resource-name>

The text editor is selected by checking the following, in order of precedence:

• the TELEPORT_EDITOR environment variable
• the VISUAL environment variable
• the EDITOR environment variable
• defaulting to vi

tctl will fetch the resource from the backend and open it in the selected editor. When the editor process terminates, tctl will push the updates to the Teleport cluster. To abandon the edit, close the editor without saving the file.

Some graphical editors like VS Code launch a background process rather than running in the foreground. This prevents tctl from properly detecting when the editor process terminates. To work around this, check whether your editor supports a "wait" option that waits for files to be closed before terminating. For example, to edit a Teleport resource with VS Code, you can set TELEPORT_EDITOR="code --wait".

Note: Renaming resources with tctl edit is not supported since Teleport resources often refer to other resources by name. To rename a resource, we recommend you:

• fetch the resource with tctl get and redirect the output to a file
• change the name of the resource in the file
• save the new resource with tctl create -f
• update any references to the old resource

Arguments

• <resource-type/resource-name> The resource to edit
  • <resource type> The type of the resource [for example: user,cluster,token]
  • <resource name> The name of the resource

Global flags

These flags are available for all commands --debug, --config . Run tctl help <subcommand> or see the Global Flags section.

Examples

edit the sre role
tctl edit role/sre

edit the alice user with the nano editor
TELEPORT_EDITOR=nano tctl edit user/alice

tctl get

Print a YAML declaration of various Teleport resources:

tctl get [<flags>] <resource-type/resource-name>,...

Arguments

• <resource-type/resource-name> The resource to get
  • <resource type> The type of the resource [for example: user,cluster,token,device]
  • <resource name> The name of the resource

Flags

Global flags

These flags are available for all commands --debug, --config . Run tctl help <subcommand> or see the Global Flags section.

Examples

tctl get users
Dump the user definition into a file:
tctl get user/joe > joe.yaml
Prints the trusted cluster 'east'
tctl get cluster/east
Prints all trusted clusters and all users
tctl get clusters,users
Dump all resources for backup into state.yaml
tctl get all > state.yaml

tctl get users
Dump the user definition into a file:
tctl get user/joe > joe.yaml
Prints the trusted cluster 'east'
tctl get cluster/east
Prints all trusted clusters and all users
tctl get clusters,users

tctl help

Shows help:

tctl help

tctl inventory list

List Teleport instance inventory:

tctl inventory list [<flags>]

Flags

Global flags

These flags are available for all commands --debug, --config . Run tctl help <subcommand> or see the Global Flags section.

Examples

List inventory

tctl inventory ls
Server ID                            Hostname                        Services                   Agent Version Upgrader Upgrader Version------------------------------------ ------------------------------- -------------------------- ------------- -------- ----------------00c3a1f7-5f24-47f9-b866-14401fbb5685 teleport-proxy-77df88c69        Proxy                      17.0.2       none     none065ab336-1ac2-4314-8b16-32fc06a172a7 server1                         Node                       17.0.2       unit     17.0.2a24d4ad4-ead8-4b15-9ea6-357a5350369e teleport-auth-fb68b5df7         Auth,Discovery             17.0.2       none     none

List inventory for a specific service and version

tctl inventory ls --services=node --exact-version=17.0.2
Server ID                            Hostname                        Services                   Agent Version Upgrader Upgrader Version------------------------------------ ------------------------------- -------------------------- ------------- -------- ----------------065ab336-1ac2-4314-8b16-32fc06a172a7 server1                         Node                       17.0.2       unit     17.0.2a24d4ad4-ead8-4b15-9ea6-357a5350369e server2                         Node,App                   17.0.2       unit     17.0.2

Note that newly added Teleport services do not show in the inventory right as the service joins. Those can take around 5 minutes under regular circumstances to show in inventory counts and up to 15 minutes for heavy load.

tctl inventory status

Show inventory status summary:

tctl inventory status [<flags>]

Flags

Global flags

These are available for all commands --debug, --config . Run tctl help <subcommand> or see the Global Flags section.

Examples

tctl inventory status
Versions:  v17.0.2: 16Upgraders:  kube: 6  unit: 6  none: 4Services:  Discovery:      2  Auth:           2  Db:             2  Kube:           2  App:            2  Node:           2  Proxy:          2  WindowsDesktop: 2Total Instances: 16

tctl inventory status --connected
Server ID                            Services               Version Upgrader------------------------------------ ---------------------- ------- --------b48e6e81-63e0-498f-834b-1a8adea09d95 Auth                   17.0.2  none178d9301-2873-4020-895a-014edf067204 Node                   17.0.2  unit

tctl inventory status
Versions:  v16.4.7: 19Upgraders:  kube: 1  unit: 1  none: 16Services:  App:            1  Node:           1  Proxy:          12  Discovery:      2  Auth:           2  Kube:           1Total Instances: 19

Note that newly added Teleport services do not show in the inventory right as the service joins. Those can take around 5 minutes under regular circumstances to show in inventory counts and up to 15 minutes for heavy load.

tctl login_rule test

Test a Login Rule resource without installing it in the cluster.

Arguments

• <traits-file> input traits file in JSON or YAML format. Empty for stdin.

Flags

Global flags

These flags are available for all commands --debug, --config. Run tctl help <subcommand> or see the Global Flags section.

Examples

Test evaluation of the Login Rules from rule1.yaml and rule2.yaml with input traits from traits.json

tctl login_rule test --resource-file rule1.yaml --resource-file rule2.yaml traits.json

Test the Login Rule in rule.yaml along with all Login Rules already present in the cluster

tctl login_rule test --resource-file rule.yaml --load-from-cluster traits.json

Read the input traits from stdin

echo '{"groups": ["example"]}' | tctl login_rule test --resource-file rule.yaml

tctl nodes add

Generate a node invitation token:

tctl nodes add [<flags>]

Flags

Global flags

These flags are available for all commands --debug, --config. Run tctl help <subcommand> or see the Global Flags section.

Examples

Generates a token that can be used by a node to join the cluster, default ttl is 30 minutes
tctl nodes add
Generates a token that can be used to add an SSH node to the cluster.
The node will run both the proxy service and the node (ssh) service.
This token can be used within an hour.
tctl nodes add --roles=node,proxy --ttl=1h

tctl nodes ls

List all active SSH nodes within the cluster:

tctl nodes ls [<flags>]

Flags

Global flags

These flags are available for all commands --debug, --config. Run tctl help <subcommand> or see the Global Flags section.

tctl request approve

Approve a user's request:

tctl request approve [token]

Arguments

• <tokens> - comma-separated list of Teleport tokens.

Examples

tctl request approve request-id-1, request-id-2

tctl request create

Create a pending Access Request.

tctl request create <username>

Arguments

• <username> - Name of target user (required).

Flags

Use the dry-run flag if you want to validate whether Teleport can create an Access Request for the user in the username argument, given the user's static roles.

Global flags

These flags are available for all commands --debug, --config. Run tctl help <subcommand> or see the Global Flags section.

Examples

Create an Access Request for user myuser for the prod role, providing a reason:

tctl request create myuser --roles=prod --reason="Fix an outage"

tctl request deny

Denies a user's request:

tctl request deny [token]

Arguments

• <tokens> - comma-separated list of Teleport tokens.

Examples

tctl request deny request-id-1, request-id-2

tctl request ls

List of open requests:

tctl request ls

Examples

tctl request ls

Token                                Requestor Metadata       Created At (UTC)    Status
------------------------------------ --------- -------------- ------------------- -------
request-id-1                         alice     roles=dictator 07 Nov 19 19:38 UTC PENDING

tctl request rm

Delete a users role request:

tctl request rm [token]

Arguments

• <tokens> - comma-separated list of Teleport tokens.

Examples

tctl request rm request-id-1

tctl rm

Delete a resource:

tctl rm <resource-type/resource-name>

Arguments

• <resource-type/resource-name> Resource to delete
  • <resource type> Type of a resource [for example: saml,oidc,github,user,cluster,tokens,device]
  • <resource name> Resource name to delete

Examples

Delete a SAML connector called "okta":
tctl rm saml/okta

Delete a local user called "admin":
tctl rm users/admin

tctl sso configure github

Configure the GitHub auth connector.

Required params --id and --secret come from registering a GitHub OAuth app, which you can read about in the GitHub documentation.

The flag --teams-to-roles can be provided multiple times to specify which GitHub Teams are assigned which roles. In this example, members of the devs team in the GitHub org octocats will be assigned the access, and editor roles in Teleport.

tctl sso configure github --id=GITHUB_CLIENT_ID --secret=GITHUB_SECRET --teams-to-roles=octocats,devs,access,editor [<other-flags>]

Arguments

This command accepts no arguments.

Flags

Mandatory flags: --id, --secret, --teams-to-roles.

Global flags

These flags are available for all commands: --debug, --config. Run tctl help <subcommand> or see the Global Flags section.

Examples

Generate a GitHub auth connector. Two role mappings are defined:

• members of the admin team in the octocats org will receive access, editor and auditor roles.
• members of the dev team in octocats org will receive the access role.

tctl sso configure gh -r octocats,admin,access,editor,auditor -r octocats,dev,access --secret GH_SECRET --id CLIENT_ID
INFO [CLIENT]    RedirectURL empty, resolving automatically.INFO [CLIENT]    RedirectURL set to "https://teleport.example.com:3080/v1/webapi/github/callback"kind: githubmetadata:  name: githubspec:  client_id: CLIENT_ID  client_secret: GH_SECRET  display: ""  redirect_url: https://teleport.example.com:3080/v1/webapi/github/callback  teams_to_logins:  - logins:    - access    - editor    - auditor    organization: octocats    team: admin  - logins:    - access    organization: octocats    team: devversion: v3

Generate the configuration and immediately test it using tctl sso test command.

tctl sso configure gh ... | tctl sso test

tctl sso configure oidc

Configure an OIDC auth connector, optionally using a preset.

The flag --claims-to-roles can be provided multiple times.

tctl sso configure oidc --id=CLIENT_ID --secret=SECRET --claims-to-roles=... [<other-flags>]

Arguments

This command accepts no arguments.

Flags

Mandatory flags: --id, --secret, --claims-to-roles. Other flags may be required depending on chosen preset.

General flags:

Supported presets:

The above values for --issuer-url are defaults which may need to be updated depending on your IdP configuration.

The following flags are specific to Google Workspace:

Global flags

These flags are available for all commands: --debug, --config. Run tctl help <subcommand> or see the Global Flags section.

Examples

1. Generate an OIDC auth connector configuration called myauth. Two mappings from OIDC claims to roles are defined:
   • members of admin group will receive access, editor and auditor roles.
   • members of developer group will receive access role.

The values for --secret, --id and --issuer-url are provided by the IdP.

tctl sso configure oidc -n myauth -r groups,admin,access,editor,auditor -r group,developer,access \      --secret IDP_SECRET --id CLIENT_ID                                                            \      --issuer-url https://idp.example.com

2. Generate an OIDC auth connector with the Okta preset, enabling the groups scope and mapping the okta-admin group to roles access, editor, auditor. Issuer URL is set to match a custom Okta domain.

tctl sso configure oidc --preset okta --scope groups -r groups,okta-admin,access,editor,auditor \      --secret IDP_SECRET --id CLIENT_ID                                                          \      --issuer-url dev-123456.oktapreview.com

3. Generate an OIDC auth connector with the Google preset. Service account credentials are set to be loaded from /var/lib/teleport/gacc.json with --google-acc-uri.

tctl sso configure oidc --preset google -r groups,mygroup@mydomain.example.com,access \      --secret SECRET --google-id GOOGLE_ID --google-acc-uri /var/lib/teleport/gacc.json \      --google-admin admin@mydomain.example.com

4. Generate the configuration and immediately test it using the tctl sso test command.

tctl sso configure oidc ... | tctl sso test

tctl sso configure saml

Configure the SAML auth connector, optionally using a preset.

The flag --attributes-to-roles/-r can be provided multiple times.

To avoid errors when pasting XML to a YAML file, we encourage the usage of the flag --entity-descriptor/-e.

tctl sso configure saml -e entity_desc.xml -r attr,value,role1 [<other-flags>]

Arguments

This command accepts no arguments.

Flags

Mandatory flags: --name, --attributes-to-roles, --entity-descriptor. These flags may become non-mandatory when other flags are present; see table below for details.

Supported presets:

Global flags

These flags are available for all commands: --debug, --config. Run tctl help <subcommand> or see the Global Flags section.

Examples

1. Generate a SAML auth connector configuration called myauth. Two mappings from SAML attributes to roles are defined:
   • members of admin group will receive access, editor and auditor roles.
   • members of developer group will receive access role. The IdP metadata will be read from entity-desc.xml file.

tctl sso configure saml -n myauth -r group,admin,access,editor,auditor -r group,developer,access -e entity-desc.xml

2. Generate a SAML auth connector configuration using the okta preset. The choice of preset affects the default name and display attribute, and may apply IdP-specific tweaks. Instead of an XML file, a URL was provided to the -e flag, which will be fetched by Teleport during runtime.

tctl sso configure saml -p okta -r group,dev,access -e https://dev-123456.oktapreview.com/app/ex30h8/sso/saml/metadata

3. Generate a configuration and immediately test it using the tctl sso test command:

tctl sso configure saml -p okta -r group,developer,access -e entity-desc.xml | tctl sso test

tctl sso test

Perform an end-to-end test of an SSO authentication flow using the provided auth connector definition.

The command supports all auth connector types: github, oidc and saml. The latter two require Teleport Enterprise.

tctl [<global-flags>] sso test [<auth-connector.yaml>]

The testing consists of running a single end-to-end authentication request using the provided auth connector definition. Once the request is finished, the results will be printed to standard output along with context-specific diagnostic information. The test process is safe from side effects in that:

• it will not change the list of configured auth connectors
• the audit log will clearly state the login attempts as "test" ones
• there will be no certificates issued for the authenticated user

- resources: [github_request]
  verbs: [list,create,read,update,delete]
- resources: [oidc_request]
  verbs: [list,create,read,update,delete]
- resources: [saml_request]
  verbs: [list,create,read,update,delete]

Arguments

• [<filename>] Connector resource definition file. Optional. Empty for stdin.

Flags

This command defines no flags.

Global flags

These flags are available for all commands: --debug, --config. Run tctl help <subcommand> or see the Global Flags section.

Examples

Test the auth connector from connector.yaml:

tctl sso test connector.yaml

The command is designed to be used in conjunction with the tctl sso configure family of commands:

tctl sso configure ... | tctl sso test

The pipeline may also utilize tee to capture the connector generated with tctl sso configure. This will save the connector in connector.yaml:

tctl sso configure ... | tee connector.yaml | tctl sso test

You can test an existing auth connector by combining the command with tctl get:

$ tctl get saml/your-connector-name --with-secrets | tctl sso test

tctl status

Report cluster and Certificate Authority status:

tctl status

Examples

Checks status of cluster.
tctl status
Cluster: example.teleport.shVersion: 17.0.0CA pins: sha256:a5322b9f89cb94fff13da4bc9c7b2e633626e35161a75f7662a179a01be84ccc
authority rotation                                        protocol status algorithm   storage--------- ----------------------------------------------- -------- ------ ----------- --------host      standby (never rotated)                         SSH      active Ed25519     software                                                          TLS      active ECDSA P-256 softwareuser      standby (last rotated: Oct 3 2024 22:12:09 UTC) SSH      active ECDSA P-256 AWS KMS                                                          TLS      active ECDSA P-256 AWS KMSdb        standby (never rotated)                         TLS      active RSA 2048    softwaredb_client standby (never rotated)                         TLS      active RSA 2048    softwareopenssh   standby (never rotated)                         SSH      active Ed25519     softwarejwt       standby (never rotated)                         JWT      active ECDSA P-256 softwaresaml_idp  standby (never rotated)                         TLS      active RSA 2048    softwareoidc_idp  standby (never rotated)                         JWT      active RSA 2048    softwarespiffe    standby (never rotated)                         JWT      active ECDSA P-256 software                                                          TLS      active ECDSA P-256 softwareokta      standby (never rotated)                         JWT      active ECDSA P-256 software
tctl status \    --auth-server=192.168.99.102:3025 \    --identity=identity.pem

tctl tokens add

Create an invitation token:

tctl tokens add --type=TYPE [<flags>]

Flags

Global flags

These flags are available for all commands --debug, --config . Run tctl help <subcommand> or see the Global Flags section.

Examples

Generate an invite token for a trusted_cluster
tctl tokens add --type=trusted_cluster --ttl=5m
Generate an invite token for a trusted_cluster with labels
tctl tokens add --type=trusted_cluster --labels=env=prod,region=us-west
Generate an invite token for a node
This is equivalent to `tctl nodes add`
tctl tokens add --type=node
Generate a join token for both a Node and the Database Service
tctl tokens add --type=node,db
Generate an invite token for a kubernetes_service
tctl tokens add --type=kube
Generate an invite token for an app_service
tctl tokens add --type=app

tctl tokens ls

List node and user invitation tokens:

tctl tokens ls [<flags>]

Flags

Global flags

These flags are available for all commands --debug, --config . Run tctl help <subcommand> or see the Global Flags section.

Example

tctl tokens ls

Token                            Type            Expiry Time (UTC)
-------------------------------- --------------- -------------------
abcd123-insecure-do-not-use-this Node            11 Oct 19 22:17 UTC
efgh456-insecure-do-not-use-this trusted_cluster 11 Oct 19 22:19 UTC
ijkl789-insecure-do-not-use-this User signup     11 Oct 19 22:20 UTC

tctl tokens rm

Delete/revoke an invitation token:

tctl tokens rm [<token>]

Arguments

• <token> The full-length token string to delete

tctl top

Reports diagnostic information.

The diagnostic metrics endpoint must be enabled with teleport start --diag-addr=<bind-addr> for tctl top to work.

tctl top [<diag-addr>] [<refresh>]

Argument

• [<diag-addr>] Diagnostic HTTP URL (HTTPS not supported)
• [<refresh>] Refresh period e.g. 5s, 2m, or 3h

Example

sudo teleport start --diag-addr=127.0.0.1:3000
View stats with a refresh period of 5 seconds
tctl top http://127.0.0.1:3000 5s

tctl users add

Generates a user invitation token:

tctl users add [<flags>] <account>

Arguments

• <account> - The Teleport user account name.

Flags

Global flags

These flags are available for all commands --debug, --config. Run tctl help <subcommand> or see the Global Flags section.

Examples

Adds Teleport user "joe" with the "access" and "requester" roles and
permissions to assume the "joe" and "ubuntu" logins
tctl users add joe --roles=access,requester --logins=joe,ubuntu

tctl users ls

Lists all user accounts:

tctl users ls [<flags>]

tctl users reset

Reset local user account password and any associated second factor with expiring link to populate values. Usage: tctl users reset <account>

Arguments

• <account> - Teleport Local DB User

Flags

Examples

tctl users reset jeff
User jeff has been reset. Share this URL with the user to complete password reset, the link is valid for 8h0m0s:
https://teleport.example.com:3080/web/reset/8a4a40bec3a31a28db44fa64c0c70ca3
Resets jeff's password and any associated second factor.  Jeff populates the password and confirms the token with the link.

tctl users rm

Deletes user accounts:

tctl users rm <logins>

Arguments

• <logins> - comma-separated list of Teleport users

Examples

tctl users rm sally,tim
Removes users sally and tim

tctl users update

Update user account:

tctl users update [<flags>] <account>

Arguments

• <account> - The Teleport user account name.

Flags

Examples

Set the user joe's roles to access and editor:

tctl users update joe --set-roles=access,editor

Set the user priya's Azure identities to developer and dba:

tctl users update priya --set-azure-identities \ `/subscriptions/${SUBSCRIPTION_ID?}/resourceGroups/${MY_RESOURCE_GROUP?}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/developer,\ `/subscriptions/${SUBSCRIPTION_ID?}/resourceGroups/${MY_RESOURCE_GROUP?}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/dba

tctl version

Print the version of your tctl binary:

tctl version