teleport/docs/pages/reference/cli.mdx

---
title: Teleport CLI Reference
description: Detailed guide and reference documentation for Teleport's command line interface (CLI) tools.
---

Teleport is made up of four CLI tools.

- [teleport](#teleport): Supports the Teleport access plane by starting and configuring various Teleport services.
- [tsh](#tsh): Allows end users to authenticate to Teleport and access resources in a cluster.
- [tctl](#tctl): Used to configure the Teleport Auth Service.
- [tbot](#tbot): Supports Machine ID, which provides short lived credentials to service accounts (e.g, a CI/CD server).

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

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

## teleport

The CLI tool that supports the Teleport access plane is called `teleport`, and allows Teleport services to be managed
over the command line:

- [Auth](../architecture/authentication.mdx)
- [Node/SSH](../architecture/nodes.mdx)
- [Proxy](../architecture/proxy.mdx)
- [App](../application-access/introduction.mdx)
- [Database](../database-access/introduction.mdx)
- [Windows Desktop](../desktop-access/introduction.mdx)
- [Kubernetes](../kubernetes-access/introduction.mdx)

The primary commands for the `teleport` CLI are as follows:

| Command | Description |
| - | - |
| `teleport help` | Outputs guidance for using Teleport commands. |
| `teleport start` | Starts the `teleport` process in the foregound using the current shell session, including any services configured by the [configuration YAML file](config.mdx). |
| `teleport status` | Prints the status of the current active Teleport SSH session. |
| `teleport configure` | Generates and writes a [configuration YAML file](config.mdx) for the Teleport service. This file should be customized in production to suit the needs of your environment, and the default output should only be used when testing. |
| `teleport version` | Prints the current release version of the Teleport binary installed on your system. |
| `teleport app start` | Starts the Teleport Application Service. |
| `teleport db start` | Starts the Teleport Database Service. |
| `teleport db configure create` | Generates a configuration YAML file for the Database Service. This file should be customized in production to suit the needs of your environment, and the default output should only be used when testing. |
| `teleport db configure bootstrap` | Used to bootstrap a configuration to the Teleport Database Service by reading a provided configuration. |
| `teleport db configure aws print-iam` | Generates and outputs current IAM policies for a Teleport-managed database. |
| `teleport db configure aws create-iam` | Generates, creates, and attaches desired IAM policies to a Teleport-managed database. |
| `teleport install systemd` | Creates a systemd unit file, used to configure and install a `teleport` service daemon. |
| `teleport node configure` | Generates a configuration YAML file for a Teleport Node accessed via SSH. This file should be customized in production to suit the needs of your environment, and the default output should only be used when testing. |

<Notice type="tip">
For more information on subcommands when working with the `teleport` cli, use the `--help` option or `teleport <subcommand> --help`.
</Notice>

### teleport start

The `teleport start` command includes a large number of optional configuration flags.

While configuration flags for `teleport start` can be used to set parameters for Teleport's configuration,
we recommend using a [configuration file](https://goteleport.com/docs/reference/config/) in production.

#### 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`, `node`, `auth`, `db`, or `app` | start listed services/roles. These roles are explained in the [Core Concepts](../core-concepts.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` | value returned by the `hostname` command on the machine | **string** | assigns an alternative name for the node which can be used by clients to log in. |
| `-c, --config` | `/etc/teleport.yaml` | **string** `.yaml` filepath | starts services with config specified in the YAML file, overrides CLI flags if set |
| `--apply-on-startup` | none | **string** `.yaml` filepath | On startup, always apply resources described in the file at the given path. Only supports the following types: `token`. |
| `--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](../management/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. |
| `--skip-version-check` | `false` | `true` or `false` | Skips version checks between the Auth Server this Teleport instance |
| `--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 |

#### teleport start --roles

The `--roles` flag when used with `teleport --start` instructs Teleport on which specific Teleport services to start. Below is a more cohesive table of roles and their associated services that `teleport start` supports:

| Service | Role Name | Description |
| - | - | - |
| [Node](../architecture/nodes.mdx) | `node` | Allows SSH connections from authenticated clients. |
| [Auth](../architecture/authentication.mdx) | `auth` | Authenticates and authorizes hosts and users who want access to Teleport-managed resources or information about a cluster. |
| [Proxy](../architecture/proxy.mdx) | `proxy` | The gateway that clients use to connect to the Auth Service or resources managed by Teleport. |
| [App](../application-access/introduction.mdx) | `app` | Provides access to applications. |
| [Database](../database-access/reference.mdx) | `db` | Provides access to databases. |

<Notice type="tip" scope={["cloud"]}>

Teleport Cloud manages Teleport instances with the `auth` and `proxy` roles. Use
the remaining roles to manage access to specific resources and other Teleport
clusters.

</Notice>

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

## 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 will use |
| `--proxy` | none | `host:https_port[,ssh_proxy_port]` | Teleport Proxy Service address |
| `--user` | `$USER` | none | The Teleport username |
| `--ttl` | `720` (12 hours) | integer | Number of minutes a certificate issued for the `tsh` user will be valid for |
| `-i, --identity` | none | **string** filepath | Identity file |
| `--cert-format` | `standard` | `standard` or `oldssh` | SSH certificate format |
| `--insecure` | none | none | Do not verify the server's certificate and host name. Use only in test environments. |
| `--auth` | `local` | any defined [authentication connector](./authentication.mdx), including `local` and `passwordless` | Specify the type of authentication connector to use. |
| `--mfa-mode` | auto | `auto`, `cross-platform`, `platform` or `otp` | Preferred mode for MFA and Passwordless assertions. |
| `--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 the version of your `tsh` binary and the Teleport Proxy Service in the current `tsh` profile

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

| Name           | Default Value(s) | Allowed Value(s) | Description                                        |
|----------------|------------------|------------------|----------------------------------------------------|
| `-f, --format` | `text`           | text, json, yaml | Format for version output                          |
| `--client`     | none             | none             | Show the client version only (no server required). |

#### Examples

```code
$ tsh version
Teleport v(=teleport.version=) git: go(=teleport.golang=)
Proxy version: (=teleport.version=)
Proxy: teleport.example.com:443
```

Display in JSON format:

```code
$ tsh version --format=json
```

```json
{
  "version": "(=teleport.version=)",
  "gitref": "",
  "runtime": "go(=teleport.golang=)",
  "proxyVersion": "(=teleport.version=)",
  "proxyPublicAddress": "teleport.example.com:443"
}
```

Only display the `tsh` binary version:

```code
$ tsh version --client
Teleport v(=teleport.version=) git: go(=teleport.golang=)
```

### 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` The `nodename` of a cluster Node or a label specification like `env=aws` to run on all matching hosts.
- `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`) |
| `-X, --x11-untrusted` | none | none | Requests untrusted (secure) X11 forwarding for this session. |
| `-Y, --x11-trusted` | none | none | Requests trusted (insecure) X11 forwarding for this session. This can make your local machine vulnerable to attacks, use with caution. |
| `--x11-untrusted-timeout` | 10m | duration | Sets a timeout for untrusted X11 forwarding, after which the client will reject any forwarding requests from the server. |

#### 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
# Run `hostname` on all nodes with the `env: aws` label
$ tsh ssh root@env=aws hostname
```

### 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 gcloud

Proxy `gcloud` CLI commands through the Teleport Application Service. `gcloud`
is a tool for interacting with Google Cloud. A user must already be
authenticated to a Google Cloud application in Teleport before they can execute
`tsh gcloud` commands.

```code
$ tsh gcloud [--app] [<command>] 
```

#### Arguments

`command`: A `gcloud` command to run, including arguments and flags.

#### Flags

| Name | Default Value(s) | Allowed Value(s) | Description |
| - | - | - | - |
| <nobr>`--app`</nobr> | Currently logged in Google Cloud application | The name of a Google Cloud application as listed via `tsh apps ls`. | The Google Cloud application to run the command against, if logged in to multiple Google Cloud applications. |

#### 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
$ tsh gcloud compute instances list 
```

### tsh gsutil

Proxy `gsutil` CLI commands through the Teleport Application Service. `gsutil`
is a tool for interacting with Google Cloud Storage. A user must already be
authenticated to a Google Cloud application in Teleport before they can execute
`tsh gsutil` commands.

```code
$ tsh gsutil [--app] [<command>] 
```

#### Arguments

`command`: A `gsutil` command to run, including arguments and flags.

#### Flags

| Name | Default Value(s) | Allowed Value(s) | Description |
| - | - | - | - |
| <nobr>`--app`</nobr> | Currently logged in Google Cloud application | The name of a Google Cloud application as listed via `tsh apps ls`. | The Google Cloud application to run the command against, if logged in to multiple Google Cloud applications. |

#### 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
$ tsh gsutil 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

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 recordings ls

List recorded sessions.

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

#### Flags

| Name | Default Value(s) | Allowed Value(s) | Description |
| - | - | - | - |
| `--from-utc` | 24 hours ago | date | Start of time range in which recordings are listed. Format 2006-01-02. Defaults to 24 hours ago. |
| `--to-utc` | current | date | Start of time range in which recordings are listed. Format 2006-01-02. Defaults to 24 hours ago. |
| `--limit` | 50 | number | Maximum number of recordings to show. |
| `--last` | none | duration | Duration into the past from which session recordings should be listed. Format 5h30m40s |

#### 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
# get the recorded sessions from the last 24 hours
$ tsh --proxy proxy.example.com recordings ls
ID                                   Type Participants Hostname Timestamp
------------------------------------ ---- ------------ -------- -------------------
b0a04442-70dc-4be8-9308-7b7901d2d600 ssh  jeff         dev       Nov 26 16:36:16 UTC
c0a02222-70dc-4be8-9308-7b7901d2d600 kube alice                  Nov 26 20:36:16 UTC
d0a04442-70dc-4be8-9308-7b7901d2d600 ssh  navin        test      Nov 26 16:36:16 UTC

# The session can be played with tsh play
$ tsh play c0a02222-70dc-4be8-9308-7b7901d2d60

# List recorded sessions that occurred between Nov 1, 2022 to Nov 3, 2022
$ tsh recordings ls --from-utc=2022-11-01 --to-utc=2022-11-3

# Retrieve recorded sessions in the last 6 hours
$ tsh recordings ls --last=6h0m0s
```

<Admonition
  title="Recorded Sessions Availability"
  scope={["oss", "enterprise"]} type="tip" scopeOnly
>

Recorded sessions are linked from the audit events to session recordings files
in their [storage backend](../reference/backends.mdx).
The following error can occur if a session recording file is not available or
when employing multiple auth servers with directory storage backend for recorded
sessions. When using a directory storage backend for audit logs and recorded sessions,
only the auth server with that recorded session can retrieve it.

```code
$ tsh play c8e1b2c5-322a-4095-89e3-391edfd2da9b
ERROR: Recording for session c8e1b2c5-322a-4095-89e3-391edfd2da9b not found.
```

Using a Security Information and Event Management (SIEM) service that combines
the audit logs will help consolidate the list of available recordings.

Downloaded recorded session are directly playable as a file.

```code
$ tsh play c8e1b2c5-322a-4095-89e3-391edfd2da9b.tar
```
</Admonition>


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

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 db

Start a local TLS proxy for database connections when using Teleport with TLS
Routing enabled. Clients can connect to a Teleport-registered database through
the local proxy.

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

#### Flags

| Name | Default Value(s) | Allowed Value(s) | Description |
| - | - | - | - |
| `--cert-file` | none | string | Path to the certificate file for configuring TLS on the local proxy.|
| `--cluster` | none | string | The name of the Teleport cluster to connect to. |
| `--key-file` | none | string | Path to the private key file for configuring TLS on the local proxy.|
| `--db-name` | none | string | Optional database name to log in to. |
| `--db-user` | none | string | Optional database user to log in as. |
| `--port` | none | string | Source port used by the local proxy.|
| `--tunnel` | none | Boolean | Open an authenticated tunnel using a database's client certificate so clients don't need to authenticate. |

#### [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

Proxy a DB connection to a named database
```code
$ tsh proxy db <db>
```

Proxy a connection to mysql db on local port 10700:
```code
$ tsh proxy db --port 10700  mysql-db
# Started DB proxy on 127.0.0.1:10700

# Use following credentials to connect to the mysql-db proxy:
#  ca_file=/Users/jeff/.tsh/keys/teleport.example.com/cas/teleport.example.com.pem
#  cert_file=/Users/jeff/.tsh/keys/teleport.example.com/jeff-db/tele1c/mysql-db-x509.pem
#  key_file=/Users/jeff/.tsh/keys/teleport.example.com/jeff
```

Proxy a connection to mysql db with no credentials required:
```code
$ tsh proxy db --tunnel mysql-db
Started authenticated tunnel for the MySQL database "mysql-db" in cluster "teleport.example.com" on 127.0.0.1:49415.

Use the following command to connect to the database:
  $ mysql --port 49415 --host localhost --protocol TCP
```

### tsh proxy ssh

Start a local TLS proxy for `ssh` connections when using Teleport in TLS Routing mode.
This is typically used as part of the SSH client configuration to use `ssh` as a client
through Teleport.  See the [OpenSSH Guide](../server-access/guides/openssh.mdx) guide
on configuring OpenSSH servers and clients.  The `tsh config` output will include `tsh proxy ssh`
within a `ProxyCommand` directive.

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

#### Arguments
- `<[user@]host>` Remote hostname and the login to use

#### Flags

| Name | Default Value(s) | Allowed Value(s) | Description |
| - | - | - | - |
| `--cluster` | none | Teleport Cluster | The name of the Teleport cluster to connect to.|

#### [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

Run the following command to generate an OpenSSH client configuration:

```code
$ tsh config
```

This command produces the following configuration:

```
# Common flags for all example.com hosts
Host *.example.com example.com
    UserKnownHostsFile "/Users/jeff/.tsh/known_hosts"
    IdentityFile "/Users/jeff/.tsh/keys/enterprise.teleportdemo.com/jeff"
    CertificateFile "/Users/jeff/.tsh/keys/example.com/jeff-ssh/example.com-cert.pub"
    PubkeyAcceptedKeyTypes +ssh-rsa-cert-v01@openssh.com
    HostKeyAlgorithms ssh-rsa-cert-v01@openssh.com

# Flags for all example.com hosts except the proxy
Host *.example.com !example.com
    Port 3022
    ProxyCommand "/usr/local/bin/tsh" proxy ssh --cluster=example.com --proxy=example.com %r@%h:%p
```

This output should be placed into the default SSH Config for environment, `~/.ssh/config` for Mac/Linux or
`.ssh\config` in the Windows User home directory. You can use this as a standalone SSH config file too.

When you run an `ssh` command against a host with a subdomain of your Proxy
Service's domain, this SSH configuration will use the `ProxyCommand` to run `tsh
proxy ssh`:

```code
$ ssh myuser@node1.example.com
```

### 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 |
| - | - | - | - |
| `-p, --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 proxy azure

Starts a local proxy server that provides secure access to an Azure managed
service identity endpoint. This is useful for managing access to Azure from
custom client applications. The local proxy forwards traffic to the Teleport
Application Service, which uses an Azure managed identity to fetch an
authentication token from Azure.

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

The command will print the address of the local proxy server along with `export`
commands for environment variables required to connect:

```text
Started Azure proxy on http://127.0.0.1:54330.
To avoid port randomization, you can choose the listening port using the --port flag.

Use the following credentials and HTTPS proxy setting to connect to the proxy:

  export AZURE_CONFIG_DIR=/Users/myuser/.tsh/azure/my.teleport.cluster/azure
  export HTTPS_PROXY=http://127.0.0.1:54330
  export HTTP_PROXY=http://127.0.0.1:54330
  export MSI_ENDPOINT=https://azure-msi.teleport.dev/eedfd5b55257c0aaa58f
  export REQUESTS_CA_BUNDLE=/Users/myuser/.tsh/keys/teleport.example.com/myuser-app/teleport.example.com/azure-cli-localca.pem
```

<Notice type="tip">

`tsh proxy azure` runs the local proxy in the foreground, so don't interrupt
the process or exit the terminal where you ran the command until you're ready
to close the local proxy.

</Notice>

Copy the `export` commands and paste them into a second terminal.

To run the local proxy server, one of the user's roles must include the
`spec.allow.azure_identities` field with one of the identities used by the
Application Service. To learn how to set up secure access to Azure via
Teleport, read [Protect the Azure CLI with Teleport Application
Access](../application-access/cloud-apis/azure.mdx).

#### Arguments

This command does not accept any arguments.

#### Flags
| Name | Default Value(s) | Allowed Value(s) | Description |
| - | - | - | - |
| `--app` | none | string | Name of the Teleport application representing Azure (i.e., based on `tsh apps ls`). Use this flag if your Teleport user has access to multiple Azure applications. |
| `--port` | none | port number | The port on `localhost` where the local proxy will listen for connections. |
| `--format` | `powershell` if on Windows, `unix` otherwise | `text`, `unix`, `command-prompt`, or `powershell` | The format to use for listing environment variables for Azure client applications connecting to 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)

### tsh proxy aws

Start a local proxy for AWS access. The user must already be logged in to at
least one AWS application via Teleport before the proxy can start.

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

#### Flags

| Name | Default Value(s) | Allowed Value(s) | Description |
| - | - | - | - |
| `--app` | Currently logged in AWS app | string | Optional name of the AWS application (as shown in `tsh apps ls`) to use if logged in to multiple |
| `-p, --port` | none | port number | Specify the source port for the local proxy |
| ` -e, --endpoint-url` | HTTP Proxy | Endpoint URL | Run the local proxy to serve as an AWS endpoint URL. If not specified, the local proxy serves as an HTTPS proxy. |
| `-f, --format` | unix | `text`, `unix`, `command-prompt`, or `powershell` | Optional format for printing environment variables for the AWS 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
# Proxy a connection to AWS with the default settings
$ tsh apps login awsapp
$ tsh proxy aws
# Set env variables from output
$ aws s3 ls

# Proxying connections to AWS on 127.0.0.1:10700 to app awsapp2
$ tsh apps logins awsapp2
$ tsh proxy aws --port=10700 --app=awsapp2
# Set env variables from output
$ aws s3 ls
```

### tsh proxy gcloud

Start a local proxy for Google Cloud API access. The user must already be logged
in to at least one Google Cloud application via Teleport before the proxy can
start.

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

#### Flags

| Name | Default Value(s) | Allowed Value(s) | Description |
| - | - | - | - |
| `--app` | Currently logged in Google Cloud app | string | Optional name of the Google Cloud application (as shown in `tsh apps ls`) to use if logged in to multiple |
| `-p, --port` | none | port number | Specify the source port for the local proxy |
| <nobr>`-e, --endpoint-url`</nobr> | HTTP Proxy | Endpoint URL | Run the local proxy to serve as a Google Cloud endpoint URL. If not specified, the local proxy serves as an HTTPS proxy. |
| `-f, --format` | unix | `text`, `unix`, `command-prompt`, or `powershell` | Optional format for printing environment variables for the Google Cloud 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 apps login google-cloud-app
$ tsh proxy gcloud
# Set env variables from output
$ gcloud compute instances list 
$ gsutil ls
```

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

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 example.txt user@host:/destination/dir
```

### tsh ls

List cluster nodes:

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

<Details title="Not seeing Nodes?" opened={false}>

(!docs/pages/includes/node-logins.mdx!)

</Details>

{/* 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

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

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](../management/admin/trustedclusters.mdx) 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

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 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". Try 'kubectl version' to test the connection.

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

#### Flags

| Name | Default Value(s) | Allowed Value(s) | Description |
| - | - | - | - |
| `--all` | false | Boolean | Whether to generate a kubeconfig for every Kubernetes cluster the current Teleport user has access to. If this is false, `tsh` will only generate a kubeconfig for the cluster specified in the `tsh kube login` command.|
| `--as` | none | string | The Kubernetes user that the current Teleport user will log in as when they authenticate to the specified Kubernetes cluster. <br/><br/>This uses [Kubernetes impersonation](https://kubernetes.io/docs/reference/access-authn-authz/authentication/#user-impersonation), so the Teleport user's Kubernetes user must have permissions to impersonate the target user. |
| `--as-groups` | none | string | A Kubernetes group that the current Teleport user will log in as when they authenticate to the specified Kubernetes cluster. <br/><br/>This uses [Kubernetes impersonation](https://kubernetes.io/docs/reference/access-authn-authz/authentication/#user-impersonation), so the Teleport user's Kubernetes user must have permissions to impersonate the target group. <br /><br/>You can include this flag multiple times to enable impersonation of multiple Kubernetes groups. |
| `--cluster` | none | string | Name of the Teleport cluster to log into in order to connect to the given Kubernetes cluster. |
| `-n`, `--kube-namespace` | none | string | The name of the Kubernetes namespace to configure as the default within the cluster the user is logging into. |

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

### tsh request create

Create a new Access Request.

```code
$ tsh request create [<flags>]
```

#### Flags

| Name | Default Value(s) | Allowed Value(s) | Description |
| - | - | - | - |
| `--roles` | none | Comma-separated strings | List of Teleport roles to request |
| `--resource` | none | String (flag can be repeated to request multiple resources) | Resource ID to be requested |
| `--reason` | none | String | Reason for making the request (optional) |
| `--reviewers` | none | Comma-separated strings | Suggested reviewers for the request (optional) |
| `--nowait` | `false` | `true` or `false` | Finish without waiting for request resolution |
| `--request-ttl` | 1 hour | Relative duration like `5s`, `2m`, or `3h`, | Defines how long the Access Request will be in a `PENDING` state before becoming invalid |
| `--session-ttl` | Time left on current session | Relative duration like `5s`, `2m`, or `3h` | Defines how long the elevated session will be valid for |

<Admonition type="tip" title="Note">
The `--request-ttl` and `--session-ttl` values can not be greater than the
following:

- Maximum certificate lifetime.
- Time left on an existing session (certificate).
- Maximum session duration defined by the user's roles.
</Admonition>

### tsh request ls

List Access Requests

```code
$ tsh request ls
```

#### Flags

| Name | Default Value(s) | Allowed Value(s) | Description |
| - | - | - | - |
| `--format` | `text` | `text`, `json`, or `yaml` | Format output |
| `--reviewable` | `false` | `true` or `false` | Only show requests reviewable by current user |
| `--suggested` | `false` | `true` or `false` | Only show requests that suggest current user as reviewer |
| `--my-requests` | `false` | `true` or `false` | Only show requests created by current user |

### tsh request show

Show Access Request details

```code
$ tsh request show <request-id>
```

#### Flags

| Name | Default Value(s) | Allowed Value(s) | Description |
| - | - | - | - |
| `--format` | text | `text`, `json`, or `yaml` | Format output |

#### Arguments

- `<request-id>` - ID of the target request

### tsh request review

Review an Access Request

```code
$ tsh request review [<flags>] <request-id>
```

#### Flags

| Name | Default Value(s) | Allowed Value(s) | Description |
| - | - | - | - |
| `--approve` | `false` | `true` or `false` | Review proposes approval |
| `--deny` | `false` | `true` or `false` | Review proposes denial |
| `--reason` | none | String | Review reason message |

#### Arguments

- `<request-id>` - ID of the target request

### tsh request search

Search for resources to request access to

```code
$ tsh request search [<flags>]
```

#### Flags

| Name | Default Value(s) | Allowed Value(s) | Description |
| - | - | - | - |
| `--kind` | none | `node`, `kubernetes_cluster`, `db`, `app`, `windows_desktop` | Resource kind to search for (required) |
| `--search` | none | Comma-separated strings | List of comma-separated search keywords or phrases enclosed in single quotes |
| `--query` | none | String | Query by [predicate language](predicate-language.mdx#resource-filtering) enclosed in single quotes |
| `--labels` | none | Comma-separated strings | List of comma-separated labels to filter by labels (e.g. `key=value1,key2=value2`) |

### tsh request drop

Drop one or more access requests from current identity

```code
$ tsh request drop [<request-id>...]
```

#### Arguments

- `<request-id>` - IDs of requests to "drop" from the current identity so that
  your certificate will lose elevated roles and/or resource restrictions.
  If no request ID is given, the default is to drop all Access Requests.

### tsh device enroll

Enroll the current device as a trusted device.

Requires a device enrollment token created via `tctl devices enroll`.

```code
$ tsh device enroll --token=TOKEN
```

#### Flags

| Name | Default Value(s) | Allowed Value(s) | Description |
| - | - | - | - |
| `--token` | none | String | Device enrollment token |

#### Examples

```code
$ tsh device enroll --token=(=devicetrust.enroll_token=)
Device "(=devicetrust.asset_tag=)"/macOS enrolled
```

### tsh environment variables

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 local, SAML, OIDC, or GitHub auth connector | okta |
| TELEPORT_MFA_MODE | Preferred mode for MFA and Passwordless assertions | otp |
| 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 |
| TELEPORT_GLOBAL_TSH_CONFIG | Override location of global `tsh` config file from default `/etc/tsh.yaml` | /opt/teleport/tsh.yaml |

### tsh configuration files

`tsh` has an optional configuration files:
- global, shared config: `/etc/tsh.yaml`. Location can be overridden with `TELEPORT_GLOBAL_TSH_CONFIG` environment variable.
- user specific config: `$TELEPORT_HOME/config/config.yaml`. Unless changed, `TELEPORT_HOME` defaults to `~/.tsh`.

The settings from both are merged, with the user config taking precedence.

#### Extra proxy headers

The `tsh` configuration file enables you to specify HTTP headers to be
included in requests to Teleport Proxy Servers with addresses matching
the `proxy` field.

```yaml
add_headers:
  - proxy: "*.example.com" # matching proxies will have headers included
    headers: # headers are pairs to include in the http headers
      foo: bar # Key/Value to be included in the http request
```

Adding HTTP headers may be useful, if for example an intermediate HTTP
proxy is in place that requires setting an authentication token:

```yaml
add_headers:
  - proxy: "*.infra.corp.xyz"
    headers:
      "Authorization": "Bearer tokentokentoken"
```

#### Aliases

Aliases allow you to define custom commands or change the default flag values for existing commands using the following syntax:

```yaml
aliases:
    "<alias>": "<command>"
```

The `<alias>` can only be a top-level subcommand. In other words, you can define a `tsh mycommand` alias but not `tsh my command`.

New command `tsh l`:

```yaml
aliases:
    "l": "tsh login --auth=okta"
```

Make `tsh status` use JSON as a default format:

```yaml
aliases:
    "status": "tsh status --format=json"
```

The alias can use an arbitrary number of arguments. If an argument variable `$N` is referenced, `tsh` will check that at least `N+1` arguments were given to the alias invocation. All arguments that were given but not referenced in the alias definition will be appended at the end.

Define a custom command using `bash`. The `$0` and `$1` variables will be substituted with command arguments.

```yaml
aliases:
    "connect": "bash -c 'tsh login $0 && tsh ssh $1'"
```

Define a custom login command where first argument specifies `--auth` option.

```yaml
aliases:
    "ap": "tsh login --auth=$0 --proxy=teleport.example.com"
```

Given the configuration:

```yaml
aliases:
    "example": "bash -c 'echo first=$0 $0-$1 $3'"
```

`tsh example 0 1 unused-2 3 unused-4` will expand to `bash -c 'echo first=0 0-1 3 unused-2 unused-4'`.

An alias definition can also reference the `$TSH` variable. `tsh` will expand this variable to the absolute path of the current `tsh` executable. This can be useful if there are multiple `tsh` versions installed, or the currently used version is not in `PATH`.

```yaml
aliases:
    "status": "$TSH status --format=json"
```

To troubleshoot aliases, set the `TELEPORT_DEBUG=1` environment variable. This will cause detailed logs to be printed to the console:

```bash
$ TELEPORT_DEBUG=1 tsh status
DEBU [TSH]       Self re-exec command: tsh [status --format=json]. tsh/aliases.go:203
...
```


## 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 Trusted Clusters.

<Tabs>
  <TabItem scope={["enterprise", "oss"]} label="Self-Hosted">

When running `tctl` commands, administrators must authenticate to a Teleport
cluster. This can be done in three ways:

### On a remote host with an identity file

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

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

### On the same host as the Teleport Auth Service

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

`tctl` only authenticates using this method if an identity file is not provided.

<Admonition type="note">

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

  To provide an accurate audit trail, it is important to limit direct SSH access
  to the Auth Service with
  [Access Controls](../access-controls/introduction.mdx) and ensure that
  admins use `tctl` remotely instead.

</Admonition>

### On a remote host after running `tsh login`

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

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

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

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

  </TabItem>
  <TabItem scope={["cloud"]} label="Teleport Cloud">

When running `tctl` commands, administrators must authenticate to a Teleport
cluster. This can be done in two ways:

### On a remote host with an identity file

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

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

### On a remote host after running `tsh login`

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

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

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

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

  </TabItem>
</Tabs>



**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 Service address(es) instead of a local Auth Service (`127.0.0.1:3025`) |
| `-i, --identity` | none | **string** filepath | Path to an identity file |
| `--insecure` | none | none | When specifying a Proxy Service address in `--auth-server`, do not verify its TLS certificate. Danger: any data you send can be intercepted or modified by an attacker |

### tctl help

Shows help:

```code
$ tctl help
```

### tctl users add

Generates a user invitation token:

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

#### Arguments

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

#### Flags

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

#### 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 and {{ internal.logins }} to "joe" and "ubuntu"
$ tctl users add joe --roles=access joe,ubuntu
# Adds Teleport user "joe" with mappings to the editor role
$ tctl users add joe --roles=editor
```

### 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 | Comma-separated list of roles for the user to assume. | Assigns the user's roles to the ones provided, replacing the user's current roles. |
| `--set-azure-identities` | none | Comma-separated list of allowed Azure identity URIs. |  Assigns the user's allowed Azure identities to the ones provided, replacing the user's currently allowed Azure identities. |

#### Examples

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

```code
$ tctl users update joe --set-roles=access,editor
```

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

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

### tctl 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

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

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 |
| `--format` | none | `text`, `json`, `yaml` | Output format |

#### Global flags

These flags are available for all commands `--debug, --config` . Run
`tctl help <subcommand>` or see the [Global Flags section](#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 a join token for both a Node and the Database Service
$ tctl tokens add --type=node,db
# Generate an invite token for a kubernetes_service
$ tctl tokens add --type=kube
# Generate an invite token for an app_service
$ tctl tokens add --type=app
```

### tctl tokens 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>]
```

#### Flags

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

#### Global flags

These flags are available for all commands `--debug, --config` . Run
`tctl help <subcommand>` or see the [Global Flags section](#tctl-global-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, only exports private keys |
| `--fingerprint` | none | **string** e.g. `SHA256:<fingerprint>` | filter authority by fingerprint |
| `--compat` | none | version number | export certificates compatible with specific version of Teleport |
| `--type` | none | `user`, `host`, `tls-host`, `tls-user`, `tls-user-der`, `windows`, `db`, `openssh`, `saml-idp` | certificate type |

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

#### Global flags

These flags are available for all commands `--debug, --config`. Run
`tctl help <subcommand>` or see the [Global Flags section](#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

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 sso test

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

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

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

The testing consists of running a single end-to-end authentication request using the provided auth connector definition.
Once the request is finished, the results will be printed to standard output along with context-specific diagnostic information.
The test process is safe from side effects in that:
- it will not change the list of configured auth connectors
- the audit log will clearly state the login attempts as "test" ones
- there will be no certificates issued for the authenticated user

<Admonition
  type="note"
  title="Important"
>
  To use this command, you must have access to the `github_request`, `oidc_request`, and `saml_request` resources (depending on the type of connector being tested).

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

```yaml
- resources: [github_request]
  verbs: [list,create,read,update,delete]
- resources: [oidc_request]
  verbs: [list,create,read,update,delete]
- resources: [saml_request]
  verbs: [list,create,read,update,delete]
```
</Admonition>


#### Arguments

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

#### Flags

This command defines no flags.

#### Global flags

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

#### Examples

Test the auth connector from `connector.yaml`:

```code
$ tctl sso test connector.yaml
```

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

```code
$ tctl sso configure ... | tctl sso test
```

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

```code
$ tctl sso configure ... | tee connector.yaml | tctl sso test
```

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

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

<Admonition
  type="note"
  title="Important"
>
  Make sure to include `--with-secrets` flag, or the exported auth connector will not be testable.
</Admonition>

### tctl sso configure github

Configure the GitHub auth connector.

Required params `--id` and `--secret` come from registering a GitHub OAuth app, which you can read about in the [GitHub documentation](https://docs.github.com/en/developers/apps/building-oauth-apps/creating-an-oauth-app).

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

```code
$ tctl sso test --id=GITHUB_CLIENT_ID --secret=GITHUB_SECRET --teams-to-roles=octocats,devs,access,editor [<other-flags>]
```

#### Arguments

This command accepts no arguments.

#### Flags

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

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

#### Global flags

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

#### Examples

Generate a GitHub auth connector. Two role mappings are defined:
  - members of the `admin` team in the `octocats` org will receive `access`, `editor` and `auditor` roles.
  - members of the `dev` team in `octocats` org will receive the `access` role.

<Admonition type="note">
  `tctl sso configure gh` is an alias for `tctl sso configure github`.
</Admonition>

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

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

```code
$ tctl sso configure gh ... | tctl sso test
```

### tctl sso configure oidc

Configure an OIDC auth connector, optionally using a preset.

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

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

#### Arguments

This command accepts no arguments.

#### Flags

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

General flags:

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

Supported presets:

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

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

The following flags are specific to Google Workspace:

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


#### Global flags

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

#### Examples

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

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

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

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

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

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

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

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

```code
$ tctl sso configure oidc ... | tctl sso test
```


### tctl sso configure saml

Configure the SAML auth connector, optionally using a preset.

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

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

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

#### Arguments

This command accepts no arguments.

#### Flags

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

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


Supported presets:

| Name       | Description                          | Display   |
|------------|--------------------------------------|-----------|
| `okta`     | Okta                                 | Okta      |
| `onelogin` | OneLogin                             | OneLogin  |
| `ad`       | Azure Active Directory               | Microsoft |
| `adfs`     | Active Directory Federation Services | ADFS      |


#### Global flags

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

#### Examples

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

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

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

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

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

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

### tctl login_rule test

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

#### Arguments

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

#### Flags

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

#### Global flags

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

#### Examples

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

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

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

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

Read the input traits from stdin

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

### tctl create

Create or update a Teleport resource from a YAML file.

The supported resource types are: user, node, cluster, role, connector, and device.
See the [Resources Reference](./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

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,tokens,device`]
  - `<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>` The resource to get
  - `<resource type>` The type of the resource \[for example: `user,cluster,token,device`]
  - `<resource name>` The name of the resource

#### Flags

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

#### Global flags

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

#### Examples

<ScopedBlock scope={["oss", "enterprise"]}>

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

</ScopedBlock>
<ScopedBlock scope={["cloud"]}>

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

</ScopedBlock>

### tctl edit

Modify a Teleport resource using your preferred text editor.

```code
$ tctl edit <resource-type/resource-name>
```

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

- the `TELEPORT_EDITOR` environment variable
- the `VISUAL` environment variable
- the `EDITOR` environment variable
- defaulting to `vi`

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

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

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

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

#### Arguments

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

#### Global flags

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

#### Examples

```code
# edit the sre role
$ tctl edit role/sre

# edit the alice user with the nano editor
$ TELEPORT_EDITOR=nano tctl edit user/alice
```


### 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 alerts create

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

```code
$ tctl alerts create [<flags>] <message>
```

#### Arguments

- `<message>`: The message for the alert to display

#### Flags

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

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

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

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

#### Examples

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

### tctl devices add

Register a device.


```code
$ tctl devices add --os=OS --asset-tag=SERIAL_NUMBER
```

#### Flags

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

#### Examples

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

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

### tctl devices enroll

Create an enrollment token for a device.

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

#### Flags

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

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

#### Examples

```code
$ tctl devices enroll --device-id=d40f2ee4-856d-4aef-b784-c4371e39c036
Run the command below on device "d40f2ee4-856d-4aef-b784-c4371e39c036" to enroll it:
tsh device enroll --token=(=devicetrust.enroll_token=)

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

### tctl devices ls

List registered devices.


```code
$ tctl devices ls
```

#### Examples

```code
$ tctl devices ls

Asset Tag    OS    Enroll Status Device ID
------------ ----- ------------- ------------------------------------
(=devicetrust.asset_tag=) macOS enrolled      d40f2ee4-856d-4aef-b784-c4371e39c036
```

### tctl devices rm

Removes a registered device.

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

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

#### Flags

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

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

#### Examples

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

$ tctl devices rm --asset-tag=(=devicetrust.asset_tag=)
Device "(=devicetrust.asset_tag=)" removed
```

### tctl 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 the version of your `tctl` binary:

```code
tctl version
```

## Resource filtering

Both `tsh` and `tctl` allow you to filter servers, applications, databases,
desktops, and Kubernetes clusters 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:

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

### Filter Examples

```code
# 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")'
```

## tbot

`tbot` is a CLI tool used with **Machine ID** that programatically issues and renews
short-lived certificates to any service account (e.g, a CI/CD server).

The primary commands for `tbot` are as follows:

| Command | Description |
| - | - |
| `tbot help` | Outputs guidance for using commands with `tbot`. |
| `tbot version` | Outputs the current version of the `tbot` binary. |
| `tbot configure` | Outputs a basic Machine ID client configuration file to be adjusted as needed. |
| `tbot start` | Starts the Machine ID client `tbot`, fetching and writing certificates to disk at a set interval. |
| `tbot init` | Initialize a certificate destination directory for writes from a separate bot user, configuring either file or POSIX ACL permissions. |
| `tbot db` | Connects to databases using native clients and queries database information. Functions as a wrapper for `tsh`, and requires `tsh` installation. |
| `tbot proxy` | Allows for access to Teleport resources on a cluster using TLS Routing. Functions as a wrapper for `tsh`, and requires `tsh` installation. |

### tbot start

Starts the Machine ID client `tbot`, fetching and writing certificates to disk at a set interval.

#### Flags

| Flag                 | Description                                                                                    |
|----------------------|------------------------------------------------------------------------------------------------|
| `-d/--debug`         | Enable verbose logging to stderr.                                                              |
| `-c/--config`        | Path to a Machine ID configuration file.                                                                  |
| `-a/--auth-server`   | Address of the Teleport Auth Server (on-prem installs) or Teleport Cloud tenant.               |
| `--token`            | A bot join token, if attempting to onboard a new bot; used on first connect. Can also be an absolute path to a file containing the token. |
| `--ca-pin`           | CA pin to validate the Teleport Auth Server; used on first connect.                            |
| `--data-dir`         | Directory to store internal bot data. In production environments access to this directory should be limited only to an isolated linux user as an owner with `0600` permissions. |
| `--destination-dir`  | Directory to write short-lived machine certificates.                                           |
| `--certificate-ttl`  | TTL of short-lived machine certificates.                                                       |
| `--renewal-interval` | Interval at which short-lived certificates are renewed; must be less than the certificate TTL. |
| `--join-method`      | Method to use to join the cluster. Can be `token` or `iam`.                                    |
| `--oneshot`          | If set, quit after the first renewal.                                                          |

#### Examples
<Tabs>
  <TabItem scope={["Cloud"]} label="Teleport Cloud">

```code
$ tbot start \
   --data-dir=/var/lib/teleport/bot \
   --destination-dir=/opt/machine-id \
   --token=00000000000000000000000000000000 \
   --join-method=token \
   --ca-pin=sha256:1111111111111111111111111111111111111111111111111111111111111111 \
   --auth-server=example.teleport.sh:443
```

  </TabItem>
  <TabItem scope={["Enterprise/OSS"]} label="Enterprise/OSS">

```code
$ tbot start \
   --data-dir=/var/lib/teleport/bot \
   --destination-dir=/opt/machine-id \
   --token=00000000000000000000000000000000 \
   --join-method=token \
   --ca-pin=sha256:1111111111111111111111111111111111111111111111111111111111111111 \
   --auth-server=auth.example.com:3025
```

  </TabItem>
</Tabs>

### tbot init

Initializes a certificate destination directory for access from a separate bot user. Allows for certificates to be written to disks other than a Machine ID client,
configuring either file or POSIX ACL permissions.

#### Flags

| Flag                | Description                                                                                                        |
|---------------------|--------------------------------------------------------------------------------------------------------------------|
| `-d/--debug`        | Enable verbose logging to stderr.                                                                                  |
| `-c/--config`       | Path to a Machine ID configuration file.                                                                                      |
| `--destination-dir` | Directory to write short-lived machine certificates to.                                                            |
| `--owner`           | Defines the Linux `user:group` owner of `--destination-dir`. Defaults to the Linux user running `tbot` if unspecified. |
| `--bot-user`        | Enables POSIX ACLs and defines the Linux user that can read/write short-lived certificates to `--destination-dir`. |
| `--reader-user`     | Enables POSIX ACLs and defines the Linux user that will read short-lived certificates from `--destination-dir`.    |
| `--init-dir`        | If using a config file and multiple destinations are configured, controls which destination dir to configure.      |
| `--clean`           | If set, remove unexpected files and directories from the destination.                                              |

#### Examples

**Example using file permissions.**

The following command highlights how to set permissions with `tbot` through Linux groups, using the user and group `jenkins:jenkins`.
If running `tbot` as the Linux user `root`, use the following invocation of
`tbot init` to initialize the short-lived certificate directory
`/opt/machine-id` with owner `jenkins:jenkins`.

```code
$ tbot init \
    --destination-dir=/opt/machine-id \
    --owner=jenkins:jenkins
```

**Example using POSIX ACLs.**

If running `tbot` as the Linux user `teleport`, use the following invocation of
`tbot init` to initialize the short-lived certificate directory
`/opt/machine-id` with owner `teleport:teleport` but allow `jenkins` to read
from `/opt/machine-id`.

```code
$ tbot init \
    --destination-dir=/opt/machine-id \
    --bot-user=teleport \
    --reader-user=jenkins
```


### tbot db

Connects to databases using native clients and queries database information. This is best used for testing and validation purposes;
most users will likely prefer to connect their own databases to a local proxy using `tbot proxy db`.

Note that `tsh` must be installed to make use of this command.

#### Flags

| Flag                | Description                                                                                              |
|---------------------|----------------------------------------------------------------------------------------------------------|
| `-d/--debug`        | Enable verbose logging to stderr.                                                                        |
| `-c/--config`       | Path to a Machine ID configuration file. Required if not using other required configuration flags.                  |
| `--destination-dir` | Path to the Machine ID destination dir that should be used for authentication. Required.                 |
| `--proxy`           | The `host:port` of the Teleport Proxy Service to use to access resources. Required.                      |
| `--cluster`         | The name of the cluster on which resources should be accessed. Extracted from the bot identity if unset. |

All other flags and arguments are passed directly to `tsh db ...`, along
with authentication parameters to use the Machine ID identity to skip `tsh`'s
login steps.

Note that certain CLI parameters, for example `--help`, may be captured by
`tbot` even if intended to be passed to the wrapped `tsh`. A `--` argument can
be used to ensure all following arguments are passed to `tsh` and ignored by
`tbot`.

Additionally, be aware of the following limitations of `tbot db`:
 - `tbot db connect` requires a `tbot db login` for certain database types,
   like MySQL, so that additional connection parameters can be written to a
   local configuration file.
 - `tbot db env` is not fully supported.

### tbot proxy

Allows for access to Teleport resources via a local TLS proxy in TLS Routing mode.
The `tbot proxy` command acts as a wrapper for `tsh proxy` to provide local proxy functionality for various protocols.

Note that `tsh` must be installed to make use of this command.

#### Flags

| Flag                | Description                                                                                              |
|---------------------|----------------------------------------------------------------------------------------------------------|
| `-d/--debug`        | Enable verbose logging to stderr.                                                                        |
| `-c/--config`       | Path to a Machine ID configuration file. Required if not using other required configuration flags.       |
| `--destination-dir` | Path to the Machine ID destination dir that should be used for authentication. Required.                 |
| `--proxy`           | The `host:port` of the Teleport Proxy Service through which resources will be accessed. Required.        |
| `--cluster`         | The name of the cluster on which resources should be accessed. Extracted from the bot identity if unset. |

All other flags and arguments are passed directly to `tsh proxy ...`, along
with authentication parameters to use the Machine ID identity to skip `tsh`'s
login step.

Additionally, the following should be noted:

- Certain CLI parameters, for example `--help`, may be captured by
`tbot` even if intended to be passed to the wrapped `tsh`. A `--` argument can
be used to ensure all following arguments are passed to `tsh` and ignored by
`tbot`
- If no configuration file is provided, `tbot` will apply a sample configuration based on provided CLI flags.
For this reason, it is recommended that settings are explicitly applied to a configuration file in production.

#### Examples

**Example using OpenSSH**

The following command forwards standard input and output over a proxy suitable for use as an OpenSSH `ProxyCommand` for SSH access:

```code
$ tbot proxy --destination-dir=./tbot-user --proxy=proxy.example.com:3080 ssh alice@node:3022
```

  In this case:
   - `alice` is the remote username
   - `node` is the Teleport Node name
   - `3022` is the remote SSH port, which is `3022` for Nodes running the Teleport
     SSH service.

**Example using Database Access**

The following example opens a local proxy server to the given database. Your database client
must still be configured with client TLS certificates:

```code
$ tbot proxy --destination-dir=./tbot-user --proxy=proxy.example.com:3080 db --port=1234 example
```

In this case:
 - `example` is the name of the database server as it exists in Teleport
 - `1234` is an arbitrary port on which to run the proxy

Though not recommended, to avoid the need for additional client authentication,
the `--tunnel` flag may be used to perform authentication at the local proxy
rather than within your client:

```code
$ tbot proxy --destination-dir=./tbot-user --proxy=proxy.example.com:3080 db --tunnel --port=1234 example
```

Note that this decreases security:
 - It allows any user on the system to access the database via `localhost`.
 - Your connection to the database will be unencrypted until it reaches the
   `tbot` proxy running on `localhost`.

Refer to the [database guide](../machine-id/guides/databases.mdx) for more information on
using database proxies.


#### Flags

| Flag                 | Description                                                                                    |
|----------------------|------------------------------------------------------------------------------------------------|
| `-d/--debug`         | Enable verbose logging to stderr.                                                              |
| `-c/--config`        | Path to a configuration file.                                                                  |
| `-a/--auth-server`   | Address of the Teleport Auth Server (on-prem installs) or Teleport Cloud tenant.               |
| `--token`            | A bot join token, if attempting to onboard a new bot; used on first connect. Can also be an absolute path to a file containing the token. |
| `--ca-pin`           | CA pin to validate the Teleport Auth Server; used on first connect.                            |
| `--data-dir`         | Directory to store internal bot data. In production environments access to this directory should be limited only to an isolated linux user as an owner with `0600` permissions. |
| `--destination-dir`  | Directory to write short-lived machine certificates.                                           |
| `--certificate-ttl`  | TTL of short-lived machine certificates.                                                       |
| `--renewal-interval` | Interval at which short-lived certificates are renewed; must be less than the certificate TTL. |
| `--join-method`      | Method to use to join the cluster. Can be `token` or `iam`.                                    |
| `--oneshot`          | If set, quit after the first renewal.                                                          |