tctl Reference
This guide provides a comprehensive list of commands, arguments, and flags for tctl.
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.
For a conceptual overview of tctl, see Getting Started with
tctl.
tctl [<flags>] <command> [<args> ...]
Global flags:
| Flag | Default | Description |
|---|---|---|
--auth-server | no default | Attempts to connect to specific auth/proxy address(es) instead of local auth [127.0.0.1:3025] |
-c, --config | no default | Path to a configuration file [/etc/teleport.yaml] for an Auth Service instance. Can also be set via the TELEPORT_CONFIG_FILE environment variable. Ignored if the auth_service is disabled. |
-d, --[no-]debug | false | Enable verbose logging to stderr |
-i, --identity | no default | Path to an identity file. Must be provided to make remote connections to auth. An identity file can be exported with 'tctl auth sign' |
--mfa-mode | auto (one of: auto, cross-platform, platform, sso, browser) | Preferred mode for MFA assertions. |
--[no-]insecure | false | When specifying a proxy address in --auth-server, do not verify its TLS certificate. Danger: any data you send can be intercepted or modified by an attacker. |
Global environment variables:
| Variable | Default | Description |
|---|---|---|
TELEPORT_AUTH_SERVER | no default | Attempts to connect to specific auth/proxy address(es) instead of local auth [127.0.0.1:3025] |
TELEPORT_IDENTITY_FILE | no default | Path to an identity file. Must be provided to make remote connections to auth. An identity file can be exported with 'tctl auth sign' |
TELEPORT_MFA_MODE | auto (one of: auto, cross-platform, platform, sso, browser) | Preferred mode for MFA assertions. |
tctl acl get
Get detailed information for an Access List.
Usage:
tctl acl get [<flags>] <access-list-name>
Flags:
| Flag | Default | Description |
|---|---|---|
--format | yaml (one of: yaml, json, text) | Output format. |
Arguments:
| Argument | Default | Description |
|---|---|---|
| access-list-name | no default (required) | The Access List name. |
tctl acl ls
List cluster Access Lists.
Usage:
tctl acl ls [<flags>]
Flags:
| Flag | Default | Description |
|---|---|---|
--format | yaml (one of: yaml, json, text) | Output format. |
--[no-]review-only | false | List only access lists that are due for review within the next 2 weeks or past due |
tctl acl reviews create
Submit a new review for a given access list.
Usage:
tctl acl reviews create [<flags>] <access-list-name>
Flags:
| Flag | Default | Description |
|---|---|---|
--notes | no default | Optional review notes. |
--remove-members | no default | Comma-separated list of members to remove as part of this review. |
Arguments:
| Argument | Default | Description |
|---|---|---|
| access-list-name | no default (required) | The access list name to submit review for. |
tctl acl reviews ls
List past audit history for a given access list.
Usage:
tctl acl reviews ls [<flags>] <access-list-name>
Flags:
| Flag | Default | Description |
|---|---|---|
--format | text (one of: yaml, json, text) | Output format. |
Arguments:
| Argument | Default | Description |
|---|---|---|
| access-list-name | no default (required) | The access list name to fetch review history for. |
tctl acl summary
Show summary information for access lists, including their members and last review.
Usage:
tctl acl summary [<flags>] [<access-list-name>]
Flags:
| Flag | Default | Description |
|---|---|---|
--format | yaml (one of: yaml, json) | Output format. |
--[no-]review-only | true | Show only access lists that are due for review within the next 2 weeks or past due. Defaults to true. |
Arguments:
| Argument | Default | Description |
|---|---|---|
| access-list-name | no default (optional) | The access list name to show summary for. If not provided, shows summary for all access lists. |
tctl acl users add
Add a user to an Access List.
Usage:
tctl acl users add [<flags>] <access-list-name> <user> [<expires>] [<reason>]
Flags:
| Flag | Default | Description |
|---|---|---|
--kind | user (one of: user, list) | Access list member kind. |
Arguments:
| Argument | Default | Description |
|---|---|---|
| access-list-name | no default (required) | The Access List name. |
| expires | no default (optional) | When the user's access expires (must be in RFC3339). Defaults to the expiration time of the Access List. |
| reason | no default (optional) | The reason the user has been added to the Access List. Defaults to empty. |
| user | no default (required) | The user to add to the Access List. |
tctl acl users ls
List users that are members of an Access List.
Usage:
tctl acl users ls [<flags>] <access-list-name>
Flags:
| Flag | Default | Description |
|---|---|---|
--format | text (one of: json, text) | Output format. |
Arguments:
| Argument | Default | Description |
|---|---|---|
| access-list-name | no default (required) | The Access List name. |
tctl acl users rm
Remove a user from an Access List.
Usage:
tctl acl users rm <access-list-name> <user>
Arguments:
| Argument | Default | Description |
|---|---|---|
| access-list-name | no default (required) | The Access List name. |
| user | no default (required) | The user to remove from the Access List. |
tctl alerts ack
Acknowledge cluster alerts.
Usage:
tctl alerts ack [<flags>] <id>
Flags:
| Flag | Default | Description |
|---|---|---|
--format | text (one of: text, json, yaml) | Output format. |
--[no-]clear | false | Clear the acknowledgment for the cluster alert. |
--reason | no default | The reason for acknowledging the cluster alert. |
--ttl | no default | Time duration to acknowledge the cluster alert for. |
Arguments:
| Argument | Default | Description |
|---|---|---|
| id | no default (required) | The cluster alert ID. |
tctl alerts ack ls
List acknowledged cluster alerts.
Usage:
tctl alerts ack ls
tctl alerts create
Create cluster alerts.
Usage:
tctl alerts create [<flags>] <message>
Flags:
| Flag | Default | Description |
|---|---|---|
--labels | no default | List of labels to attach to the alert. For example: key1=value1,key2=value2. |
--severity | low (one of: low, medium, high) | Severity of the alert. |
--ttl | no default | Time duration after which the alert expires (default 24h). |
Arguments:
| Argument | Default | Description |
|---|---|---|
| message | no default (required) | Alert body message. |
tctl alerts delete
Deletes a cluster alert.
Usage:
tctl alerts delete <id>
Arguments:
| Argument | Default | Description |
|---|---|---|
| id | no default (required) | The cluster alert ID. |
tctl alerts list
List cluster alerts.
Usage:
tctl alerts list [<flags>]
Flags:
| Flag | Default | Description |
|---|---|---|
--format | text (one of: text, json, yaml) | Output format. |
--labels | no default | List of comma separated labels to filter by labels (e.g. key1=value1,key2=value2) |
-v, --[no-]verbose | false | Show detailed alert info, including acknowledged alerts. |
tctl apps ls
List all applications registered with the cluster.
Usage:
tctl apps ls [<flags>] [<labels>]
Flags:
| Flag | Default | Description |
|---|---|---|
--format | text | Output format, 'text', 'json', or 'yaml' |
--query | no default | Query by predicate language enclosed in single quotes. Supports ==, !=, &&, and || (e.g. --query='labels["key1"] == "value1" && labels["key2"] != "value2"') |
--search | no default | List of comma separated search keywords or phrases enclosed in quotations (e.g. --search=foo,bar,"some phrase") |
-v, --[no-]verbose | false | Verbose table output, shows full label output |
Arguments:
| Argument | Default | Description |
|---|---|---|
| labels | no default (optional) | List of comma separated labels to filter by labels (e.g. key1=value1,key2=value2) |
tctl audit query create
Create an audit query.
Usage:
tctl audit query create [<flags>] [<query>]
Flags:
| Flag | Default | Description |
|---|---|---|
--name | no default | Audit query name |
Arguments:
| Argument | Default | Description |
|---|---|---|
| query | no default (optional) | SQL Query |
tctl audit query exec
Execute audit query.
Usage:
tctl audit query exec [<query>]
Arguments:
| Argument | Default | Description |
|---|---|---|
| query | no default (optional) | SQL Query |
tctl audit query get
Get audit query.
Usage:
tctl audit query get <name>
Arguments:
| Argument | Default | Description |
|---|---|---|
| name | no default (required) | name of the audit query |
tctl audit query ls
List audit queries.
Usage:
tctl audit query ls
tctl audit query rm
Remove audit query.
Usage:
tctl audit query rm <name>
Arguments:
| Argument | Default | Description |
|---|---|---|
| name | no default (required) | name of the audit query |
tctl audit report get
Get security report.
Usage:
tctl audit report get <name>
Arguments:
| Argument | Default | Description |
|---|---|---|
| name | no default (required) | security name |
tctl audit report ls
List security reports.
Usage:
tctl audit report ls
tctl audit report run
Run the security report.
Usage:
tctl audit report run <name>
Arguments:
| Argument | Default | Description |
|---|---|---|
| name | no default (required) | security report name |
tctl audit report state
Print the state of the security report.
Usage:
tctl audit report state <name>
Arguments:
| Argument | Default | Description |
|---|---|---|
| name | no default (required) | security report name |
tctl audit schema
Print audit query schema.
Usage:
tctl audit schema
tctl auth crl
Export empty certificate revocation list (CRL) for Teleport certificate authorities.
Usage:
tctl auth crl --type=TYPE [<flags>]
Flags:
| Flag | Default | Description |
|---|---|---|
--out | no default | If set, writes exported revocation lists to files with the given path prefix |
--type | no default (one of: host, db, db_client, user) | Certificate authority type. |
tctl auth export
Export public cluster CA certificates to stdout.
Usage:
tctl auth export [<flags>]
Flags:
| Flag | Default | Description |
|---|---|---|
--compat | no default | export certificates compatible with specific version of Teleport |
--fingerprint | no default | filter authority by fingerprint |
--integration | no default | Name of the integration. Only applies to "github" CAs. |
--[no-]keys | false | if set, will print private keys |
--out | no default | If set writes exported authorities to files with the given path prefix |
--type | no default (one of: user, host, tls-host, tls-user, tls-user-der, tls-spiffe, windows, db, db-der, db-client, db-client-der, openssh, saml-idp, github, awsra, app-client) | export certificate type (user, host, tls-host, tls-user, tls-user-der, tls-spiffe, windows, db, db-der, db-client, db-client-der, openssh, saml-idp, github, awsra, app-client) |
tctl auth ls
List connected auth servers.
Usage:
tctl auth ls [<flags>]
Flags:
| Flag | Default | Description |
|---|---|---|
--format | yaml | Output format: 'yaml', 'json' or 'text' |
tctl auth rotate
Rotate certificate authorities in the cluster. Starts in interactive mode by default, provide --type to manually send rotation requests.
Usage:
tctl auth rotate [<flags>]
Flags:
| Flag | Default | Description |
|---|---|---|
--grace-period | 30h0m0s | Grace period keeps previous certificate authorities signatures valid, if set to 0 will force users to re-login and nodes to re-register. |
--[no-]interactive | false | Enable interactive mode |
--[no-]manual | false | Activate manual rotation, set rotation phases manually |
--phase | no default | Target rotation phase to set, used in manual rotation, one of: init, standby, update_clients, update_servers, rollback |
--type | no default (one of: host, windows, user, db, db_client, openssh, jwt, saml_idp, oidc_idp, spiffe, okta, awsra, bound_keypair, app_client) | Certificate authority to rotate. |
tctl auth sign
Create an identity file(s) for a given user.
Usage:
tctl auth sign --out=OUT [<flags>]
Flags:
| Flag | Default | Description |
|---|---|---|
--app-name | no default | Application to generate identity file for. Mutually exclusive with "--db-service". |
--compat | no default | OpenSSH compatibility flag |
--db-name | no default | Database name placed on the identity file. Only used when "--db-service" is set. |
--db-service | no default | Database to generate identity file for. Mutually exclusive with "--app-name". |
--db-user | no default | Database user placed on the identity file. Only used when "--db-service" is set. |
--format | file | Identity format: file, openssh, tls, kubernetes, db, windows, mongodb, cockroachdb, redis, snowflake, elasticsearch, cassandra, scylla, oracle. file is the default. |
--host | no default | Teleport host name |
--kube-cluster-name | no default | Kubernetes cluster to generate identity file for when --format is set to "kubernetes" |
--leaf-cluster | no default | Leaf cluster to generate identity file for when --format is set to "kubernetes" |
--[no-]omit-cdp | false | Omit CRL Distribution Points from the cert. Only used when --format is set to "windows" |
--[no-]overwrite | false | Whether to overwrite existing destination files. When not set, user will be prompted before overwriting any existing file. |
--[no-]tar | false | Create a tarball of the resulting certificates and stream to stdout. |
-o, --out | no default | Identity output |
--proxy | no default | Address of the Teleport proxy. When --format is set to "kubernetes", this address will be set as cluster address in the generated kubeconfig file |
--ttl | 12h0m0s | TTL (time to live) for the generated certificate. |
--user | no default | Teleport user name |
--windows-domain | no default | Active Directory domain for which this cert is valid. Only used when --format is set to "windows" |
--windows-pki-domain | no default | Active Directory domain where CRLs will be located. Only used when --format is set to "windows" |
--windows-sid | no default | Optional Security Identifier to embed in the certificate. Only used when --format is set to "windows" |
--windows-user | no default | Window user placed on the identity file. Only used when --format is set to "windows" |
tctl autoupdate agents mark-done
Marks one or many groups as done updating.
Usage:
tctl autoupdate agents mark-done [<groups>...]
Arguments:
| Argument | Default | Description |
|---|---|---|
| groups | no default (optional) | Groups to mark as done updating. |
tctl autoupdate agents report
Aggregates the agent autoupdate reports and displays agent count per version and per update group.
Usage:
tctl autoupdate agents report
tctl autoupdate agents rollback
Rolls back one or many groups.
Usage:
tctl autoupdate agents rollback [<groups>...]
Arguments:
| Argument | Default | Description |
|---|---|---|
| groups | no default (optional) | Groups to rollback. When empty, every group already started is rolled back. |
tctl autoupdate agents start-update
Starts updating one or many groups.
Usage:
tctl autoupdate agents start-update [<flags>] [<groups>...]
Flags:
| Flag | Default | Description |
|---|---|---|
--[no-]force | false | Skips progressive deployment mechanism such as canaries or backpressure. |
Arguments:
| Argument | Default | Description |
|---|---|---|
| groups | no default (optional) | Groups to start updating. |
tctl autoupdate agents status
Prints agents auto update status.
Usage:
tctl autoupdate agents status
tctl autoupdate client-tools disable
Disables client tools auto updates. Clients will not be told to update to the target version.
Usage:
tctl autoupdate client-tools disable
tctl autoupdate client-tools enable
Enables client tools auto updates. Clients will be told to update to the target version.
Usage:
tctl autoupdate client-tools enable
tctl autoupdate client-tools status
Prints if the client tools updates are enabled/disabled, and the target version in specified format.
Usage:
tctl autoupdate client-tools status [<flags>]
Flags:
| Flag | Default | Description |
|---|---|---|
--format | yaml | Output format: 'yaml' or 'json' |
--proxy | no default | Address of the Teleport proxy. When defined this address will be used to retrieve client tools auto update configuration. |
tctl autoupdate client-tools target
Sets the client tools target version. This command is not supported on Teleport Cloud.
Usage:
tctl autoupdate client-tools target [<flags>] [<version>]
Flags:
| Flag | Default | Description |
|---|---|---|
--[no-]clear | false | Removes the target version, Teleport will default to its current proxy version. |
Arguments:
| Argument | Default | Description |
|---|---|---|
| version | no default (optional) | Client tools target version. Clients will be told to update to this version. |
tctl bots add
Add a new bot to the cluster.
Usage:
tctl bots add [<flags>] <name>
Flags:
| Flag | Default | Description |
|---|---|---|
--format | text (one of: text, json) | Output format. |
--initial-public-key | no default | If set, use the given initial public key in SSH authorized_keys format, instead of generating a registration secret. The value must be quoted. Not compatible with --token or --legacy. |
--logins | no default | List of allowed SSH logins for the bot user |
--max-session-ttl | no default | Set a max session TTL for the bot's internal identity. 12h default, 168h maximum. |
--[no-]legacy | false | If set, generate a legacy joining token instead of a bound keypair token. No effect if --token is set. |
--recovery-limit | no default | Overrides the recovery limit (default: 1) for the bound keypair token. No effect if --token or --legacy is set, or if --recovery-mode is not standard. Must be greater than 1. |
--recovery-mode | standard (one of: standard, relaxed, insecure) | If set, overrides the recovery mode for the bound keypair token. No effect if --token or --legacy is set. |
--registration-secret | no default | Sets a registration secret for the bound keypair token. If not set, one will be randomly generated. No effect if --initial-public-key, --token, or --legacy is set. |
--roles | no default | Roles the bot is able to assume. |
--token | no default | The token to use, if any. If unset, a new single-use token will be created. |
--ttl | 1h0m0s | TTL for the bot join token. For standard bound keypair tokens, this sets must_register_before; for legacy tokens, this sets the resource TTL. |
Arguments:
| Argument | Default | Description |
|---|---|---|
| name | no default (required) | A name to uniquely identify this bot in the cluster. |
tctl bots instances add
Join a new instance onto an existing bot.
Usage:
tctl bots instances add [<flags>] <name>
Flags:
| Flag | Default | Description |
|---|---|---|
--format | text (one of: text, json) | Output format. |
--initial-public-key | no default | If set, use the given initial public key in SSH authorized_keys format, instead of generating a registration secret. The value must be quoted. Not compatible with --token or --legacy. |
--[no-]legacy | false | If set, generate a legacy joining token instead of a bound keypair token. No effect if --token is set. |
--recovery-limit | no default | Overrides the recovery limit (default: 1) for the bound keypair token. No effect if --token or --legacy is set, or if --recovery-mode is not standard. Must be greater than 1. |
--recovery-mode | standard (one of: standard, relaxed, insecure) | If set, overrides the recovery mode for the bound keypair token. No effect if --token or --legacy is set. |
--registration-secret | no default | Sets a registration secret for the bound keypair token. If not set, one will be randomly generated. No effect if --initial-public-key, --token, or --legacy is set. |
--token | no default | The token to use, if any. If unset, a new single-use token will be created. |
--ttl | 1h0m0s | TTL for the bot join token. For standard bound keypair tokens, this sets must_register_before; for legacy tokens, this sets the resource TTL. |
Arguments:
| Argument | Default | Description |
|---|---|---|
| name | no default (required) | The name of the existing bot for which to add a new instance. |
tctl bots instances list
List bot instances.
Usage:
tctl bots instances list [<flags>] [<name>]
Flags:
| Flag | Default | Description |
|---|---|---|
--format | text (one of: text, json) | Output format. |
--query | no default | An expression in the Teleport predicate language used to filter bot instances |
--search | no default | Fuzzy search query used to filter bot instances |
--sort-index | bot_name | Request sort index, 'bot_name', 'active_at_latest', 'version_latest' or 'host_name_latest' |
--sort-order | ascending | Request sort order, 'ascending' or 'descending' |
Arguments:
| Argument | Default | Description |
|---|---|---|
| name | no default (optional) | The name of the bot from which to list instances. If unset, lists instances from all bots. |
tctl bots instances show
Shows information about a specific bot instance.
Usage:
tctl bots instances show <id>
Arguments:
| Argument | Default | Description |
|---|---|---|
| id | no default (required) | The full ID of the bot instance, in the form of [bot name]/[uuid] |
tctl bots ls
List all certificate renewal bots registered with the cluster.
Usage:
tctl bots ls
tctl bots rm
Permanently remove a certificate renewal bot from the cluster.
Usage:
tctl bots rm <name>
Arguments:
| Argument | Default | Description |
|---|---|---|
| name | no default (required) | Name of an existing bot to remove. |
tctl bots update
Update an existing bot.
Usage:
tctl bots update [<flags>] <name>
Flags:
| Flag | Default | Description |
|---|---|---|
--add-logins | no default | Adds a comma-separated list of logins to an existing bot. |
--add-roles | no default | Adds a comma-separated list of roles to an existing bot. |
--set-logins | no default | Sets the bot's logins to the given comma-separated list, replacing any existing logins. |
--set-max-session-ttl | no default | Sets the max session TTL. 168h maximum. |
--set-roles | no default | Sets the bot's roles to the given comma-separated list, replacing any existing roles. |
Arguments:
| Argument | Default | Description |
|---|---|---|
| name | no default (required) | Name of an existing bot to update. |
tctl bound-keypair request-rotation
Request a keypair rotation on the next join attempt.
Usage:
tctl bound-keypair request-rotation <name>
Arguments:
| Argument | Default | Description |
|---|---|---|
| name | no default (required) | The name of the token |
tctl create
Create or update a Teleport resource from a YAML file.
Usage:
tctl create [<flags>] [<filename>]
Flags:
| Flag | Default | Description |
|---|---|---|
-f, --[no-]force | false | Overwrite the resource if already exists |
Arguments:
| Argument | Default | Description |
|---|---|---|
| filename | no default (optional) | resource definition file, empty for stdin |
tctl db ls
List all databases registered with the cluster.
Usage:
tctl db ls [<flags>] [<labels>]
Flags:
| Flag | Default | Description |
|---|---|---|
--format | text | Output format, 'text', 'json', or 'yaml' |
--query | no default | Query by predicate language enclosed in single quotes. Supports ==, !=, &&, and || (e.g. --query='labels["key1"] == "value1" && labels["key2"] != "value2"') |
--search | no default | List of comma separated search keywords or phrases enclosed in quotations (e.g. --search=foo,bar,"some phrase") |
-v, --[no-]verbose | false | Verbose table output, shows full label output |
Arguments:
| Argument | Default | Description |
|---|---|---|
| labels | no default (optional) | List of comma separated labels to filter by labels (e.g. key1=value1,key2=value2) |
tctl desktop bootstrap
Generate a PowerShell script to bootstrap Active Directory.
Usage:
tctl desktop bootstrap
tctl desktop ls
List all desktops registered with the cluster.
Usage:
tctl desktop ls [<flags>]
Flags:
| Flag | Default | Description |
|---|---|---|
--format | text | Output format, 'text', 'json' or 'yaml' |
-v, --[no-]verbose | false | Verbose table output, shows full label output |
tctl devices add
Register managed devices.
Usage:
tctl devices add [<flags>]
Flags:
| Flag | Default | Description |
|---|---|---|
--asset-tag | no default | Inventory identifier for the device (e.g., Mac serial number) |
--enroll-ttl | no default | Time duration for the enrollment token |
--format | text (one of: text, json, yaml) | Output format. |
--[no-]current-device | false | Registers the current device. Overrides --os and --asset-tag. |
--[no-]enroll | false | If set, creates a device enrollment token |
--os | no default (one of: linux, macos, windows) | Operating system |
tctl devices enroll
Creates a new device enrollment token.
Usage:
tctl devices enroll [<flags>]
Flags:
| Flag | Default | Description |
|---|---|---|
--asset-tag | no default | Inventory identifier for the device |
--device-id | no default | Device identifier |
--[no-]current-device | false | Enrolls the current device. Overrides --device-id and --asset-tag. |
--ttl | no default | Time duration for the enrollment token |
tctl devices lock
Locks a device.
Usage:
tctl devices lock [<flags>]
Flags:
| Flag | Default | Description |
|---|---|---|
--asset-tag | no default | Inventory identifier for the device |
--device-id | no default | Device identifier |
--expires | no default | Time point (RFC3339) when the lock expires |
--message | no default | Message to display to locked-out users |
--[no-]current-device | false | Locks the current device. Overrides --device-id and --asset-tag. |
--ttl | no default | Time duration after which the lock expires |
tctl devices ls
Lists managed devices.
Usage:
tctl devices ls [<flags>]
Flags:
| Flag | Default | Description |
|---|---|---|
--format | text (one of: text, json, yaml) | Output format. |
tctl devices rm
Removes a managed device.
Usage:
tctl devices rm [<flags>]
Flags:
| Flag | Default | Description |
|---|---|---|
--asset-tag | no default | Inventory identifier for the device |
--device-id | no default | Device identifier |
--[no-]current-device | false | Removes the current device. Overrides --device-id and --asset-tag. |
tctl discovery nodes
Report discovered server instances and their enrollment status using Teleport audit log and cluster state.
Usage:
tctl discovery nodes [<flags>]
Flags:
| Flag | Default | Description |
|---|---|---|
--cloud | `` | Comma-separated list of cloud providers to include (allowed: aws, azure). Empty (default) returns all. |
--format | text (one of: text, json) | Output format. |
--last | 1h | Time window to look back for failures in Teleport audit log (e.g. 1h, 24h, 30m). |
--[no-]failures-only | false | Only show instances with enrollment failures. |
tctl edit
Edit a Teleport resource.
Usage:
tctl edit [<resource type/resource name>]
Arguments:
| Argument | Default | Description |
|---|---|---|
| resource type/resource name | no default (optional) | Resource to update, e.g., "user/myuser" |
tctl get
Print a YAML declaration of various Teleport resources.
Usage:
tctl get [<flags>] <resources>
Flags:
| Flag | Default | Description |
|---|---|---|
--format | yaml | Output format: 'yaml', 'json' or 'text' |
--[no-]with-secrets | false | Include secrets in resources like certificate authorities or OIDC connectors |
-v, --[no-]verbose | false | Verbose table output, shows full label output |
Arguments:
| Argument | Default | Description |
|---|---|---|
| resources | no default (required) | Resource spec: 'type/[name][,...]' or 'all' |
tctl help
Show help.
Usage:
tctl help [<command>...]
Arguments:
| Argument | Default | Description |
|---|---|---|
| command | no default (optional) | Show help on command. |
tctl idp saml test-attribute-mapping
Test expression evaluation of attribute mapping.
Usage:
tctl idp saml test-attribute-mapping --users=USERS --sp=SP [<flags>]
Flags:
| Flag | Default | Description |
|---|---|---|
--format | no default | output format, 'yaml' or 'json' |
--sp | no default | name of a file containing service provider spec |
-u, --users | no default | username or name of a file containing user spec |
tctl inventory list
List Teleport instance inventory.
Usage:
tctl inventory list [<flags>]
Flags:
| Flag | Default | Description |
|---|---|---|
--exact-version | no default | Filter output by teleport version |
--format | text | Output format, 'text' or 'json' |
--newer-than | no default | Filter for newer teleport versions |
--older-than | no default | Filter for older teleport versions |
--services | no default | Filter output by service (node,kube,proxy,etc) |
--update-group | no default | Filter output by update group |
--upgrader | no default | Filter output by upgrader (kube,unit,none) |
tctl inventory ping
Ping locally connected instance.
Usage:
tctl inventory ping <server-id>
Arguments:
| Argument | Default | Description |
|---|---|---|
| server-id | no default (required) | ID of target server |
tctl inventory status
Show inventory status summary.
Usage:
tctl inventory status [<flags>]
Flags:
| Flag | Default | Description |
|---|---|---|
--format | text | Output format, 'text' or 'json' |
--[no-]connected | false | Show locally connected instances summary |
tctl kube ls
List all Kubernetes clusters registered with the cluster.
Usage:
tctl kube ls [<flags>] [<labels>]
Flags:
| Flag | Default | Description |
|---|---|---|
--format | text | Output format, 'text', 'json', or 'yaml' |
--query | no default | Query by predicate language enclosed in single quotes. Supports ==, !=, &&, and || (e.g. --query='labels["key1"] == "value1" && labels["key2"] != "value2"') |
--search | no default | List of comma separated search keywords or phrases enclosed in quotations (e.g. --search=foo,bar,"some phrase") |
-v, --[no-]verbose | false | Verbose table output, shows full label output |
Arguments:
| Argument | Default | Description |
|---|---|---|
| labels | no default (optional) | List of comma separated labels to filter by labels (e.g. key1=value1,key2=value2) |
tctl list-kinds
Lists all resource kinds supported by this tctl version.
Usage:
tctl list-kinds [<flags>]
Flags:
| Flag | Default | Description |
|---|---|---|
--[no-]wide | false | Do not truncate the Description column, even if it exceeds terminal width |
tctl lock
Create a new lock.
Usage:
tctl lock [<flags>]
Flags:
| Flag | Default | Description |
|---|---|---|
--access-request | no default | UUID of an Access Request to disable. |
--bot-instance-id | no default | UUID of a bot instance to disable |
--device | no default | UUID of a trusted device to disable. |
--expires | no default | Time point (RFC3339) when the lock expires. |
--join-token | no default | Bot join token name to disable |
--linux-desktop | no default | Name of a Linux desktop to disable. |
--login | no default | Name of a local UNIX user to disable. |
--message | no default | Message to display to locked-out users. |
--mfa-device | no default | UUID of a user MFA device to disable. |
--role | no default | Name of a Teleport role to disable. |
--server-id | no default | UUID of a Teleport server to disable. |
--ttl | no default | Time duration after which the lock expires. |
--user | no default | Name of a Teleport user to disable. |
--windows-desktop | no default | Name of a Windows desktop to disable. |
tctl login_rule test
Test the parsing and evaluation of login rules.
Usage:
tctl login_rule test [<flags>] [<traits-file>]
Flags:
| Flag | Default | Description |
|---|---|---|
--format | yaml | Output format: 'yaml' or 'json' |
--[no-]load-from-cluster | false | load existing login rules from the connected Teleport cluster |
--resource-file | no default | login rule resource file name (YAML or JSON) |
Arguments:
| Argument | Default | Description |
|---|---|---|
| traits-file | no default (optional) | input user traits file name (YAML or JSON), empty for stdin |
tctl nodes add
Generate a node invitation token.
Usage:
tctl nodes add [<flags>]
Flags:
| Flag | Default | Description |
|---|---|---|
--roles | node | Comma-separated list of roles for the new node to assume [node] |
--token | no default | Override the default random generated token with a specified value |
--ttl | 30m0s | Time to live for a generated token |
tctl nodes ls
List all active SSH nodes within the cluster.
Usage:
tctl nodes ls [<flags>] [<labels>]
Flags:
| Flag | Default | Description |
|---|---|---|
--format | text | Output format, 'text', or 'yaml' |
--query | no default | Query by predicate language enclosed in single quotes. Supports ==, !=, &&, and || (e.g. --query='labels["key1"] == "value1" && labels["key2"] != "value2"') |
--search | no default | List of comma separated search keywords or phrases enclosed in quotations (e.g. --search=foo,bar,"some phrase") |
-v, --[no-]verbose | false | Verbose table output, shows full label output |
Arguments:
| Argument | Default | Description |
|---|---|---|
| labels | no default (optional) | List of comma separated labels to filter by labels (e.g. key1=value1,key2=value2) |
tctl notifications create
Create a cluster notification.
Usage:
tctl notifications create --title=TITLE --content=CONTENT [<flags>]
Flags:
| Flag | Default | Description |
|---|---|---|
--content | no default | Set the notification's content. |
--labels | no default | List of labels to attach to the notification. For example: key1=value1,key2=value2. |
--[no-]require-all-roles | false | Set whether this notification should target users who have all of the provided roles. |
--[no-]warning | false | Set whether this notification is a warning notification. |
--roles | no default | Target a specific set of roles. By default, this will target all users with any of the provided roles, use --require-all-roles to exclusively target users with all of them. |
-t, --title | no default | Set the notification's title. |
--ttl | 30d | Time duration after which the notification expires (default 30 days). |
--user | no default | Target a specific user. |
tctl notifications ls
List notifications which were manually created using tctl notifications create. By default, this will list notifications capable of targeting multiple
users, such as role-based ones. To list notifications directed only at a
specific user, use the --user flag. To include notifications generated by
Teleport, use --all.
Usage:
tctl notifications ls [<flags>]
Flags:
| Flag | Default | Description |
|---|---|---|
--format | text (one of: yaml, json, text) | Output format. |
--labels | no default | List of comma separated labels to filter by labels (e.g. key1=value1,key2=value2) |
--[no-]all | false | Set whether all notifications should be included, including those generated by Teleport, as opposed to solely those created using tctl notifications create. |
--user | no default | Set which user to list user-specific notifications for, or leave empty to list your own. |
tctl notifications rm
Remove a cluster notification.
Usage:
tctl notifications rm [<flags>] <id>
Flags:
| Flag | Default | Description |
|---|---|---|
--user | no default | The user the notification to remove belongs to, if any. |
Arguments:
| Argument | Default | Description |
|---|---|---|
| id | no default (required) | The ID of the notification to remove. |
tctl plugins cleanup
Cleans up the given plugin type.
Usage:
tctl plugins cleanup [<flags>] <type>
Flags:
| Flag | Default | Description |
|---|---|---|
--[no-]dry-run | true | Dry run the cleanup command. Dry run defaults to on. |
Arguments:
| Argument | Default | Description |
|---|---|---|
| type | no default (required) | The type of plugin to clean up. Only supports Okta at present. |
tctl plugins delete
Remove a plugin instance.
Usage:
tctl plugins delete [<name>]
Arguments:
| Argument | Default | Description |
|---|---|---|
| name | no default (optional) | The name of the SCIM plugin resource to delete |
tctl plugins edit awsic
Edit an AWS IAM Identity Center integration's settings.
Usage:
tctl plugins edit awsic [<flags>]
Flags:
| Flag | Default | Description |
|---|---|---|
--plugin-name | aws-identity-center | Name of the AWS Identity Center integration instance to update. Defaults to aws-identity-center. |
--roles-sync-mode | no default (one of: ALL, NONE) | Control account-assignment role creation. ALL creates roles for all possible account assignments. NONE creates no roles, and also implies a totally-exclusive group import filter. |
tctl plugins install awsic
Install an AWS IAM Identity Center integration.
Usage:
tctl plugins install awsic --access-list-default-owner=ACCESS-LIST-DEFAULT-OWNER --scim-url=SCIM-URL --scim-token=SCIM-TOKEN --instance-region=INSTANCE-REGION --instance-arn=INSTANCE-ARN [<flags>]
Flags:
| Flag | Default | Description |
|---|---|---|
--access-list-default-owner | no default | Teleport user to set as default owner for the imported Access Lists. Multiple flags allowed. |
--account-id | no default | Add AWS Account to account import list by ID. All AWS accounts will be imported if no items are added to account import list. |
--account-name | no default | Add AWS Account to account import list by name. Can be a glob, or enclosed in ^$ to specify a regular expression. All AWS accounts will be imported if no items are added to account import list. |
--assume-role-arn | no default | ARN of a role that the system credential should assume. |
--exclude-account-id | no default | Exclude AWS account from import list by ID. |
--exclude-account-name | no default | Exclude AWS account from import list by name. Can be a glob or a regular expression (enclosed in ^$). |
--exclude-group-name | no default | Exclude AWS group from import list by name. Can be a glob or a regular expression (enclosed in ^$). |
--group-name | no default | Add AWS group to group import list by name. Can be a glob, or enclosed in ^$ to specify a regular expression. If no filters are supplied then all AWS groups will be imported. |
--instance-arn | no default | AWS Identity center instance ARN |
--instance-region | no default | AWS Identity Center instance region |
--[no-]force-scim-url | false | Use the provided SCIM provisioning endpoint even if it fails scim endpoint validation |
--[no-]use-system-credentials | true | Uses system credentials instead of OIDC. |
--oidc-integration | no default | Name of the Teleport OIDC integration to use when authenticating with AWS. Must be supplied when --no-use-system-credentials is set. |
--roles-sync-mode | ALL (one of: ALL, NONE) | Control account-assignment role creation. ALL creates Teleport Roles for all possible account assignments. NONE creates no Teleport Roles, and also implies a totally-exclusive group import filter. |
--scim-token | no default | AWS Identify Center SCIM provisioning token. |
--scim-url | no default | AWS Identity Center SCIM provisioning endpoint |
--user-label | no default | Add user label filter, in the form of a comma-separated list of "name=value" pairs. If no label filters are supplied, all Teleport users will be provisioned to Identity Center |
--user-origin | no default (any of (repeatable): defaults, config-file, dynamic, cloud, kubernetes, okta, scim, discovery-kubernetes, entra-id, aws-identity-center, integration_awsrolesanywhere) | Shorthand for "--user-label teleport.dev/origin=ORIGIN" |
tctl plugins install entraid
Install an Microsoft Entra ID integration.
Usage:
tctl plugins install entraid --default-owner=DEFAULT-OWNER [<flags>]
Flags:
| Flag | Default | Description |
|---|---|---|
--access-list-owners-source | plugin | Source of the Access List owners. |
--auth-connector-name | entra-id-default | Name of the SAML connector resource to create |
--default-owner | no default | List of Teleport users that are default owners for the imported Access Lists. Multiple flags allowed. |
--exclude-group-id | no default | Exclude group matching the specified group ID. |
--exclude-group-name | no default | Exclude groups matching the specified group name regex. |
-f, --[no-]force | false | Proceed with installation even if plugin already exists. |
--group-id | no default | Include group matching the specified group ID. |
--group-name | no default | Include groups matching the specified group name regex. |
-m, --[no-]manual-setup | false | Manually set up the EntraID integration. |
--name | entra-id | Name of the plugin resource to create |
--[no-]access-graph | true | Enables Access Graph cache build. |
--[no-]use-system-credentials | false | Uses system credentials instead of OIDC. |
tctl plugins install github
Install an Access Graph Github integration.
Usage:
tctl plugins install github [<flags>]
Flags:
| Flag | Default | Description |
|---|---|---|
--start-date | <today> | Start date for the audit log ingest in the YYYY-MM-DD format. |
tctl plugins install netiq
Install an Access Graph NetIQ integration.
Usage:
tctl plugins install netiq [<flags>]
Flags:
| Flag | Default | Description |
|---|---|---|
--[no-]insecure-skip-verify | false | Skip verification of the NetIQ server's SSL certificate. |
tctl plugins install okta
Install an Okta integration.
Usage:
tctl plugins install okta --org=ORG --saml-connector=SAML-CONNECTOR [<flags>]
Flags:
| Flag | Default | Description |
|---|---|---|
-a, --app-filter | no default | Add an app filter. Supports globbing by default. Enclose in ^pattern$ for full regex support. |
--api-token | no default | Okta API token for the plugin to use |
--app-id | no default | Okta ID of the APP used for SSO via SAML |
-g, --group-filter | no default | Add a group filter. Supports globbing by default. Enclose in ^pattern$ for full regex support. |
--name | okta | Name of the plugin resource to create |
--[no-]accesslist-sync | true | Enable group to Access List synchronization |
--[no-]appgroup-sync | true | Enable Okta Applications and Groups sync |
--[no-]assign-default-roles | true | If user synchronization is enabled, assign the builtin okta-requester role to synchronized users |
--[no-]scim | false | Enable SCIM Okta integration |
--[no-]system-logs-export | false | Enables the Teleport Identity Security SIEM integration for Okta. |
--[no-]users-sync | true | Enable user synchronization |
-o, --owner | no default | Add default owners for synced Access Lists |
--org | no default | URL of Okta organization |
--saml-connector | no default | SAML connector used for Okta SSO login. |
tctl plugins install scim
Install a Teleport SCIM plugin.
Usage:
tctl plugins install scim --connector=CONNECTOR [<flags>]
Flags:
| Flag | Default | Description |
|---|---|---|
--auth | oauth (one of: bearer, oauth) | Plugin Authentication type. |
--connector | no default | Name of the Teleport connector to use. |
--connector-type | no default (one of: oidc, saml) | Type of the Teleport connector to use. |
tctl plugins rotate awsic
Rotate the AWS Identity Center SCIM bearer token.
Usage:
tctl plugins rotate awsic [<flags>] TOKEN
Flags:
| Flag | Default | Description |
|---|---|---|
--[no-]validate-token | true | Validate that the supplied token is valid for the configured downstream SCIM service |
--plugin-name | aws-identity-center | Name of the AWSIC plugin instance to update. Defaults to aws-identity-center. |
Arguments:
| Argument | Default | Description |
|---|---|---|
| token | no default (required) | The new SCIM bearer token. |
tctl proxy ls
Lists proxies connected to the cluster.
Usage:
tctl proxy ls [<flags>]
Flags:
| Flag | Default | Description |
|---|---|---|
--format | yaml | Output format: 'yaml', 'json' or 'text' |
tctl recordings download
Download session recordings.
Usage:
tctl recordings download [<flags>] <session-id>
Flags:
| Flag | Default | Description |
|---|---|---|
-o, --output-dir | <current working directory> | Directory to download session recordings to. |
Arguments:
| Argument | Default | Description |
|---|---|---|
| session-id | no default (required) | ID of the session to download recordings for. |
tctl recordings encryption complete-rotation
Completes an in-progress encryption key rotation.
Usage:
tctl recordings encryption complete-rotation
tctl recordings encryption rollback-rotation
Rolls back an in-progress encryption key rotation.
Usage:
tctl recordings encryption rollback-rotation
tctl recordings encryption rotate
Rotate encryption keys used for encrypting session recordings.
Usage:
tctl recordings encryption rotate
tctl recordings encryption status
Show current rotation status.
Usage:
tctl recordings encryption status [<flags>]
Flags:
| Flag | Default | Description |
|---|---|---|
--format | text | Format output (text, json, yaml).. Defaults to 'text'. |
tctl recordings ls
List recorded sessions.
Usage:
tctl recordings ls [<flags>]
Flags:
| Flag | Default | Description |
|---|---|---|
--format | text | Format output (text, json, yaml).. Defaults to 'text'. |
--from-utc | no default | Start of time range in which recordings are listed. Format 2006-01-02. Defaults to 24 hours ago. |
--last | no default | Duration into the past from which session recordings should be listed. Format 5h30m40s |
--limit | 50 | Maximum number of recordings to show. Default 50. |
--to-utc | no default | End of time range in which recordings are listed. Format 2006-01-02. Defaults to current time. |
tctl recordings search
Search session recordings using semantic and keyword queries.
Usage:
tctl recordings search [<flags>] [<query>...]
Flags:
| Flag | Default | Description |
|---|---|---|
--access-request | no default | Filter by access request ID. Can be specified multiple times. |
--database-name | no default | Filter database sessions by database name. |
--format | text | Format output (text, json, yaml).. Defaults to 'text'. |
--from | no default | Start of time range. Format 2006-01-02. Defaults to 24 hours ago. |
--kind | no default | Filter by session kind (ssh, db, k8s, desktop). Can be specified multiple times. |
--label | no default | Filter by resource labels (key=value pairs), e.g. env/prod=true,db/type=postgres. |
--limit | 50 | Maximum number of results to return. |
--pod-name | no default | Filter Kubernetes sessions by pod name. |
--pod-namespace | no default | Filter Kubernetes sessions by pod namespace. |
--resource-kind | no default | Filter by Teleport resource type (node, kube_cluster, db). |
--resource-name | no default | Filter by resource name. |
--role | no default | Filter by role held during the session. Can be specified multiple times. |
--search-mode | hybrid (one of: hybrid, keyword, embeddings) | Search strategy to use when search queries are provided. |
--server-addr | no default | Filter SSH sessions by server address. |
--server-hostname | no default | Filter SSH sessions by server hostname. |
--severity | no default | Minimum severity level to include (low, medium, high, critical). |
--to | no default | End of time range. Format 2006-01-02. Defaults to current time. |
--username | no default | Filter by the Teleport username that initiated the session. |
Arguments:
| Argument | Default | Description |
|---|---|---|
| query | no default (optional) | Natural language description of the sessions to find (e.g. "SSH sessions exfiltrating data to external endpoints"). |
tctl requests approve
Approve pending Access Request.
Usage:
tctl requests approve [<flags>] <request-id>
Flags:
| Flag | Default | Description |
|---|---|---|
--annotations | no default | Resolution attributes <key>=<val>[,...] |
--assume-start-time | no default | Sets time roles can be assumed by requestor (RFC3339 e.g 2023-12-12T23:20:50.52Z) |
--delegator | no default | Optional delegating identity |
--reason | no default | Optional reason message |
--roles | no default | Override requested roles <role>[,...] |
Arguments:
| Argument | Default | Description |
|---|---|---|
| request-id | no default (required) | ID of target request(s) |
tctl requests create
Create pending Access Request.
Usage:
tctl requests create [<flags>] <username>
Flags:
| Flag | Default | Description |
|---|---|---|
--[no-]dry-run | false | Don't actually generate the Access Request |
--reason | no default | Optional reason message |
--resource | no default | Resource ID to be requested |
--roles | no default | Roles to be requested |
Arguments:
| Argument | Default | Description |
|---|---|---|
| username | no default (required) | Name of target user |
tctl requests deny
Deny pending Access Request.
Usage:
tctl requests deny [<flags>] <request-id>
Flags:
| Flag | Default | Description |
|---|---|---|
--annotations | no default | Resolution annotations <key>=<val>[,...] |
--delegator | no default | Optional delegating identity |
--reason | no default | Optional reason message |
Arguments:
| Argument | Default | Description |
|---|---|---|
| request-id | no default (required) | ID of target request(s) |
tctl requests get
Show Access Request by ID.
Usage:
tctl requests get <request-id>
Arguments:
| Argument | Default | Description |
|---|---|---|
| request-id | no default (required) | ID of target request(s) |
tctl requests ls
Show active Access Requests.
Usage:
tctl requests ls [<flags>]
Flags:
| Flag | Default | Description |
|---|---|---|
--sort-index | created | Request sort index, 'created' or 'state' |
--sort-order | descending | Request sort order, 'ascending' or 'descending' |
tctl requests review
Review an Access Request.
Usage:
tctl requests review --author=AUTHOR [<flags>] <request-id>
Flags:
| Flag | Default | Description |
|---|---|---|
--author | no default | Username of reviewer |
--[no-]approve | false | Review proposes approval |
--[no-]deny | false | Review proposes denial |
Arguments:
| Argument | Default | Description |
|---|---|---|
| request-id | no default (required) | ID of target request |
tctl requests rm
Delete an Access Request.
Usage:
tctl requests rm [<flags>] <request-id>
Flags:
| Flag | Default | Description |
|---|---|---|
-f, --[no-]force | false | Force the deletion of an active Access Request |
Arguments:
| Argument | Default | Description |
|---|---|---|
| request-id | no default (required) | ID of target request(s) |
tctl rm
Delete a resource.
Usage:
tctl rm [<resource type/resource name>]
Arguments:
| Argument | Default | Description |
|---|---|---|
| resource type/resource name | no default (optional) | Resource to delete |
| <resource type> Type of a resource [for example: connector,user,cluster,token] | ||
| <resource name> Resource name to delete |
Examples: $ tctl rm role/devs $ tctl rm cluster/main|
tctl saml export
Export a SAML signing key in .crt format.
Usage:
tctl saml export <connector_name>
Arguments:
| Argument | Default | Description |
|---|---|---|
| connector_name | no default (required) | name of the SAML connector to export the key from |
tctl scoped assignments list
List scoped role assignments
Usage:
tctl scoped assignments list [<flags>]
Flags:
| Flag | Default | Description |
|---|---|---|
-f, --format | text (one of: text, json, yaml) | Format output (text, json, yaml). |
--role | no default | Filter by assigned role. |
--user | no default | Filter by user. |
tctl scoped status
Show the status of scoped resources.
Usage:
tctl scoped status
tctl scoped tokens add
Create a scoped invitation token.
Usage:
tctl scoped tokens add --type=TYPE [<flags>]
Flags:
| Flag | Default | Description |
|---|---|---|
--assign-scope | no default | Scope that should be applied to resources provisioned by this token |
--format | no default (one of: text, json, yaml) | Format output (text, json, yaml). |
--labels | no default | Set token labels, e.g. env=prod,region=us-west |
--mode | no default | Usage mode of a token (default: unlimited, single_use) |
--name | no default | Override the default, randomly generated token name with a specified name |
--scope | no default | Scope assigned to the token itself |
--ssh-labels | no default | Set immutable ssh labels the token should assign to provisioned resources, e.g. env=prod,region=us-west |
--ttl | 30m0s | Set expiration time for token, default is 30 minutes |
--type | no default | Type(s) of token to add, e.g. --type=node |
tctl scoped tokens ls
List invitation tokens.
Usage:
tctl scoped tokens ls [<flags>]
Flags:
| Flag | Default | Description |
|---|---|---|
-f, --format | no default (one of: text, json, yaml) | Format output (text, json, yaml). |
--[no-]with-secrets | false | Do not redact join tokens |
tctl scoped tokens rm
Delete/revoke a scoped invitation token.
Usage:
tctl scoped tokens rm [<token>]
Arguments:
| Argument | Default | Description |
|---|---|---|
| token | no default (optional) | Token to delete |
tctl sso configure github
Configure GitHub auth connector.
Usage:
tctl sso configure github --teams-to-roles=org,team,role1,role2,... --id=ID --secret=SECRET [<flags>]
Flags:
| Flag | Default | Description |
|---|---|---|
--api-endpoint-url | https://api.github.com | API endpoint URL for GitHub instance. |
--display | no default | Sets the connector display name. |
--endpoint-url | https://github.com | Endpoint URL for GitHub instance. |
--id | no default | GitHub app client ID. |
-n, --name | github | Connector name. |
--[no-]ignore-missing-roles | false | Ignore missing roles referenced in --teams-to-roles. |
--redirect-url | no default | Authorization callback URL. |
-r, --teams-to-roles | no default | Sets teams-to-roles mapping using format 'organization,name,role1,role2,...'. Repeatable. |
--secret | no default | GitHub app client secret. |
tctl sso configure oidc
Configure OIDC auth connector, optionally using a preset. Available presets: [google gitlab okta].
Usage:
tctl sso configure oidc --claims-to-roles=name,value,role1,role2,... --secret=SECRET [<flags>]
Flags:
| Flag | Default | Description |
|---|---|---|
--acr | no default | Authentication Context Class Reference values. |
--display | no default | Sets the connector display name. |
--google-acc | no default | Google only. String containing Google service account credentials. |
--google-acc-uri | no default | Google only. URI pointing at service account credentials. Example: file:///var/lib/teleport/gworkspace-creds.json. |
--google-admin | no default | Google only. Email of a Google admin to impersonate. |
--google-id | no default | Shorthand for setting the --id flag to <GOOGLE_WORKSPACE_CLIENT_ID>.apps.googleusercontent.com |
--id | no default | OIDC app client ID. |
--issuer-url | no default | Issuer URL. |
-n, --name | no default | Connector name. Required, unless implied from preset. |
--[no-]google-legacy | false | Google only. Flag to select groups with direct membership filtered by domain (legacy behavior). Disabled by default. More info: https://goteleport.com/docs/enterprise/sso/google-workspace/#how-teleport-uses-google-workspace-apis |
--[no-]ignore-missing-roles | false | Ignore missing roles referenced in --claims-to-roles. |
-p, --preset | no default (one of: google, gitlab, okta) | Preset. |
--prompt | no default | Optional OIDC prompt. Example values: none, select_account, login, consent. |
--provider | no default | Sets the external identity provider type to enable IdP specific workarounds. Examples: ping, adfs, netiq, okta. |
-r, --claims-to-roles | no default | Sets claim-to-roles mapping using format 'claim_name,claim_value,role1,role2,...'. Repeatable. |
--redirect-url | no default | Authorization callback URL(s). Each repetition of the flag declares one redirectURL. |
--scope | no default | Scope specifies additional scopes set by provider. Each repetition of the flag declares one scope. Examples: email, groups, openid. |
--secret | no default | OIDC app client secret. |
tctl sso configure saml
Configure SAML auth connector, optionally using a preset. Available presets: [okta onelogin ad adfs].
Usage:
tctl sso configure saml --attributes-to-roles=ATTRIBUTES-TO-ROLES [<flags>]
Flags:
| Flag | Default | Description |
|---|---|---|
--acs | no default | AssertionConsumerService is a URL for assertion consumer service on the service provider (Teleport's side). |
--assertion-cert-file | no default | A file with cert used for securing SAML assertions. Must be used together with --assertion-key-file. |
--assertion-key-file | no default | A file with key used for securing SAML assertions. Must be used together with --assertion-cert-file. |
--audience | no default | Audience uniquely identifies our service provider. |
--cert | no default | Cert file with the IdP certificate PEM. IdP signs <Response> responses using this certificate. |
--display | no default | Sets the connector display name. |
-e, --entity-descriptor | no default | Set the Entity Descriptor. Valid values: file, URL, XML content. Supplies configuration parameters as single XML instead of individual elements. |
--issuer | no default | Issuer is the identity provider issuer. |
-n, --name | no default | Connector name. Required, unless implied from preset. |
--[no-]allow-idp-initiated | false | Allow the IdP to initiate the SSO flow. |
--[no-]ignore-missing-roles | false | Ignore missing roles referenced in --attributes-to-roles. |
-p, --preset | no default (one of: okta, onelogin, ad, adfs) | Preset. |
--provider | no default | Sets the external identity provider type. Examples: ping, adfs. |
-r, --attributes-to-roles | no default | Sets attribute-to-role mapping using format 'attr_name,attr_value,role1,role2,...'. Repeatable. |
--service-provider-issuer | no default | ServiceProviderIssuer is the issuer of the service provider (Teleport). |
--signing-cert-file | no default | A file with request certificate. Must be used together with --signing-key-file. |
--signing-key-file | no default | A file with request signing key. Must be used together with --signing-cert-file. |
--sso | no default | SSO is the URL of the identity provider's SSO service. |
tctl sso test
Perform end-to-end test of SSO flow using provided auth connector definition.
Usage:
tctl sso test [<flags>] [<filename>]
Flags:
| Flag | Default | Description |
|---|---|---|
--browser | no default | Set to 'none' to suppress browser opening on login. |
Arguments:
| Argument | Default | Description |
|---|---|---|
| filename | no default (optional) | Connector resource definition filename. Empty for stdin. |
tctl stable-unix-users ls
List the stable UNIX users currently persisted in the cluster.
Usage:
tctl stable-unix-users ls [<flags>]
Flags:
| Flag | Default | Description |
|---|---|---|
--format | text (one of: text, json, yaml) | Output format. |
tctl status
Report cluster status.
Usage:
tctl status
tctl terraform env
Obtain certificates and load them into environment variables. This creates a temporary MachineID bot.
Usage:
tctl terraform env [<flags>]
Flags:
| Flag | Default | Description |
|---|---|---|
--bot-ttl | 1h | Time-to-live of the Bot resource. The bot will be removed after this period. Defaults to [1h] |
--resource-prefix | tctl-terraform-env- | Resource prefix to use when creating the Terraform role and bots. Defaults to [tctl-terraform-env-] |
--role | no default | Role used by Terraform. The role must already exist in Teleport. When not specified, uses the default role "terraform-provider" |
tctl tokens add
Create a invitation token.
Usage:
tctl tokens add --type=TYPE [<flags>]
Flags:
| Flag | Default | Description |
|---|---|---|
--app-name | example-app | Name of the application to add |
--app-uri | http://localhost:8080 | URI of the application to add |
--db-name | no default | Name of the database to add |
--db-protocol | no default | Database protocol to use. Supported are: [postgres mysql mongodb oracle cockroachdb redis snowflake sqlserver cassandra elasticsearch opensearch dynamodb clickhouse clickhouse-http spanner] |
--db-uri | no default | Address the database is reachable at |
--format | no default (one of: text, json, yaml) | Output format. |
--labels | no default | Set token labels, e.g. env=prod,region=us-west |
--ttl | 30m0s | Set expiration time for token, default is 30 minutes |
--type | no default | Type(s) of token to add, e.g. --type=node,app,db,proxy,etc |
--value | no default | Override the default random generated token with a specified value |
tctl tokens configure-kube
Creates a token allowing workload from the Kubernetes cluster to join the Teleport cluster.
Usage:
tctl tokens configure-kube --service-account=SERVICE-ACCOUNT [<flags>]
Flags:
| Flag | Default | Description |
|---|---|---|
--bot | no default | Name of the bot that this token will grant access to. When set, creates a bot token. Overrides --type |
--cluster-name | no default | Name of the Kubernetes cluster. When not set, defaults to the context name. |
--context | no default | Kubernetes context to use. When not set, defaults to the active context. |
-f, --[no-]force | false | Force the token creation, even if the token already exists |
-j, --join-with | auto | Kubernetes joining type, possible values are 'oidc', 'jwks', and 'auto'. See https://goteleport.com/docs/reference/join-methods/#kubernetes-kubernetes for more details. |
-n, --namespace | teleport | Namespace of the Kubernetes Service Account using the token. For 'teleport-kube-agent' and 'tbot' Helm charts, this is the release namespace. |
-o, --out | ./values.yaml | Path of the output file. |
-s, --service-account | no default | Name of the Kubernetes Service Account using the token. For 'teleport-kube-agent' and 'tbot' Helm charts, this is the release name. |
--token-name | no default | Optional name of the created join token. When not set, default to '<CLUSTER_NAME>(-<BOT_NAME>)' |
--type | kube,app,discovery | Type(s) of token to add, e.g. --type=kube,app,db,discovery,proxy,etc |
--update-group | no default | Optional update group used for version detection and agent updater configuration |
tctl tokens ls
List node and user invitation tokens.
Usage:
tctl tokens ls [<flags>]
Flags:
| Flag | Default | Description |
|---|---|---|
--format | no default (one of: text, json, yaml) | Output format. |
--labels | no default | List of comma separated labels to filter by labels (e.g. key1=value1,key2=value2) |
--[no-]with-secrets | false | Do not redact join tokens |
tctl tokens rm
Delete/revoke an invitation token.
Usage:
tctl tokens rm [<token>]
Arguments:
| Argument | Default | Description |
|---|---|---|
| token | no default (optional) | Token to delete |
tctl top
Report diagnostic information.
Usage:
tctl top [<diag-addr>] [<refresh>]
Arguments:
| Argument | Default | Description |
|---|---|---|
| diag-addr | no default (optional) | Diagnostic HTTP URL |
| refresh | 5s (optional) | Refresh period |
tctl update
Update resource fields.
Usage:
tctl update [<flags>] [<resource type/resource name>]
Flags:
| Flag | Default | Description |
|---|---|---|
--set-labels | no default | Set labels |
--set-ttl | no default | Set TTL |
Arguments:
| Argument | Default | Description |
|---|---|---|
| resource type/resource name | no default (optional) | Resource to update |
| <resource type> Type of a resource [for example: rc] | ||
| <resource name> Resource name to update |
Example: $ tctl update rc/remote|
tctl users add
Generate a user invitation token [Teleport local users only].
Usage:
tctl users add --roles=ROLES [<flags>] <account>
Flags:
| Flag | Default | Description |
|---|---|---|
--aws-role-arns | no default | List of allowed AWS role ARNs for the new user |
--azure-identities | no default | List of allowed Azure identities for the new user |
--db-names | no default | List of allowed database names for the new user |
--db-roles | no default | List of database roles for automatic database user provisioning |
--db-users | no default | List of allowed database users for the new user |
--default-relay-addr | no default | Relay address that clients should use by default |
--gcp-service-accounts | no default | List of allowed GCP service accounts for the new user |
--host-user-gid | no default | GID for auto provisioned host users to use |
--host-user-uid | no default | UID for auto provisioned host users to use |
--kubernetes-groups | no default | List of allowed Kubernetes groups for the new user |
--kubernetes-users | no default | List of allowed Kubernetes users for the new user |
--logins | no default | List of allowed SSH logins for the new user |
--mcp-tools | no default | List of allowed MCP tools for the new user |
--roles | no default | List of roles for the new user to assume |
--ttl | 1h0m0s | Set expiration time for token, default is 1h0m0s, maximum is 48h0m0s |
--windows-logins | no default | List of allowed Windows logins for the new user |
Arguments:
| Argument | Default | Description |
|---|---|---|
| account | no default (required) | Teleport user account name |
tctl users ls
Lists all user accounts.
Usage:
tctl users ls
tctl users reset
Reset user password and generate a new token [Teleport local users only].
Usage:
tctl users reset [<flags>] <account>
Flags:
| Flag | Default | Description |
|---|---|---|
--ttl | 8h0m0s | Set expiration time for token, default is 8h0m0s, maximum is 24h0m0s |
Arguments:
| Argument | Default | Description |
|---|---|---|
| account | no default (required) | Teleport user account name |
tctl users rm
Deletes user accounts.
Usage:
tctl users rm <logins>
Arguments:
| Argument | Default | Description |
|---|---|---|
| logins | no default (required) | Comma-separated list of user logins to delete |
tctl users update
Update user account.
Usage:
tctl users update [<flags>] <account>
Flags:
| Flag | Default | Description |
|---|---|---|
--set-aws-role-arns | no default | List of allowed AWS role ARNs for the user, replaces current AWS role ARNs |
--set-azure-identities | no default | List of allowed Azure identities for the user, replaces current Azure identities |
--set-db-names | no default | List of allowed database names for the user, replaces current database names |
--set-db-roles | no default | List of allowed database roles for automatic database user provisioning, replaces current database roles |
--set-db-users | no default | List of allowed database users for the user, replaces current database users |
--set-default-relay-addr | no default | Relay address that clients should use by default. Value can be reset by providing an empty string |
--set-gcp-service-accounts | no default | List of allowed GCP service accounts for the user, replaces current service accounts |
--set-host-user-gid | no default | GID for auto provisioned host users to use. Value can be reset by providing an empty string |
--set-host-user-uid | no default | UID for auto provisioned host users to use. Value can be reset by providing an empty string |
--set-kubernetes-groups | no default | List of allowed Kubernetes groups for the user, replaces current Kubernetes groups |
--set-kubernetes-users | no default | List of allowed Kubernetes users for the user, replaces current Kubernetes users |
--set-logins | no default | List of allowed SSH logins for the user, replaces current logins |
--set-mcp-tools | no default | List of allowed MCP tools for the user, replaces current allowed MCP tools. |
--set-roles | no default | List of roles for the user to assume, replaces current roles |
--set-windows-logins | no default | List of allowed Windows logins for the user, replaces current Windows logins |
Arguments:
| Argument | Default | Description |
|---|---|---|
| account | no default (required) | Teleport user account name |
tctl version
Print the version of your tctl binary.
Usage:
tctl version
tctl workload-identity ls
List workload identity configurations.
Usage:
tctl workload-identity ls
tctl workload-identity revocations add
Create a new revocation.
Usage:
tctl workload-identity revocations add --serial=SERIAL --type=TYPE --reason=REASON [<flags>]
Flags:
| Flag | Default | Description |
|---|---|---|
--expires-at | no default | Time that the revocation should expire, usually this should match the expiry time of the credential. This should be specified using RFC3339 e.g '2024-02-05T15:04:00Z'. If unspecified, the time 1 week from now is used. |
--reason | no default | Reason for revocation. |
--serial | no default | Serial number of the certificate to revoke. |
--type | no default (one of: x509) | Type of credential to revoke (x509) |
tctl workload-identity revocations crl
Fetch the signed CRL for existing revocations.
Usage:
tctl workload-identity revocations crl [<flags>]
Flags:
| Flag | Default | Description |
|---|---|---|
--[no-]follow | false | Follow the stream of CRL updates. |
--out | no default | Path to write the CRL as a file to. If unspecified, STDOUT will be used. |
tctl workload-identity revocations ls
List revocations.
Usage:
tctl workload-identity revocations ls
tctl workload-identity revocations rm
Delete a revocation.
Usage:
tctl workload-identity revocations rm --serial=SERIAL --type=TYPE
Flags:
| Flag | Default | Description |
|---|---|---|
--serial | no default | Serial number of the certificate to remove the revocation for. |
--type | no default (one of: x509) | Type of credential to remove the revocation for (x509). |
tctl workload-identity rm
Delete a workload identity configuration.
Usage:
tctl workload-identity rm <name>
Arguments:
| Argument | Default | Description |
|---|---|---|
| name | no default (required) | Name of the workload identity configuration to delete. |
tctl workload-identity x509-issuer-overrides create
Create an issuer override from the given certificate chains.
Usage:
tctl workload-identity x509-issuer-overrides create [<flags>] <fullchain.pem>...
Flags:
| Flag | Default | Description |
|---|---|---|
-f, --[no-]force | false | Overwrite the existing override if it exists. |
--name | default | The name of the override resource to write. |
--[no-]dry-run | false | Print the workload_identity_x509_issuer_override that would have been created, without actually creating it. |
Arguments:
| Argument | Default | Description |
|---|---|---|
| fullchain.pem | no default (required) | PEM files containing an issuer and its optional chain each. |
tctl workload-identity x509-issuer-overrides sign-csrs
Sign CSRs with the SPIFFE X.509 CA keys.
Usage:
tctl workload-identity x509-issuer-overrides sign-csrs [<flags>]
Flags:
| Flag | Default | Description |
|---|---|---|
--creation-mode | same | How the attributes of the issuer are encoded in the CSR: "same", "empty". |
-f, --[no-]force | false | Attempt to sign as many CSRs as possible even in the presence of errors. |
Was this page helpful?