title	description
tctl CLI reference	Comprehensive reference of subcommands, flags, and arguments for the tctl CLI tool.

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.

On a remote host with an identity file

tctl can authenticate with a user-provided identity file. The Teleport Auth Service signs an identity file when a user runs tctl auth sign or tsh login --out=<output-path>, and the user can include the path to the identity file in the --identity flag when running tctl commands.

When using the --identity flag, the user must provide the --auth-server flag with the address of an Auth Service or Proxy Service so tctl knows which cluster to authenticate to.

On the same host as the Teleport Auth Service

If there is a Teleport configuration file on the host where tctl is run, tctl attempts to authenticate to the Auth Service named in the configuration file using an identity stored in its local backend.

tctl authenticates using this method if a configuration file exists at /etc/teleport.yaml or TELEPORT_CONFIG_FILE points to a configuration file in another location. If the auth_service is disabled in the configuration file, then the configuration file is ignored.

Note that when a tctl command is run locally on the Auth Service, the audit logs will show that it was performed by the Auth Service itself.

To provide an accurate audit trail, it is important to limit direct SSH access to the Auth Service with Access Controls and ensure that admins use tctl remotely instead.

On a remote host after running `tsh login`

If tctl cannot find a local Teleport configuration file or a user-provided identity file, it attempts to load the user's tsh profile to authenticate to the cluster. The tsh profile is created when a user runs tsh login.

tctl reads the TELEPORT_CONFIG_FILE environment variable to determine if a Teleport configuration file is present. If you are using your tsh profile to authenticate tctl, you must ensure that one of these conditions is true:

On a remote host with an identity file

tctl can authenticate with a user-provided identity file. The Teleport Auth Service signs an identity file when a user runs tctl auth sign or tsh login --out=<output-path>, and the user can include the path to the identity file in the --identity flag when running tctl commands.

When using the --identity flag, the user must alo provide the --auth-server flag with the address of an Auth Service or Proxy Service so tctl knows which cluster to authenticate to.

On a remote host after running `tsh login`

If tctl cannot find a local Teleport configuration file or a user-provided identity file, it attempts to load the user's tsh profile to authenticate to the cluster. The tsh profile is created when a user runs tsh login.

tctl reads the TELEPORT_CONFIG_FILE environment variable to determine if a Teleport configuration file is present. If you are using your tsh profile to authenticate tctl, you must ensure that one of these conditions is true:

TELEPORT_CONFIG_FILE is blank
No file exists at /etc/teleport.yaml

Otherwise tctl will attempt to connect to a Teleport cluster on the machine, which could result in the error, ERROR: open /var/lib/teleport/host_uuid: permission denied.

tctl global flags

Name	Default Value(s)	Allowed Value(s)	Description
`-d, --debug`	none	none	Enable verbose logging to stderr
`-c, --config`	`/etc/teleport.yaml`	string filepath	Path to a configuration file
`--auth-server`	none	`host:port`	Attempts to connect to specific Auth/Proxy Service address(es) instead of a local Auth Service (`127.0.0.1:3025`)
`-i, --identity`	none	string filepath	Path to an identity file
`--insecure`	none	none	When specifying a Proxy Service address in `--auth-server`, do not verify its TLS certificate. Danger: any data you send can be intercepted or modified by an attacker

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 notifications create

Create a new notification for users in the cluster:

$ tctl notifications create [<flags>]

There are several ways to specify which users see the notification. To target a specific user, use the --user flag. To target all users with a particular role (or set of roles), use the --roles flag. If you specify multiple roles, all users with at least one of the roles will see the notification, in order to require users to have all of the roles specified, add the --require-all-roles flag. If neither --user nor --roles are provided, the notification will default to targeting all users in the cluster, regardless of their roles.

Flags

Name	Default Value(s)	Allowed Value(s)	Description
`-t, --title`	none	string	Required. Sets the notification's title
`--content`	none	string	Required. Sets the notification's text content, this is the text that will be displayed when a user clicks on the notification.
`--user`	none	string	If user-specific, the username of the specific user this notification will target.
`--roles`	none	Comma-separated strings	If role-specific, the set of roles users must have to receive this notification.
`--require-all-roles`	`false`	`true`,`false`	If role-specific, setting this to `true` will only targets users who have all of the roles specified in `--roles`. If `false`, users only need to have one or more of the roles.
`--ttl`	`30d`	Any duration	Time duration after which the notification will expire and be deleted.
`--warning`	`false`	`true`,`false`	Whether this notification should be displayed as a warning.
`--labels`	none	Comma-separated strings	Custom labels to attach to the notification's metadata. Note that these will have no effect on the native behavior of the notification.

Examples

# Create a notification for a specific user
$ tctl notifications create --user=alice --title="Upcoming Database Maintenance" --content="We will be conducting a database upgrade tomorrow at 2AM UTC"

# Create a warning notification for all users
$ tctl notifications create --warning --title="Enroll an MFA device" --content="We will soon be enforcing MFA in this cluster, please enroll a device to avoid being locked out of your account."

# Create a notification for users with the `engineer` role that expires in 2 days
$ tctl notifications create --roles=engineer --title="Reminder" --content="Please use access requests to request access to production servers" --ttl=2d

tctl notifications ls

List notifications:

$ tctl notifications ls [<flags>]

Flags

Name	Default Value(s)	Allowed Value(s)	Description
`--user`	none	string	List only a specific user's notifications.
`--format`	`text`	`text`,`yaml`,`json`	The format of the output.
`--all`	`false`	`true`,`false`	If `true`, notifications generated by Teleport will also be returned, as opposed to only notifications created by admins via the `tctl` interface.
`--labels`	none	Comma-separated strings	Filter notifications by labels.

Examples

$ tctl notifications ls
ID                                   Created             Expires             Title                Labels
------------------------------------ ------------------- ------------------- -------------------- ------
0194d8b2-5a38-7858-88fe-5fcee3ff1ceb 06 Feb 25 00:39 UTC 08 Mar 25 00:39 UTC Example notification

tctl notifications rm

Delete a notification:

$ tctl notifications rm [<flags>] <id>

Arguments

<id>: the ID of the notification to delete. This can be retrieved from the output of tctl notifications ls.

Flags

Name	Default Value(s)	Allowed Value(s)	Description
`--user`	none	string	The username of the user this notification belongs to, if the notification is user-specific.

Examples

# Delete a notification which was either for all users, or role-based.
$ tctl notifications rm 3b8eb3d6-da9a-5353-aece-cbc885ecbf73

# Delete a notification which was specific to a user.
$ tctl notifications rm --user=alice 4f548918-c853-52a6-b98b-5718b79d0e96

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

Name	Default Value(s)	Allowed Value(s)	Description
`--ttl`	24h	Any duration	Time duration to acknowledge the alert for
`--clear`	none		Clear an existing alert acknowledgement
`--reason`	none		The reason for suppressing this alert

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

Name	Default Value(s)	Allowed Value(s)	Description
`--severity`	`low`	`low`, `medium`, `high`	Alert severity
`--ttl`	none	Any duration	Optional expiry for alert (alert does not expire if no TTL is specified)
`--labels`	none	any	A list of labels to attach to the alert.

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

Name	Default Value(s)	Allowed Value(s)	Description
`--verbose` (`-v`)	false	boolean	If set, display detailed alert info (including acknowledged alerts)
`--labels`	none	Comma-separated strings	A list of labels to filter by

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

Name	Default Value(s)	Allowed Value(s)	Description
`--keys`	none	none	if set, only exports private keys
`--fingerprint`	none	string e.g. `SHA256:<fingerprint>`	filter authority by fingerprint
`--compat`	none	version number	export certificates compatible with specific version of Teleport
`--type`	none	`user`, `host`, `tls-host`, `tls-user`, `tls-user-der`, `windows`, `db`, `openssh`, `saml-idp`	certificate type
`--out`	none	filepath	if set writes exported authorities to files with the given path prefix

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

Name	Default Value(s)	Allowed Value(s)	Description
`--grace-period`	none	relative duration like 5s, 2m, or 3h	Grace period keeps previous certificate authorities signatures valid, if set to 0 will force users to log in again and nodes to re-register.
`--manual`	none	none	Activate manual rotation, set rotation phases manually
`--type`	`user,host`	`user` or `host`	Certificate authority to rotate
`--phase`		`init, standby, update_clients, update_servers, rollback`	Target rotation phase to set, used in manual rotation

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

`tctl auth sign` is commonly used to generate long-lived certificates for automation purposes. On supported platforms, [Machine ID](../../enroll-resources/machine-id/introduction.mdx) is a more secure alternative that generates short-lived certificates for automation workflows.

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

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

Flags

Name	Default Value(s)	Allowed Value(s)	Description
`--user`	none	existing user	Teleport user name
`--host`	none	auth host	Teleport host name
`-o, --out`	none	filepath	identity output
`--overwrite`	none	none	When specified, write new identity files, even if they already exist
`--format`	`file`	`file`, `openssh`, `tls` or `kubernetes`	identity format
`--identity`	none	`file`	Identity file to use for logging in to the Auth Service
`--auth-server`	none	auth host & port	Remote Teleport host name
`--ttl`	`12h`	relative duration like `5s`, `2m`, or `3h`	TTL (time to live) for the generated certificate
`--compat`	`""`	`standard` or `oldssh`	OpenSSH compatibility flag
`--proxy`	`""`	Address of the Teleport Proxy Service	When --format is set to `kubernetes`, this address will be set as the cluster address in the generated kubeconfig file
`--leaf-cluster`	`""`	The name of a leaf cluster.
`--kube-cluster-name`	`""`	Kubernetes Cluster Name
`--app-name`	`""`	application name	Generate a certificate for accessing the specified web application
`--db-service`	`""`	Database Service name	Generate a certificate for accessing the specified Database Service instance
`--db-user`	`""`	database user	When `--db-service` is specified, encode this database user in the certificate
`--db-name`	`""`	database name	When `--db-service` is specified, encode this database name in the certificate

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 Service 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

Name	Default Value(s)	Allowed Value(s)	Description
`--roles`	none	Comma-separated list of roles to assign to the Bot.	Required. Specifies the roles that the Bot should be able to impersonate and include in generated credentials.
`--logins`	none	Comma-separated list of allowed SSH logins to set Bot's login trait to.	Optional. Specifies the values that should be configured as the Bot's logins trait for the purpose of role templating.
`--token`	none	String name of an existing join token.	Optional. Specifies an existing join token to be used rather than creating one as part of the Bot creation.
`--ttl`	15m	Duration.	Optional. Overrides the TTL of the token that will be created if `--token` is not specified.
`--format`	`text`	`text`, `json`	If set to `json`, return new bot information as a machine-readable JSON string.

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

Name	Default Value(s)	Allowed Value(s)	Description
`--token`	none	String name of an existing join token.	Optional. Specifies an existing join token to be used rather than creating one as part of the Bot creation.
`--format`	`text`	`text`, `json`	If set to `json`, return new bot information as a machine-readable JSON string.

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

Name	Default Value(s)	Allowed Value(s)	Description
`--add-roles`	none	Comma-separated list of roles the bot may assume	Appends the given roles to the existing roles the bot may assume.
`--set-roles`	none	Comma-separated list of roles the bot may assume	Replaces the bots's current roles with the list provided.
`--add-logins`	none	Comma-separated list of allowed Unix logins	Appends the given logins to the bot's current allowed logins.
`--set-logins`	none	Comma-separated list of allowed Unix logins	Replaces the bot's current allowed logins with the given list.

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

Name	Default Value(s)	Allowed Value(s)	Description
`-f, --force`	none	none	Overwrite the resource if already exists

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

Name	Default Value(s)	Allowed Value(s)	Description
`--os`	none	`linux`, `macos`, `windows`	Device operating system
`--asset-tag`	none	string	Device inventory identifier (e.g., Mac serial number)
`--enroll`	false	boolean	If set, creates a device enrollment token

Examples

$ tctl devices add --os=macos --asset-tag=(=devicetrust.asset_tag=)
Device (=devicetrust.asset_tag=)/macOS added to the inventory

$ tctl devices add --os=macos --asset-tag=(=devicetrust.asset_tag=) --enroll
Device (=devicetrust.asset_tag=)/macOS added to the inventory
Run the command below on device "(=devicetrust.asset_tag=)" to enroll it:
tsh device enroll --token=(=devicetrust.enroll_token=)

tctl devices enroll

Create an enrollment token for a device.

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

Flags

Name	Default Value(s)	Allowed Value(s)	Description
`--device-id`	none	string	Teleport device identifier
`--asset-tag`	none	string	Device inventory identifier (e.g., Mac serial number)

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=(=devicetrust.enroll_token=)

$ tctl devices enroll --asset-tag=(=devicetrust.asset_tag=)
Run the command below on device "(=devicetrust.asset_tag=)" to enroll it:
tsh device enroll --token=(=devicetrust.enroll_token=)

tctl devices ls

List registered devices.

$ tctl devices ls

Examples

$ tctl devices ls

Asset Tag    OS    Enroll Status Device ID
------------ ----- ------------- ------------------------------------
(=devicetrust.asset_tag=) 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

Name	Default Value(s)	Allowed Value(s)	Description
`--device-id`	none	string	Teleport device identifier
`--asset-tag`	none	string	Device inventory identifier (e.g., Mac serial number)

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=(=devicetrust.asset_tag=)
Device "(=devicetrust.asset_tag=)" 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

Name	Default Value(s)	Allowed Value(s)	Description
`--format`		`yaml, json` or `text`	Output format
`--with-secrets`	none	none	Include secrets in resources like certificate authorities or OIDC connectors

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

Name	Default Value(s)	Allowed Value(s)	Description
`--format`	`text`	`yaml, json` or `text`	Output format
`--older-than`	none	string	Filter for older teleport versions
`--exact-version`	none	string	Filter output by teleport version
`--services`	none	string	Filter output by service (node,kube,proxy,etc)
`--upgrader`	none	`none`, `kube`, or `unit`	Filter output by upgrader (kube,unit,none)

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                      (=teleport.version=)       none     none
065ab336-1ac2-4314-8b16-32fc06a172a7 server1                         Node                       (=teleport.version=)       unit     (=teleport.version=)
a24d4ad4-ead8-4b15-9ea6-357a5350369e teleport-auth-fb68b5df7         Auth,Discovery             (=teleport.version=)       none     none

List inventory for a specific service and version

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

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

Name	Default Value(s)	Allowed Value(s)	Description
`--format`	`text`	`yaml, json` or `text`	Output format
`--[no-]connected`	`--no-connected`	none	Show locally connected instances summary

Global flags

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

Examples

List inventory status

$ tctl inventory status
Versions:
  v(=teleport.version=): 16
Upgraders:
  kube: 6
  unit: 6
  none: 4
Services:
  Discovery:      2
  Auth:           2
  Db:             2
  Kube:           2
  App:            2
  Node:           2
  Proxy:          2
  WindowsDesktop: 2
Total Instances: 16

List inventory status for locally connected instances summary. This allows seeing connected instances on a specific Auth service.

$ tctl inventory status --connected
Server ID                            Services               Version Upgrader
------------------------------------ ---------------------- ------- --------
b48e6e81-63e0-498f-834b-1a8adea09d95 Auth                   (=teleport.version=)  none
178d9301-2873-4020-895a-014edf067204 Node                   (=teleport.version=)  unit

List inventory status

$ tctl inventory status
Versions:
  v(=cloud.version=): 19
Upgraders:
  kube: 1
  unit: 1
  none: 16
Services:
  App:            1
  Node:           1
  Proxy:          12
  Discovery:      2
  Auth:           2
  Kube:           1
Total 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

Name	Default Value(s)	Allowed Value(s)	Description
`--resource-file`	none	string filepath	Path to Login Rule resource path, can be repeated for multiple files
`--load-from-cluster`	`false`	`true, false`	When true, all Login Rules currently installed in the cluster will be loaded for the test. Can be combined with `--resource-file` to test interactions.
`--format`	`yaml`	`yaml, json`	Output format for traits

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

Name	Default Value(s)	Allowed Value(s)	Description
`--roles`	`node`	`proxy, auth, node, db, app` or `windowsdesktop`	Comma-separated list of roles for the new node to assume
`--ttl`	30m	relative duration like 5s, 2m, or 3h	Time to live for a generated token
`--token`	none	string token value	A custom token to use, auto-generated if not provided. Should match token set with `teleport start --token`

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

Name	Default Value(s)	Allowed Value(s)	Description
`--namespace`	none	string namespace	Namespace of the nodes

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

Name	Default Value(s)	Allowed Value(s)	Description
`roles`	none	Comma-separated list of strings	Roles to be requested
`resource`	none	Comma-separated list of strings	Resource IDs to be requested
`reason`	none	String	Optional reason message
`dry-run`	none	Boolean	Don't actually generate the Access Request

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.

Name	Default Value(s)	Allowed Value(s)	Description
`-n`, `--name`	`github`	resource name	Connector name.
`-r`, `--teams-to-roles`	none	`org,team,role1,role2,...`	Sets teams-to-roles mapping. Repeatable.
`--display`	none	display name	Controls how this connector is displayed.
`--id`	none	GitHub OAuth2 client id	GitHub app client ID.
`--secret`	none	GitHub OAuth2 secret	GitHub app client secret.
`--redirect-url`	none	Valid callback URL.	Authorization callback URL.
`--ignore-missing-roles`			Ignore missing roles referenced in `--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` is an alias for `tctl sso configure github`.

$ 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: github
metadata:
  name: github
spec:
  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: dev
version: 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:

Name	Description
`-p`, `--preset`	Preset. One of: `google`, `gitlab`, `okta`.
`-n`, `--name`	Connector name. Required, unless implied from preset.
`-r`, `--claims-to-roles`	Sets claim-to-roles mapping using format `claim_name,claim_value,role1,role2,...`. Repeatable.
`--display`	Display controls how this connector is displayed.
`--id`	OIDC app client ID.
`--secret`	OIDC app client secret.
`--issuer-url`	Issuer URL.
`--redirect-url`	Authorization callback URL.
`--prompt`	Optional OIDC prompt. Example values: `none`, `select_account`, `login`, `consent`.
`--scope`	Scope specifies additional scopes set by provider. Each repetition of the flag declares one scope. Examples: `email`, `groups`, `openid`.
`--acr`	Authentication Context Class Reference values.
`--provider`	Sets the external identity provider type to enable IdP specific workarounds. Examples: `ping`, `adfs`, `netiq`, `okta``.
`--ignore-missing-roles`	Ignore missing roles referenced in `--claims-to-roles`.

Supported presets:

Name	Description	Display	Issuer URL
`google`	Google Workspace	Google	`https://accounts.google.com`
`gitlab`	GitLab	GitLab	`https://gitlab.com`
`okta`	Okta	Okta	`https://oktaice.okta.com`

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:

Name	Description
`--google-acc-uri`	URI of your service account credentials file. Example: `file:///var/lib/teleport/gworkspace-creds.json`.
`--google-acc`	String containing Google service account credentials.
`--google-admin`	Email of a Google admin to impersonate.
`--google-legacy`	Flag to select groups with direct membership filtered by domain (legacy behavior). Disabled by default. More info
`--google-id`	Shorthand for setting the `--id` flag to `<GOOGLE_WORKSPACE_CLIENT_ID>.apps.googleusercontent.com`

Global flags

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

Examples

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

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

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

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.

Name	Required?	Description
`-p/--preset`		Preset. One of: `okta`, `onelogin`, `ad`, `adfs`.
`-n/--name`	Yes, unless `--preset` is given.	Connector name.
`-e/--entity-descriptor`	Yes, unless `--sso`, `--acs`, `--cert` and `--issuer` are also given.	Set the Entity Descriptor. Valid values: file path, URL, XML content. Supplies configuration parameters as a single XML document instead of individual elements.
`-r/--attributes-to-roles`	Yes, at least one occurrence must be present.	Sets attribute-to-role mapping using format `attr_name,attr_value,role1,role2,...`. Repeatable.
`--display`		Sets the connector display name.
`--issuer`		Sets identity provider issuer.
`--sso`		URL of the identity provider's SSO service.
`--cert`		Path to your IdP's certificate PEM file. Your IdP signs responses using this certificate.
`--acs`		URL for the assertion consumer service on the service provider (Teleport's side).
`--audience`		Uniquely identifies our service provider.
`--service-provider-issuer`		Issuer of the service provider (Teleport).
`--signing-key-file`		A file with request signing key. Must be used together with `--signing-cert-file`.
`--signing-cert-file`		A file with request certificate. Must be used together with `--signing-key-file`.
`--assertion-key-file`		A file with key used for securing SAML assertions. Must be used together with `--assertion-cert-file`.
`--assertion-cert-file`		A file with cert used for securing SAML assertions. Must be used together with `--assertion-key-file`.
`--provider`		Sets the external identity provider type, enabling workarounds. Examples: ping, adfs.
`--ignore-missing-roles`		Ignore missing roles referenced in `--attributes-to-roles`.

Supported presets:

Name	Description	Display
`okta`	Okta	Okta
`onelogin`	OneLogin	OneLogin
`ad`	Microsoft Entra ID	Microsoft
`adfs`	Active Directory Federation Services	ADFS

Global flags

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

Examples

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

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

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

<Admonition type="note" title="Important"

To use this command, you must have access to the github_request, oidc_request, and saml_request resources (depending on the type of connector being tested).

If you receive a "permission denied" error, ensure that you have access to the following resources in one of your Teleport roles:

- 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

<Admonition type="note" title="Important"

Make sure to include --with-secrets flag, or the exported auth connector will not be testable.

tctl stable-unix-users ls

List the stored usernames and UIDs for automatically created users:

$ tctl stable-unix-users ls

Arguments

This command accepts no arguments.

Flags

Name	Default Value(s)	Allowed Value(s)	Description
`--format`	`text`	`json` or `text`	Output format

Examples

$ tctl stable-unix-users ls
Username UID
-------- -----
alice    90000
bob      90002
carol    90003
dan      90001

tctl status

Report cluster and Certificate Authority status:

$ tctl status

Examples

# Checks status of cluster.
$ tctl status
Cluster: example.teleport.sh
Version: 17.0.0
CA pins: sha256:a5322b9f89cb94fff13da4bc9c7b2e633626e35161a75f7662a179a01be84ccc

authority rotation                                        protocol status algorithm   storage
--------- ----------------------------------------------- -------- ------ ----------- --------
host      standby (never rotated)                         SSH      active Ed25519     software
                                                          TLS      active ECDSA P-256 software
user      standby (last rotated: Oct 3 2024 22:12:09 UTC) SSH      active ECDSA P-256 AWS KMS
                                                          TLS      active ECDSA P-256 AWS KMS
db        standby (never rotated)                         TLS      active RSA 2048    software
db_client standby (never rotated)                         TLS      active RSA 2048    software
openssh   standby (never rotated)                         SSH      active Ed25519     software
jwt       standby (never rotated)                         JWT      active ECDSA P-256 software
saml_idp  standby (never rotated)                         TLS      active RSA 2048    software
oidc_idp  standby (never rotated)                         JWT      active RSA 2048    software
spiffe    standby (never rotated)                         JWT      active ECDSA P-256 software
                                                          TLS      active ECDSA P-256 software
okta      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

Name	Default Value(s)	Allowed Value(s)	Description
`--format`	none	`text`, `json`, `yaml`	Output format
`--labels`	none	`text`	Sets token labels
`--ttl`	1h	Duration like 5s, 2m, or 3h	Sets how long the token is valid for.
`--type`	none	`proxy`, `auth`, `trusted_cluster`, `node`, `db`, `kube`, `app`, `windowsdesktop`	Type of token to add
`--value`	none	string token value	Value of token to add

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

Name	Default Value(s)	Allowed Value(s)	Description
`--format`	none	`text`, `json`, `yaml`	Output format

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)
# -------------------------------- --------------- -------------------
# (=presets.tokens.first=) Node            11 Oct 19 22:17 UTC
# (=presets.tokens.second=) trusted_cluster 11 Oct 19 22:19 UTC
# (=presets.tokens.third=) 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

Name	Default Value(s)	Allowed Value(s)	Description
`--roles`	none	Comma-separated strings	List of Teleport roles to assign to the new user
`--logins`	none	Comma-separated strings	List of allowed SSH logins for the new user
`--kubernetes-groups`	none	Comma-separated strings	Kubernetes groups to assign to a user, e.g. `system:masters`
`--kubernetes-users`	none	Comma-separated strings	Kubernetes user to assign to a user, e.g. `jenkins`
`--db-users`	none	Comma-separated strings	List of allowed database users for the new user
`--db-names`	none	Comma-separated strings	List of allowed database names for the new user
`--windows-logins`	none	Comma-separated strings	List of allowed Windows logins for the new user
`--aws-role-arns`	none	Comma-separated strings	List of allowed AWS role ARNs for the new user
`--gcp-service-accounts`	none	Comma-separated strings	List of allowed GCP service accounts for the new user
`--azure-identities`	none	Comma-separated strings	List of Azure managed identities to allow the user to assume. Must be the full URIs of the identities
`--ttl`	1h	relative duration like 5s, 2m, or 3h, maximum 48h	Set expiration time for token
`--host-user-uid`	none	Unix UID	UID for auto provisioned host users to use
`--host-user-gid`	none	Unix GID	GID for auto provisioned host users to use

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 multi-factor devices with expiring link to populate values. Usage: tctl users reset <account>

Arguments

<account> - Teleport Local DB User

Flags

Name	Default Value(s)	Allowed Value(s)	Description
`--ttl`	`8h`	relative duration like `5s`, `2m`, or `3h`	Set the expiration time for token, default is `8h0m0s`, maximum is `24h0m0s`

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

Name	Default Value(s)	Allowed Value(s)	Description
`--set-roles`	none	Comma-separated list of roles for the user to assume.	Assigns the user's roles to the ones provided, replacing the user's current roles.
`--set-azure-identities`	none	Comma-separated list of allowed Azure identity URIs.	Assigns the user's allowed Azure identities to the ones provided, replacing the user's currently allowed Azure identities.

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 autoupdate client-tools status

$ tctl autoupdate client-tools status [<flags>]

Requests the current status of client tool managed updates, indicating whether managed updates are enabled and displaying the target version for the update. If the --proxy flag is defined, tctl sends a request to an unauthenticated endpoint to retrieve the data.

Flags

Name	Default Value(s)	Allowed Value(s)	Description
`--proxy`	none	none	Address of the Teleport Proxy Service. When defined this address will be used to retrieve client tool auto update configuration.
`--format`	yaml	`json`, `yaml`	Output format: 'yaml' or 'json'.

Examples

$ tctl autoupdate client-tools status
mode: enabled
target_version: 17.2.7

$ tctl autoupdate client-tools status --format json
{
    "mode": "enabled",
    "target_version": "17.2.7"
}

# Request to an unauthenticated endpoint.
$ tctl autoupdate client-tools status --proxy proxy.example.com
mode: enabled
target_version: 17.2.7

tctl autoupdate client-tools enable

Enables managed updates for client tools in the cluster. If the target version is not set, the proxy version will be advertised.

Examples

$ tctl autoupdate client-tools enable
client tools auto update mode has been changed

tctl autoupdate client-tools disable

Disables managed updates for client tools in the cluster.

Examples

$ tctl autoupdate client-tools disable
client tools auto update mode has been changed

tctl autoupdate client-tools target

$ tctl autoupdate client-tools target [<flags>] <target-version>

Sets the target version for client tools in the cluster. After login, client tools will be advertised to this version and initiate the update process.

Arguments

<target-version> - Client tools target version. Clients will be told to update to this version.

Flags

Name	Default Value(s)	Allowed Value(s)	Description
`--clear`	none	none	Removes the target version, Teleport will default to its current proxy version.

Examples

$ tctl autoupdate client-tools target 17.2.7
client tools auto update target version has been set

$ tctl autoupdate client-tools target --clear
client tools auto update target version has been cleared

tctl autoupdate agents status

Prints the status of automatic updates for Teleport Agents.

Examples

$ tctl autoupdate agents status
Agent autoupdate mode: enabled
Rollout creation date: 2025-01-14 16:17:36
Start version: 17.0.1
Target version: 17.1.5
Rollout state: Done

Group Name State Start Time          State Reason
---------- ----- ------------------- --------------
dev        Done  2025-01-15 12:00:08 outside_window
stage      Done  2025-01-15 16:17:45 outside_window
prod       Done  2025-01-15 18:00:12 outside_window
backup     Done  2025-01-14 20:00:31 outside_window

tctl version

Print the version of your tctl binary:

tctl version

Files

tctl.mdx

Latest commit

History

tctl.mdx

File metadata and controls

Authentication

On a remote host with an identity file

On the same host as the Teleport Auth Service

On a remote host after running tsh login

On a remote host with an identity file

On a remote host after running tsh login

tctl global flags

tctl acl get

tctl acl ls

tctl acl users add

tctl acl users ls

tctl acl users rm

tctl notifications create

Flags

Examples

tctl notifications ls

Flags

Examples

tctl notifications rm

Arguments

Flags

Examples

tctl alerts ack

Arguments

Flags

Examples

tctl alerts ack ls

tctl alerts create

Arguments

Flags

Examples

tctl alerts list

Flags

Examples

tctl auth export

Flags

Global flags

Examples

tctl auth rotate

Flags

Global flags

Examples

tctl auth sign

Flags

Global flags

Examples

tctl bots add

Arguments

Flags

Examples

Global flags

tctl bots instances add

Arguments

Flags

Examples

Global flags

tctl bots instances list

Arguments

Examples

Global flags

tctl bots instances show

Arguments

Examples

Global flags

tctl bots ls

Global flags

tctl bots rm

Arguments

Global flags

tctl bots update

Arguments

Flags

Examples

Global flags

On a remote host after running `tsh login`

On a remote host after running `tsh login`