tctl CLI Reference — Teleport Cluster Admin Tool

tctl is the administrative CLI for Teleport cluster management. It lets cluster administrators manage users, roles, join tokens, certificate authorities, nodes, access requests, and Machine ID bots — either locally on an Auth Service host or remotely using a signed identity file.

tctl [<flags>] <command> [<args> ...]

tctl requires either local access to the Teleport Auth Service (via /etc/teleport.yaml) or a remote identity file created with tctl auth sign. Running it without proper authorization will result in an authentication error.

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.
`-i`, `--identity`	no default	Path to an identity file for remote auth connections.
`--mfa-mode`	`auto`	Preferred MFA mode: `auto`, `cross-platform`, `platform`, `sso`, `browser`.
`--[no-]insecure`	`false`	Do not verify the proxy TLS certificate (use with caution).
`-d`, `--[no-]debug`	`false`	Enable verbose logging to stderr.

Global Environment Variables

Variable	Default	Description
`TELEPORT_AUTH_SERVER`	no default	Attempts to connect to specific auth/proxy address(es) instead of local auth.
`TELEPORT_IDENTITY_FILE`	no default	Path to an identity file for remote connections.
`TELEPORT_MFA_MODE`	`auto`	Preferred MFA mode.

User Commands

`tctl users add`

Generate a user invitation token for a new local Teleport user.

tctl users add --roles=ROLES [<flags>] <account>

Flag	Default	Description
`--roles`	no default	List of roles for the new user to assume.
`--logins`	no default	List of allowed SSH logins for the new user.
`--ttl`	`1h0m0s`	Set expiration time for token (max 48h).
`--format`	`text`	Output format: `text`, `json`, `yaml`.
`--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.
`--db-users`	no default	List of allowed database users 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.
`--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.
`--gcp-service-accounts`	no default	List of allowed GCP service accounts for the new user.
`--host-user-uid`	no default	UID for auto provisioned host users to use.
`--host-user-gid`	no default	GID for auto provisioned host users to use.
`--windows-logins`	no default	List of allowed Windows logins for the new user.
`--mcp-tools`	no default	List of allowed MCP tools for the new user.
`--default-relay-addr`	no default	Relay address that clients should use by default.

Example:

# Add a new user with the 'dev' role
tctl users add --roles=dev alice

# Add a user with SSH logins
tctl users add --roles=devops --logins=ubuntu,ec2-user bob

`tctl users ls`

List all user accounts in the cluster.

tctl users ls [<flags>]

Flag	Default	Description
`--format`	`text`	Output format: `text`, `json`, `yaml`.

Example:

tctl users ls
tctl users ls --format=json

`tctl users rm`

Delete one or more user accounts.

tctl users rm <logins>

Example:

# Delete a single user
tctl users rm alice

# Delete multiple users (comma-separated)
tctl users rm alice,bob

`tctl users reset`

Reset a user’s password and generate a new invitation token.

tctl users reset [<flags>] <account>

Flag	Default	Description
`--ttl`	`8h0m0s`	Set expiration time for token (max 24h).
`--format`	`text`	Output format: `text`, `json`, `yaml`.

Example:

tctl users reset alice

Role Commands

Roles are managed using the generic tctl get, tctl create, and tctl rm resource commands.

`tctl get roles`

Retrieve and display role definitions.

tctl get roles [<flags>]
tctl get roles/<rolename>

Flag	Default	Description
`--format`	`yaml`	Output format: `yaml`, `json`, `text`.
`--[no-]with-secrets`	`false`	Include secrets in output.

Example:

# List all roles
tctl get roles

# Get a specific role in YAML format
tctl get roles/dev-access

# Get in JSON
tctl get roles/dev-access --format=json

`tctl create` (roles)

Create or update a role from a YAML file.

tctl create [<flags>] [<filename>]

Flag	Default	Description
`-f`, `--[no-]force`	`false`	Overwrite the resource if it already exists.

Example:

# Create a role from a YAML file
tctl create role.yaml

# Force-overwrite an existing role
tctl create -f role.yaml

Sample role YAML:

kind: role
version: v7
metadata:
  name: dev-access
spec:
  allow:
    logins: ['ubuntu', 'ec2-user']
    node_labels:
      env: dev
  deny: {}

`tctl rm` (roles)

Delete a role.

tctl rm roles/<rolename>

Example:

tctl rm roles/dev-access

Token Commands

`tctl tokens add`

Create an invitation token for joining nodes, proxies, databases, or apps.

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

Flag	Default	Description
`--type`	no default	Type(s) of token to add, e.g. `--type=node,app,db,proxy`.
`--ttl`	`30m0s`	Set expiration time for token (default 30 minutes).
`--value`	no default	Override the default random generated token with a specified value.
`--format`	no default	Output format: `text`, `json`, `yaml`.
`--labels`	no default	Set token labels, e.g. `env=prod,region=us-west`.

Example:

# Create a node join token
tctl tokens add --type=node

# Create a token valid for 1 hour for a database agent
tctl tokens add --type=db --ttl=1h

# Create a token with a custom value
tctl tokens add --type=node --value=my-secret-token

`tctl tokens ls`

List existing invitation tokens.

tctl tokens ls [<flags>]

Flag	Default	Description
`--format`	no default	Output format: `text`, `json`, `yaml`.
`--labels`	no default	Filter by labels.
`--[no-]with-secrets`	`false`	Do not redact join tokens (show full values).

Example:

tctl tokens ls
tctl tokens ls --format=json

`tctl tokens rm`

Delete/revoke an invitation token.

tctl tokens rm [<token>]

Example:

tctl tokens rm abc123tokenvalue

Auth Commands

`tctl auth sign`

Create an identity file for a given user (used for remote tctl access or CI/CD pipelines).

tctl auth sign --out=OUT [<flags>]

Flag	Default	Description
`-o`, `--out`	no default	Identity output path (required).
`--user`	no default	Teleport user name.
`--host`	no default	Teleport host name.
`--ttl`	`12h0m0s`	TTL for the generated certificate.
`--format`	`file`	Identity format: `file`, `openssh`, `tls`, `kubernetes`, `db`, `windows`, `mongodb`, `cockroachdb`, `redis`, `snowflake`, `elasticsearch`, `cassandra`, `scylla`, `oracle`.
`--proxy`	no default	Proxy address (used when format is `kubernetes`).
`--kube-cluster-name`	no default	Kubernetes cluster name when format is `kubernetes`.
`--leaf-cluster`	no default	Leaf cluster to generate identity file for when format is `kubernetes`.
`--app-name`	no default	Application to generate identity file for. Mutually exclusive with `--db-service`.
`--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.
`--db-name`	no default	Database name placed on the identity file. Only used when `--db-service` is set.
`--compat`	no default	OpenSSH compatibility flag.
`--[no-]overwrite`	`false`	Whether to overwrite existing destination files.
`--[no-]tar`	`false`	Create a tarball of the resulting certificates and stream to stdout.

Example:

# Sign an identity for a user
tctl auth sign --user=alice --out=/tmp/alice-identity

# Sign a kubeconfig for a Kubernetes cluster
tctl auth sign --user=alice --format=kubernetes \
  --kube-cluster-name=my-cluster --out=kubeconfig

# Sign a certificate with a 24-hour TTL
tctl auth sign --user=ci-bot --ttl=24h --out=/tmp/ci-identity

`tctl auth export`

Export public cluster CA certificates.

tctl auth export [<flags>]

Flag	Default	Description
`--type`	no default	Certificate type: `user`, `host`, `tls-host`, `tls-user`, `db`, `openssh`, etc.
`--fingerprint`	no default	Filter by CA fingerprint.
`--out`	no default	Write exported authorities to files with the given path prefix.
`--[no-]keys`	`false`	If set, also print private keys.

Example:

# Export host CA
tctl auth export --type=tls-host

# Export user CA
tctl auth export --type=user

Node Commands

`tctl nodes ls`

List all active SSH nodes in the cluster.

tctl nodes ls [<flags>] [<labels>]

Flag	Default	Description
`--format`	`text`	Output format: `text`, `json`, `yaml`.
`--search`	no default	Search keywords.
`--query`	no default	Predicate language query.
`-v`, `--[no-]verbose`	`false`	Verbose table output.

Example:

tctl nodes ls
tctl nodes ls env=production
tctl nodes ls --format=json

`tctl nodes add`

Generate a node invitation token.

tctl nodes add [<flags>]

Flag	Default	Description
`--roles`	`node`	Comma-separated roles for the new node.
`--ttl`	`30m0s`	Time to live for the generated token.
`--token`	no default	Override the generated token with a specified value.
`--format`	`text`	Output format: `text`, `json`, `yaml`.

Example:

tctl nodes add
tctl nodes add --ttl=1h

Access Request Commands

`tctl requests ls`

Show active Access Requests.

tctl requests ls [<flags>]

Flag	Default	Description
`--format`	`text`	Output format: `text`, `json`, `yaml`.
`--sort-index`	`created`	Sort field: `created` or `state`.
`--sort-order`	`descending`	Sort order: `ascending` or `descending`.

Example:

tctl requests ls
tctl requests ls --format=json

`tctl requests approve`

Approve a pending Access Request.

tctl requests approve [<flags>] <request-id>

Flag	Default	Description
`--reason`	no default	Optional reason message.
`--roles`	no default	Override requested roles.
`--annotations`	no default	Resolution attributes as `key=val[,...]`.
`--assume-start-time`	no default	Sets when roles can be assumed (RFC3339).
`--delegator`	no default	Optional delegating identity.

Example:

tctl requests approve --reason="Verified and approved" abc123-request-id

`tctl requests deny`

Deny a pending Access Request.

tctl requests deny [<flags>] <request-id>

Flag	Default	Description
`--reason`	no default	Optional reason message.
`--annotations`	no default	Resolution annotations.
`--delegator`	no default	Optional delegating identity.

Example:

tctl requests deny --reason="Outside the change window" abc123-request-id

`tctl requests review`

Review an Access Request.

tctl requests review --author=AUTHOR [<flags>] <request-id>

Flag	Default	Description
`--author`	no default	Username of reviewer (required).
`--[no-]approve`	`false`	Review proposes approval.
`--[no-]deny`	`false`	Review proposes denial.

Example:

tctl requests review --author=admin --approve abc123-request-id

Bot Commands

Bots are Machine ID agents that programmatically issue short-lived certificates.

`tctl bots add`

Add a new bot to the cluster.

tctl bots add [<flags>] <name>

Flag	Default	Description
`--roles`	no default	Roles the bot is able to assume.
`--logins`	no default	List of allowed SSH logins for the bot user.
`--ttl`	`1h0m0s`	TTL for the bot join token.
`--token`	no default	Specify a token to use; if unset, one is generated.
`--format`	`text`	Output format: `text`, `json`, `yaml`.
`--max-session-ttl`	no default	Set a max session TTL for the bot’s internal identity (12h default, 168h maximum).
`--initial-public-key`	no default	Use the given initial public key in SSH authorized_keys format. Not compatible with `--token` or `--legacy`.
`--[no-]legacy`	`false`	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 for the bound keypair token. Must be greater than 1.
`--recovery-mode`	`standard`	Override the recovery mode for the bound keypair token: `standard`, `relaxed`, `insecure`.
`--registration-secret`	no default	Sets a registration secret for the bound keypair token.

Example:

# Add a bot with the 'ci-reader' role
tctl bots add --roles=ci-reader ci-bot

# Add a bot with a custom token TTL
tctl bots add --roles=deployer --ttl=4h deploy-bot

`tctl bots ls`

List all Machine ID bots registered with the cluster.

tctl bots ls [<flags>]

Flag	Default	Description
`--format`	`text`	Output format: `text`, `json`, `yaml`.

Example:

tctl bots ls

`tctl bots rm`

Permanently remove a bot from the cluster.

tctl bots rm <name>

Example:

tctl bots rm ci-bot

Resource CRUD

tctl provides generic resource management commands that work with any Teleport resource kind.

`tctl get`

Print a YAML (or JSON) declaration of any Teleport resource.

tctl get [<flags>] <resources> [<id>]

Examples:

tctl get roles
tctl get users/alice
tctl get nodes
tctl get cert_authority

`tctl create`

Create or update a resource from a YAML file.

tctl create [<flags>] [<filename>]

tctl create -f my-role.yaml

`tctl rm`

Delete a resource by type and name.

tctl rm <resource-type>/<resource-name>

tctl rm roles/dev-access
tctl rm users/alice
tctl rm tokens/abc123

`tctl edit`

Open a resource in your editor for interactive editing.

tctl edit <resource-type>/<resource-name>

tctl edit roles/dev-access

Use tctl status to display a summary of the cluster’s health and CA information — helpful for verifying connectivity before running other admin commands.

CLI Reference

Configuration & API

tctl CLI Reference — Teleport Cluster Admin Tool

Global Flags

Global Environment Variables

User Commands

`tctl users add`

`tctl users ls`

`tctl users rm`

`tctl users reset`

Role Commands

`tctl get roles`

`tctl create` (roles)

`tctl rm` (roles)

Token Commands

`tctl tokens add`

`tctl tokens ls`

`tctl tokens rm`

Auth Commands

`tctl auth sign`

`tctl auth export`

Node Commands

`tctl nodes ls`

`tctl nodes add`

Access Request Commands

`tctl requests ls`

`tctl requests approve`

`tctl requests deny`

`tctl requests review`

Bot Commands

`tctl bots add`

`tctl bots ls`

`tctl bots rm`

Resource CRUD

`tctl get`

`tctl create`

`tctl rm`

`tctl edit`

Build docs developers (and LLMs) love

CLI Reference

Configuration & API

Documentation Index

​Global Flags

​Global Environment Variables

​User Commands

​tctl users add

​tctl users ls

​tctl users rm

​tctl users reset

​Role Commands

​tctl get roles

​tctl create (roles)

​tctl rm (roles)

​Token Commands

​tctl tokens add

​tctl tokens ls

​tctl tokens rm

​Auth Commands

​tctl auth sign

​tctl auth export

​Node Commands

​tctl nodes ls

​tctl nodes add

​Access Request Commands

​tctl requests ls

​tctl requests approve

​tctl requests deny

​tctl requests review

​Bot Commands

​tctl bots add

​tctl bots ls

​tctl bots rm

​Resource CRUD

​tctl get

​tctl create

​tctl rm

​tctl edit

Build docs developers (and LLMs) love

Global Flags

Global Environment Variables

User Commands

`tctl users add`

`tctl users ls`

`tctl users rm`

`tctl users reset`

Role Commands

`tctl get roles`

`tctl create` (roles)

`tctl rm` (roles)

Token Commands

`tctl tokens add`

`tctl tokens ls`

`tctl tokens rm`

Auth Commands

`tctl auth sign`

`tctl auth export`

Node Commands

`tctl nodes ls`

`tctl nodes add`

Access Request Commands

`tctl requests ls`

`tctl requests approve`

`tctl requests deny`

`tctl requests review`

Bot Commands

`tctl bots add`

`tctl bots ls`

`tctl bots rm`

Resource CRUD

`tctl get`

`tctl create`

`tctl rm`

`tctl edit`