teleport/docs/pages/setup/reference/cli.mdx

---
title: Teleport CLI Reference
description: The detailed guide and reference documentation for Teleport Command Line Interface (CLI) tools.
h1: Command Line (CLI) Reference
---

Teleport is made up of three CLI tools.

- [teleport](#teleport): The Teleport daemon that runs the Teleport Service, and acts as a daemon on a node allowing SSH connections.
- [tsh](#tsh): A tool that lets end users interact with Teleport nodes. This replaces `ssh`.
- [tctl](#tctl): An administrative tool that can configure Teleport Auth Service.

(!docs/pages/includes/permission-warning.mdx!)

(!docs/pages/includes/backup-warning.mdx!)

## teleport

The Teleport daemon is called `teleport`. It can be configured to run one or
more "roles" with the `--roles` flags. The arguments to `--roles` correspond to
the following services.

| Service | Role Name | Description |
| - | - | - |
| [Node](../../architecture/nodes.mdx) | `node` | Runs a daemon on a node which allows SSH connections from authenticated clients. |
| [Auth](../../architecture/authentication.mdx) | `auth` | Authenticates nodes and users who want access to Teleport Nodes or information about the cluster. |
| [Proxy](../../architecture/proxy.mdx) | `proxy` | The gateway that clients use to connect to the Auth or Node Services. |
| [App](../../application-access/introduction.mdx) | `app` | Runs a daemon on a node which provides access to applications using an SSH reverse tunnel. |
| [Kube](../../kubernetes-access/introduction.mdx) | `kube` | Runs the Teleport node as a kubernetes access server. |
| [DB](../../database-access/reference.mdx) | `db` | Indicates that the Teleport node should be run as a database access server. |
| [Trusted Cluster](../../setup/admin/trustedclusters.mdx) | `trusted_cluster` | The node will support a leaf cluster used to connect to another Teleport cluster. |

### teleport start

#### Flags

| Name | Default Value(s) | Allowed Value(s) | Description |
| - | - | - | - |
| `-d, --debug` | none | none | enable verbose logging to stderr |
| `--insecure-no-tls` | `false` | `true` or `false` | Tells proxy to not generate default self-signed TLS certificates. This is useful when running Teleport on kubernetes (behind reverse proxy) or behind things like AWS ELBs, GCP LBs or Azure Load Balancers where SSL termination is provided externally. |
| `-r, --roles` | `proxy,node,auth` | **string** comma-separated list of `proxy, auth, node, db, app` or `windowsdesktop` | start listed services/roles. These roles are explained in the [Teleport Architecture](../../architecture/overview.mdx) document. |
| `--pid-file` | none | **string** filepath | create a PID file at the path |
| `--advertise-ip` | none | **string** IP | advertise IP to clients, often used behind NAT |
| `-l, --listen-ip` | `0.0.0.0` | [**net. IP**](https://golang.org/pkg/net/#IP) | binds services to IP |
| `--auth-server` | none | **string** IP | proxy attempts to connect to a specified auth server instead of local auth, disables `--roles=auth` if set |
| `--token` | none | **string** | set invitation token to register with an auth server on start, used once and ignored afterwards. Obtain it by running `tctl nodes add` on the auth server.*We recommend to use tools like `pwgen` to generate sufficiently random tokens of 32+ byte length.* |
| `--ca-pin` | none | **string** `sha256:<hash>` | set CA pin to validate the Auth Server. Generated by `tctl status` |
| `--nodename` | `hostname` command on the machine | **string** | assigns an alternative name for the node which can be used by clients to login. By default it's equal to the value returned by |
| `-c, --config` | `/etc/teleport.yaml` | **string** `.yaml` filepath | starts services with config specified in the YAML file, overrides CLI flags if set |
| `--bootstrap` | none | **string** `.yaml` filepath | bootstrap configured YAML resources {/* TODO link how to configure this file */} |
| `--labels` | none | **string** comma-separated list | assigns a set of labels to a node, for example env=dev,app=web. See the explanation of labeling mechanism in the [Labeling Nodes](../admin/labels.mdx) section. |
| `--insecure` | none | none | disable certificate validation on Proxy Service, validation still occurs on Auth Service. |
| `--fips` | none | none | start Teleport in FedRAMP/FIPS 140-2 mode. |
| `--diag-addr` | none | none | Enable diagnostic endpoints |
| `--permit-user-env` | none | none | flag reads in environment variables from `~/.tsh/environment` when creating a session. |
| `--app-name` | none | none | Name of the application to start |
| `--app-uri` | none | none | Internal address of the application to proxy |
| `--app-public-addr` | none | none | Public address fo the application to proxy |

#### Examples

```
# By default without any configuration, teleport starts running as a single-node
# cluster. It's the equivalent of running with --roles=node,proxy,auth
sudo teleport start

# Starts a node named 'db' running in strictly SSH mode role, joining the cluster
# serviced by the auth server running on 10.1.0.1
sudo teleport start --roles=node --auth-server=10.1.0.1 --token=xyz --nodename=db

# Same as the above, but the node runs with db=master label and can be connected
# to using that label in addition to its name.
sudo teleport start --roles=node --auth-server=10.1.0.1 --labels=db=master

# Starts an app server that proxies the application "example-app" running at http://localhost:8080.
sudo teleport start --roles=app --token=xyz --auth-server=proxy.example.com:3080 \
    --app-name="example-app" \
    --app-uri="http://localhost:8080" \
    --labels=group=dev
```

### teleport status

Shows the status of a Teleport connection:

```code
$ teleport status
```

This command is only available from inside of a recorded SSH session.

### teleport configure

Dumps a **sample** configuration file in YAML format into
standard output:

```code
$ teleport configure
```

<Admonition title="warning" type="Warning">
  **Caution**: This sample config is *not* the default config and should be used
for reference only.

  View [Config Reference](./config.mdx) for all YAML configuration options.
</Admonition>

### teleport version

Shows the release version:

```code
$ teleport version
```

### teleport help

Displays help options for `teleport`:

```code
$ teleport help
```

And, for its subcommands:

```code
$ teleport help <subcommand>
```

## tsh

`tsh` is a CLI client used by Teleport Users. It allows users to interact with
current and past sessions on the cluster, copy files to and from nodes, and list
information about the cluster.

### tsh Global Flags

| Name | Default Value(s) | Allowed Value(s) | Description |
| - | - | - | - |
| `-l, --login` | none | an identity name | the login identity that the Teleport User should use |
| `--proxy` | none | `host:https_port[,ssh_proxy_port]` | set SSH proxy address |
| `--user` | `$USER` | none | the Teleport User name |
| `--ttl` | none | relative duration like 5s, 2m, or 3h | set time to live for a SSH session, session ttl unrestricted if unset {/* TODO Check this */} |
| `-i, --identity` | none | **string** filepath | Identity file |
| `--cert-format` | `file` | `file` or `openssh` | SSH certificate format |
| `--insecure` | none | none | Do not verify server's certificate and host name. Use only in test environments |
| `--auth` | `local` | any defined [authentication connector](./authentication.mdx) | Specify the type of authentication connector to use. |
| `--skip-version-check` | none | none | Skip version checking between server and client. |
| `-d, --debug` | none | none | Verbose logging to stdout |
| `-J, --jumphost` | none | A jump host | SSH jumphost |

### tsh help

Prints help:

```code
$ tsh help
```

### tsh version

Prints client version:

```code
$ tsh version
```

### tsh ssh

Run shell or execute a command on a remote SSH node:

```code
$ tsh ssh [<flags>] <[user@]host> [<command>...]
```

#### Arguments

`<[user@]host> [<command>...]`

- `user` The login identity to use on the remote host. If `[user]` is not specified the user defaults to `$USER` or can be set with `--user`. If the flag `--user` and positional argument `[user]` are specified the arg `[user]` takes precedence.
- `host` A `nodename` of a cluster node or a
- `command` The command to execute on a remote host.

#### Flags

| Name | Default Value(s) | Allowed Value(s) | Description |
| - | - | - | - |
| `-p, --port` | none | port | SSH port on a remote host |
| `-A, --forward-agent` | none | none | Forward agent to target node like `ssh -A` |
| `-L, --forward` | none | none | Forward localhost connections to remote server |
| `-D, --dynamic-forward` | none | none | Forward localhost connections to remote server using SOCKS5 |
| `-N, -no-remote-exec` | none | none | Don't execute remote command, useful for port forwarding |
| `--local` | none | | Execute command on localhost after connecting to SSH node |
| `-t, --tty` | `file` | | Allocate TTY |
| `--cluster` | none | | Specify the cluster to connect |
| `-o, --option` | `local` | | OpenSSH options in the format used in the configuration file |
| `--enable-escape-sequences` | | | Enable support for SSH escape sequences. Type `~?` during an SSH session to list supported sequences. |
| `--no-use-local-ssh-agent` | | | Do not load generated SSH certificates into the local ssh-agent (specified via `$SSH_AUTH_SOCK`). Useful when using `gpg-agent` or Yubikeys. You can also set the `TELEPORT_USE_LOCAL_SSH_AGENT` environment variable to `false` (default `true`) |

#### [Global Flags](#tsh-global-flags)

These flags are available for all commands `--login, --proxy, --user, --ttl, --identity, --cert-format, --insecure, --auth, --skip-version-check, --debug, --jumphost`.
Run `tsh help <subcommand>` or see the [Global Flags Section](#tsh-global-flags)

#### Examples

```code
# Log in to node `grav-00` as OS User `root` with Teleport User `teleport`
$ tsh ssh --proxy proxy.example.com --user teleport -d root@grav-00
# `tsh ssh` takes the same arguments as OpenSSH client:
$ tsh ssh -o ForwardAgent=yes root@grav-00
$ tsh ssh -o AddKeysToAgent=yes root@grav-00
```

### tsh config

Generates OpenSSH configuration to use currently logged in teleport
as a bastion host.

```code
$ tsh config
```

#### Examples

```code
# Print OpenSSH config file to console
$ tsh config

# Append Teleport configuration to ssh config
$ tsh config >> ~/.ssh/config
```

### tsh apps ls

List all available applications:

```code
$ tsh apps ls
```

### tsh join

Joins an active session:

```code
$ tsh join [<flags>] <session-id>
```

#### Arguments

`<session-id>`

- `session-id` The UUID of an active Teleport Session obtained by `teleport status` within
  the session.

#### Flags

| Name | Default Value(s) | Allowed Value(s) | Description |
| - | - | - | - |
| `--cluster` | none | a cluster_name | Specify the cluster to connect |

#### [Global Flags](#tsh-global-flags)

These flags are available for all commands `--login, --proxy, --user, --ttl, --identity, --cert-format, --insecure, --auth, --skip-version-check, --debug, --jumphost`.
Run `tsh help <subcommand>` or see the [Global Flags Section](#tsh-global-flags)

#### Examples

```code
# join session using teleport user joe as ec2-user
$ tsh --user=joe --login=ec2-user join <session-id>
```

### tsh play

Plays back a prior session:

```code
$ tsh play [<flags>] <session-id>
```

#### Arguments

`<session-id>`

- `session-id` The UUID of a past Teleport Session obtained by `teleport status` within
  the session or from the Web UI.

#### Flags

| Name | Default Value(s) | Allowed Value(s) | Description |
| - | - | - | - |
| `--cluster` | none | a cluster_name | Specify the cluster to connect |
| `--format`  | `pty`  | json, pty | Format for playback |

#### [Global Flags](#tsh-global-flags)

These flags are available for all commands `--login, --proxy, --user, --ttl, --identity, --cert-format, --insecure, --auth, --skip-version-check, --debug, --jumphost, --format`.
Run `tsh help <subcommand>` or see the [Global Flags Section](#tsh-global-flags)

#### Examples

```code
$ tsh --proxy proxy.example.com play <session-id>

# Playing back a session using pty format using a downloaded session recording.
$ tsh play --format=pty 1fe153d1-ce8b-4ef4-9908-6539457ba4ad.tar

# Playing back a session in json format using jq to filter on events
$ tsh play --format=json ~/play/0c0b81ed-91a9-4a2a-8d7c-7495891a6ca0.tar | jq '.event
```

### tsh proxy app

Starts a local TLS proxy for Application Access connections.
You can use this proxy to connect to an application repeatedly after a single login to your Teleport cluster,
which is especially useful for interacting with an application via a CLI.

```code
$ tsh proxy app [<flags>] <app>
```

#### Arguments
`<app>`

- `app` The name of the application to start the local proxy for. To see a list of available applications, run `tsh apps ls`.

#### Flags

| Name | Default Value(s) | Allowed Value(s) | Description |
| - | - | - | - |
| `--port` | none | port number | Specify the source port for the local proxy |

#### [Global Flags](#tsh-global-flags)

These flags are available for all commands `--login, --proxy, --user, --ttl, --identity, --cert-format, --insecure, --auth, --skip-version-check, --debug, --jumphost, --format`.
Run `tsh help <subcommand>` or see the [Global Flags Section](#tsh-global-flags)

#### Examples
```code
$ tsh proxy app <app>

# Proxy a connection to grafana on local port 10700
$ tsh proxy --port 10700 app grafana &
# Proxying connections to grafana on 127.0.0.1:10700
$ curl http://127.0.0.1:10700/api/users
```

### tsh scp

Copies files from source to dest:

```code
$ tsh scp [<flags>] <source>... <dest>
```

{/* TODO Confirm which flags are supported and whether supports multiple sources */}

#### Arguments

- `<source>` - filepath to copy
- `<dest>` - target destination

#### Flags

| Name | Default Value(s) | Allowed Value(s) | Description |
| - | - | - | - |
| `--cluster` | none | a cluster_name | Specify the cluster to connect |
| `-r, --recursive` | none | none | Recursive copy of subdirectories |
| `-P, --port` | none | port number | Port to connect to on the remote host |
| `-q, --quiet` | none | none | Quiet mode |

#### [Global Flags](#tsh-global-flags)

These flags are available for all commands `--login, --proxy, --user, --ttl, --identity, --cert-format, --insecure, --auth, --skip-version, --debug, --jumphost`.
Run `tsh help <subcommand>` or see the [Global Flags Section](#tsh-global-flags)

#### Examples

```code
$ tsh --proxy=proxy.example.com scp -P example.txt user@host:/destination/dir
```

### tsh ls

List cluster nodes:

```code
$ tsh ls [<flags>] [<label>]
```

{/* TODO: label? or labels? seems like it only supports one label at a time */}

#### Arguments

- `<label>` - `key=value` label to filer nodes by

#### Flags

| Name | Default Value(s) | Allowed Value(s) | Description |
| - | - | - | - |
| `-v, --verbose` | none | none | also print Node ID |

#### [Global Flags](#tsh-global-flags)

These flags are available for all commands `--login, --proxy, --user, --ttl, --identity, --cert-format, --insecure, --auth, --skip-version, --debug, --jumphost`.
Run `tsh help <subcommand>` or see the [Global Flags Section](#tsh-global-flags)

#### Examples

```code
$ tsh ls

# Node Name Address            Labels
# --------- ------------------ ------
# grav-00   10.164.0.0:3022    os:linux
# grav-01   10.156.0.2:3022    os:linux
# grav-02   10.156.0.7:3022    os:osx

$ tsh ls -v

# Node Name Node ID                              Address            Labels
# --------- ------------------------------------ ------------------ ------
# grav-00   52e3e46a-372f-494b-bdd9-a1d25b9d6dec 10.164.0.0:3022    os:linux
# grav-01   73d86fc7-7c4b-42e3-9a5f-c46e177a29e8 10.156.0.2:3022    os:linux
# grav-02  24503590-e8ae-4a0a-ad7a-dd1865c04e30 10.156.0.7:3022     os:osx

# Only show nodes with os label set to 'osx':
$ tsh ls os=osx

# Node Name Address            Labels
# --------- ------------------ ------
# grav-02   10.156.0.7:3022    os:osx
```

### tsh kube ls

List Kubernetes clusters:

```code
$ tsh kube ls
```

#### Examples

```code
$ tsh kube ls

# Kube Cluster Name                     Selected
# ------------------------------------- --------
# gke_bens-demos_us-central1-c_gks-demo *
# microk8s
```

### tsh clusters

```code
$ tsh clusters [<flags>]
```

#### Flags

| Name | Default Value(s) | Allowed Value(s) | Description |
| - | - | - | - |
| `-q, --quiet` | none | none | no headers in output |

#### [Global Flags](#tsh-global-flags)

These flags are available for all commands `--login, --proxy, --user, --ttl, --identity, --cert-format, --insecure, --auth, --skip-version, --debug, --jumphost`.
Run `tsh help <subcommand>` or see the [Global Flags Section](#tsh-global-flags)

#### Examples

```code
$ tsh clusters

# Cluster Name Status
# ------------ ------
# staging          online
# production       offline

$ tsh clusters --quiet

# staging online
# production offline
```

### tsh login

Logs in to the cluster. When `tsh` logs in, the auto-expiring key is stored in
`~/.tsh` and is valid for 12 hours by default unless you specify another
interval via `--ttl` flag (capped by the server-side configuration).

```code
$ tsh login [<flags>] [<cluster>]
```

#### Arguments

- `<cluster>` - the name of the cluster,  see [Trusted Cluster](../../setup/admin/trustedclusters.mdx#introduction) for more information.

#### Flags

| Name | Default Value(s) | Allowed Value(s) | Description |
| - | - | - | - |
| `--bind-addr` | none | host:port | Address in the form of host:port to bind to for login command webhook |
| `-o, --out` | none | filepath | Identity output filepath |
| `--format` | `file` | `file`, `openssh` or `kubernetes` | Identity format: file, openssh (for OpenSSH compatibility) or kubernetes (for kubeconfig) |
| `--browser` | none | `none` | Set to 'none' to suppress opening system default browser for `tsh login` commands |
| `--request-roles` | none | | Request one or more extra roles |
| `--request-reason` | none | | Reason for requesting additional roles |
| `--request-nowait` | none | | Finish without waiting for request resolution |
| `--request-id` | none | | Login with the roles requested in the given request |
| `--no-use-local-ssh-agent` | | | Do not load generated SSH certificates into the local ssh-agent (specified via `$SSH_AUTH_SOCK`). Useful when using `gpg-agent` or Yubikeys. You can also set the `TELEPORT_USE_LOCAL_SSH_AGENT` environment variable to `false` (default `true`) |

#### [Global Flags](#tsh-global-flags)

These flags are available for all commands `--login, --proxy, --user, --ttl, --identity, --cert-format, --insecure, --auth, --skip-version-check, --debug, --jumphost`.
Run `tsh help <subcommand>` or see the [Global Flags Section](#tsh-global-flags)

#### Examples

*The proxy endpoint can take a https and ssh port in this format `host:https_port[,ssh_proxy_port]`*

```code
# Try Toboth ports 443 and 3080 for https
$ tsh --proxy=proxy.example.com login

# Use ports 8080 and 8023 for https and SSH proxy:
$ tsh --proxy=proxy.example.com:8080,8023 login

# Use port 8080 and 3023 (default) for SSH proxy:
$ tsh --proxy=proxy.example.com:8080 login

# Use port 23 as custom SSH port, keep HTTPS proxy port as default
$ tsh --proxy=work.example.com:,23 login

# Login and select cluster "two":
$ tsh --proxy=proxy.example.com login two

# Select cluster "two" using existing credentials and proxy:
$ tsh login two

# Login to the  cluster with a very short-lived certificate
$ tsh --ttl=1 login

# Login using the local Teleport 'admin' user:
$ tsh --proxy=proxy.example.com --auth=local --user=admin login

# Login using Github as an SSO provider, assuming the Github connector is called "github"
$ tsh --proxy=proxy.example.com --auth=github --user=admin login

# Suppress the opening of the system default browser for external provider logins
$ tsh --proxy=proxy.example.com --browser=none

# Login to cluster and output a local kubeconfig
$ tsh login --proxy=proxy.example.com --format=kubernetes -o kubeconfig

# Request access to a cluster.
$ tsh login --proxy=proxy.example.com --request-reason="I need to run a debug script on production"
```

### tsh kube login

Log into a Kubernetes cluster. Discover connected clusters by using [`tsh kube ls`](cli.mdx#tsh-kube-ls).

```code
$ tsh kube login <kube-cluster>
```

```code
# tsh kube login to k8s cluster (gke_bens-demos_us-central1-c_gks-demo)
$ tsh kube login gke_bens-demos_us-central1-c_gks-demo
# Logged into kubernetes cluster "gke_bens-demos_us-central1-c_gks-demo"

# On login, kubeconfig is pointed at the first cluster (alphabetically)
$ kubectl config current-context
# aws-gke_bens-demos_us-central1-c_gks-demo

# But all clusters are populated as contexts
$ kubectl config get-contexts

# CURRENT   NAME                                        CLUSTER                       AUTHINFO                                    NAMESPACE
# *         aws-gke_bens-demos_us-central1-c_gks-demo   aws                           aws-gke_bens-demos_us-central1-c_gks-demo
#          aws-microk8s                                aws                           aws-microk8s
```

### tsh logout

Deletes the client's cluster certificate:

```code
$ tsh logout
```

### tsh status

Display the list of proxy servers and retrieved certificates:

```code
$ tsh status
```

#### Examples

```code
$ tsh status

# > Profile URL:  https://proxy.example.com:3080
#   Logged in as:       benarent
#   Cluster:            aws
#   Roles:              admin*
#   Logins:             benarent, root, ec2-user, ubunutu
#   Kubernetes:         enabled
#   Kubernetes cluster: "gke_bens-demos_us-central1-c_gks-demo"
#   Kubernetes groups:  system:masters
#  Valid until:        2020-11-21 01:50:23 -0800 PST [valid for 11h52m0s]
#  Extensions:         permit-agent-forwarding, permit-port-forwarding, permit-pty
```

### tsh mfa ls

List all registered Multi-Factor Authentication (MFA) devices:

```code
$ tsh mfa ls
```

### tsh mfa add

Register a new Multi-Factor Authentication (MFA) device:

```code
$ tsh mfa add
```

#### Examples

```code
$ tsh mfa add

# Choose device type [TOTP, WEBAUTHN]: webauthn
# Enter device name: desktop yubikey
# Tap any *registered* security key
# Tap your *new* security key
# MFA device "desktop yubikey" added.
```

```code
$ tsh mfa add

# Choose device type [TOTP, WEBAUTHN]: totp
# Enter device name: android
# Tap any *registered* security key
# Open your TOTP app and create a new manual entry with these fields:
# Name: awly@example.com:3080
# Issuer: Teleport
# Algorithm: SHA1
# Number of digits: 6
# Period: 30s
# Secret: 6DHDR7GWA7ZKLLWEWRIF55WXJKZ52UVJ

# Once created, enter an OTP code generated by the app: 123456
# MFA device "android" added.
```

### tsh mfa rm

Remove a registered Multi-Factor Authentication (MFA) device. You can view your
registered devices using [`tsh mfa ls`](cli.mdx#tsh-mfa-ls).

```code
$ tsh mfa rm <device-name>
```

Environment variables configure your tsh client and can help you avoid using flags repetitively.

| Environment Variable | Description | Example Value |
| - | - | - |
| TELEPORT_AUTH | Name of a defined SAML, OIDC, or Github auth connector | okta |
| TELEPORT_CLUSTER | Name of a Teleport root or leaf cluster | cluster.example.com |
| TELEPORT_LOGIN | Login name to be used by default on the remote host | root |
| TELEPORT_LOGIN_BIND_ADDR | Address in the form of host:port to bind to for login command webhook | host:port |
| TELEPORT_PROXY | Address of the Teleport proxy server | cluster.example.com:3080 |
| TELEPORT_HOME | Home location for tsh configuration and data | /directory |
| TELEPORT_USER | A Teleport user name | alice |
| TELEPORT_ADD_KEYS_TO_AGENT | Specifies if the user certificate should be stored on the running SSH agent | yes, no, auto, only |
| TELEPORT_USE_LOCAL_SSH_AGENT | Disable or enable local SSH agent integration | true, false |


## tctl

`tctl` is a CLI tool used to administer a Teleport cluster.

`tctl` allows a cluster administrator to manage all resources in a cluster
including nodes, users, tokens, and certificates.

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

By default, `tctl` connects to a local Auth server, meaning it will fail if you
attempt to run `tctl` on a non-`auth` host.

`tctl` can also connect to a remote Auth server if the `--identity` and
`--auth-server` flags are used. An identity file for use with `--identity`
can be exported with `tctl auth sign` or `tsh login --out=<output-path>`.

<Admonition type="note">
  Note that when a `tctl` command is run locally on an Auth server, the audit logs will
  show that it was performed by the Auth server itself. To properly audit admin actions
  at scale, it is important to limit direct ssh access to the Auth server with
  [Access Controls](../../access-controls/introduction.mdx) and ensure that admins use `tctl`
  remotely with the `--identity` flag instead.
</Admonition>

The `TELEPORT_CONFIG_FILE` environment variable indicates where the Teleport configuration file is.
If you're connecting to a remote Teleport cluster (Teleport Cloud) through a `tsh` session and have a file `/etc/teleport.yaml` on your machine set the `TELEPORT_CONFIG_FILE` to `""`.  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`.

**Example**

```code
$ export TELEPORT_CONFIG_FILE=""
$ tctl tokens add --type=node
```

### 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 address(es) instead of local auth [127.0.0.1:3025] |
| `-i, --identity` | none | **string** filepath | Path to an identity file. Must be provided to make remote connections to auth. An identity file can be exported with 'tctl auth sign' |
| `--insecure` | none | none | 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 |

### tctl help

Shows help:

```code
$ tctl help
```

### tctl users add

Generates a user invitation token:

```code
$ tctl users add [<flags>] <account> [<local-logins>]
```

#### Arguments

- `<account>` - The Teleport user account name.
- `<local-logins>` - A comma-separated list of local UNIX users this account can log in as. If unspecified the account will be mapped to an OS user of the same name. See examples below.

#### Flags

| Name | Default Value(s) | Allowed Value(s) | Description |
| - | - | - | - |
| `--k8s-groups` | none | a kubernetes group | Kubernetes groups to assign to a user, e.g. `system:masters` |
| `--k8s-users` | none | a kubernetes user | Kubernetes user to assign to a user, e.g. `jenkins` |
| `--ttl` | 1h | relative duration like 5s, 2m, or 3h, **maximum 48h** | Set expiration time for token |

#### [Global Flags](#tctl-global-flags)

These flags are available for all commands `--debug, --config`. Run
`tctl help <subcommand>` or see the [Global Flags Section](#tctl-global-flags)

#### Examples

```code
# Adds teleport user "joe" with mappings to
# OS users "joe" and "root"
$ tctl users add joe joe,root
# Adds teleport user "joe" with mappings to
# OS users "joe" only
$ tctl users add joe
```

### tctl users update

Update user account:

```code
$ tctl users update [<flags>] <account>
```

#### Arguments

- `<account>` - The Teleport user account name.

#### Flags

| Name | Default Value(s) | Allowed Value(s) | Description |
| - | - | - | - |
| `--set-roles` | none | a role name | Comma-separated list of roles for the user to assume, replaces current roles |

#### Examples

```code
$ tctl users update joe --set-roles=access,editor
# Assigns roles "access" and "editor" to user "joe"
```

### tctl users ls

Lists all user accounts:

```code
$ tctl users ls [<flags>]
```

### tctl users rm

Deletes user accounts:

```code
$ tctl users rm <logins>
```

#### Arguments

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

#### Examples

```code
$ tctl users rm sally,tim
# Removes users sally and tim
```

### tctl users reset

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

#### Arguments

- `<account>` - Teleport Local DB User

#### Flags

| 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

```code
$ 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 request ls

List of open requests:

```code
$ tctl request ls
```

#### Examples

```code
$ 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 approve

Approve a user's request:

```code
$ tctl request approve [token]
```

#### Arguments

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

#### Examples

```code
$ tctl request approve request-id-1, request-id-2
```

### tctl request deny

Denies a user's request:

```code
$ tctl request deny [token]
```

#### Arguments

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

#### Examples

```code
$ tctl request deny request-id-1, request-id-2
```

### tctl request rm

Delete a users role request:

```code
$ tctl request rm [token]
```

#### Arguments

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

#### Examples

```code
$ tctl request rm request-id-1
```

### tctl nodes add

Generate a node invitation token:

```code
$ 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](#tctl-global-flags)

These flags are available for all commands `--debug, --config`. Run
`tctl help <subcommand>` or see the [Global Flags Section](#tctl-global-flags)

#### Examples

```code
# 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:

```code
$ tctl nodes ls [<flags>]
```

#### Flags

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

#### [Global Flags](#tctl-global-flags)

These flags are available for all commands `--debug, --config`. Run
`tctl help <subcommand>` or see the [Global Flags Section](#tctl-global-flags)

### tctl tokens add

Create an invitation token:

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

#### Flags

| Name | Default Value(s) | Allowed Value(s) | Description |
| - | - | - | - |
| `--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 |
| `--ttl` | 1h | relative duration like 5s, 2m, or 3h | Set expiration time for token |

#### [Global Flags](#tctl-global-flags)

These flags are available for all commands `--debug, --config` . Run
`tctl help <subcommand>` or see the [Global Flags Section](#tctl-global-flags)

#### Examples

```code
# 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
# Generate an invite token for a node
# This is equivalent to `tctl nodes add`
$ tctl tokens add --type=node
# 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 rm

Delete/revoke an invitation token:

```code
$ tctl tokens rm [<token>]
```

#### Arguments

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

### tctl tokens ls

List node and user invitation tokens:

```code
$ tctl tokens ls [<flags>]
```

#### Example

```code
$ 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 auth export

Export public cluster (CA) keys to stdout:

```code
$ tctl auth export [<flags>]
```

#### Flags

| Name | Default Value(s) | Allowed Value(s) | Description |
| - | - | - | - |
| `--keys` | none | none | if set, will print private keys |
| `--fingerprint` | none | **string** e.g. `SHA265:<fingerprint>` | filter authority by fingerprint |
| `--compat` | none | version number | export certificates compatible with specific version of Teleport |
| `--type` | none | `user, host` or `tls` | certificate type |

#### [Global Flags](#tctl-global-flags)

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

```code
$ tctl help <subcommand>
```

or see the [Global Flags Section](#tctl-global-flags).

#### Examples

```code
# 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
```

### tctl auth sign

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

```code
$ 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 |
| `--format` | `file` | `file`, `openssh`, `tls` or `kubernetes` | identity format |
| `--identity` | `file` | `file` | identity format |
| `--auth-server` | none | auth host & port | Remote Teleport host name |
| `--ttl` | none | 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. | When --format is set to "kubernetes", this address will be set as cluster address in the generated kubeconfig file |
| `--leaf-cluster` | `""` | The name of a leaf cluster. | |
| `--kube-cluster-name` | `""` | Kubernetes Cluster Name | |

#### [Global Flags](#tctl-global-flags)

These flags are available for all commands `--debug, --config`. Run
`tctl help <subcommand>` or see the [Global Flags Section](#tctl-global-flags)

#### Examples

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

### tctl auth rotate

Rotate certificate authorities in the cluster:

```code
$ 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](#tctl-global-flags)

These flags are available for all commands `--debug, --config` . Run
`tctl help <subcommand>` or see the [Global Flags Section](#tctl-global-flags)

#### Examples

```code
# 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 create

Create or update a Teleport resource from a YAML file.

The supported resource types are: user, node, cluster, role, connector.
See the [Resources Reference](./resources.mdx) for complete docs on how to build these yaml files.

```code
$ 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](#tctl-global-flags)

These flags are available for all commands `--debug, --config`. Run
`tctl help <subcommand>` or see the [Global Flags Section](#tctl-global-flags)

#### Examples

```code
# 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 rm

Delete a resource:

```code
$ 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,token`]
  - `<resource name>` Resource name to delete

#### Examples

```code
# Delete a SAML connector called "okta":
$ tctl rm saml/okta

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

### tctl get

Print a YAML declaration of various Teleport resources:

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

#### Arguments

- `[<resource-type/resource-name>]` Resource to get
  - `<resource type>` Type of a resource \[for example: `user,cluster,token`]
  - `<resource name>` Resource name to get

#### 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](#tctl-global-flags)

These flags are available for all commands `--debug, --config` . Run
`tctl help <subcommand>` or see the [Global Flags Section](#tctl-global-flags)

#### Examples

```code
$ 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 status

Report cluster status:

```code
$ tctl status
```

#### Examples

```code
# Checks status of cluster.
$ tctl status Cluster  grav-00 User CA  never updated Host CA  never updated CA
# pin   sha256:1146cdd2b887772dcc2e879232c8f60012a839f7958724ce5744005474b15b9d
# Checks remote auth status using exported identity.
$ tctl status \
    --auth-server=192.168.99.102:3025 \
    --identity=identity.pem
```

### tctl top

Reports diagnostic information.

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

```code
$ tctl top [<diag-addr>] [<refresh>]
```

#### Argument

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

#### Example

```code
$ 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 version

Print cluster version:

```code
tctl version
```

## Resource filtering

Both `tsh` and `tctl` allow you to filter `nodes`, `apps`, `db`, and `kube` resources using the `--search` and `--query` flags.

The `--search` flag performs a simple fuzzy search on resource fields. For example, `--search=mac` searches for resources containing `mac`.

The `--query` flag allows you to perform more sophisticated searches using a [predicate language](predicate-language.mdx#resource-filtering).

In both cases, you can further refine the results by appending a list of comma-separated labels to the command. For example:

```bash
$ tsh ls --search=foo,bar labelKey1=labelValue1,labelKey2=labelValue2
```

### Filter Examples

```bash
# List all nodes
$ tsh ls

# List nodes using label argument
$ tsh ls env=staging,os=mac

# List nodes using search keywords
$ tsh ls --search=staging,mac

# List nodes using predicate language. This query searches for nodes with labels
# with key `env` equal to `staging` and key `os` equal to `mac`.
$ tsh ls --query='labels.env == "staging" && equals(labels.os, "mac")'
```

## Experimental features

### tctl access ls

Displays user accesses to SSH nodes

```bash
tctl access ls [--user <user> | --login <login> | --node <hostname>][<flags>]
```

#### Flags

| Name | Default Value(s) | Allowed Value(s) | Description |
| - | - | - | - |
| `--user` | none | existing user | Teleport user name |
| `--login` | none | user login | Teleport user login |
| `--node` | none | existing hostname | Teleport node hostname |
| `--namespace` | default | existing namespace | Teleport namespace |

#### Examples

```bash
# Get all user accesses over all nodes
tctl access ls
# Get accesses for user 'joe'
tctl access ls --user joe
# Get accesses for node 'prod'
tctl access ls --node prod
# Get accesses for login 'root'
tctl access ls --login root
# Get accesses for user 'joe', node 'prod', and login 'root'
tctl access ls --user joe --login root --node prod
```