## Module 1: Getting Familiar with TiDB Cloud Filesystem

`ti` is the command name for the TiDB Cloud CLI. It provides a unified command-line entry point for managing various services on TiDB Cloud. It covers TiDB Cloud Filesystem and TiDB Cloud Starter.

```mermaid
---
title: Overview of Module Environment
---
flowchart LR
  subgraph region["Region aws-${LAB:REGION_CODE}"]
    style region stroke-dasharray: 5 5
    USER["Lab User"] --> TI["ti CLI"]
    TI -->|Manage by API Key| API["TiDB Cloud Filesystem"]
    TI -->|Mount/Use by FS Token| API["TiDB Cloud Filesystem"]
  end
```

This module aims to familiarize you with the TiDB Cloud CLI `ti` commands: install `ti`, configure a TiDB Cloud API Key, verify the connection, and get familiar with CLI help and output control. hermes-agent will join the workflow only in the next module.

### Step 1: Install TiDB Cloud CLI

- Click **[Terminal 1](ssh://monitor1-ssh#1)**. All subsequent commands in this module run in this shell as the `ubuntu` user.
- Download and install the TiDB Cloud CLI - `ti`.

```bash
curl -fsSL https://github.com/tidbcloud/ti-cli/releases/latest/download/install.sh | sh
export PATH="$HOME/.ti/bin:$PATH"
```

```output
...
  Docs: https://github.com/tidbcloud/ti-cli
```

- Add the `ti` command to your shell profile so you can use `ti` when you need to re-enter the terminal during the lab.

```bash
grep -qxF 'export PATH="$HOME/.ti/bin:$PATH"' "$HOME/.bashrc" || \
  echo 'export PATH="$HOME/.ti/bin:$PATH"' >> "$HOME/.bashrc"
```

- Check the TiDB Cloud CLI version. The version you install may be higher than the one shown in the sample output.

```bash
ti --version
```

```output
ti 0.2.1 (6b5d3f48e5b852d13906a592f64cac03b614eca9, 2026-08-11T09:07:43Z, linux/amd64)
```

### Step 2: Obtain a pair of TiDB Cloud API Keys

> [!IMPORTANT]
> In this step, you'll need access to a TiDB Cloud account. We recommend using your personal TiDB Cloud account instead of an organization's production account. All lab activities are designed to remain within TiDB Cloud's free-tier usage limits.

- Click [TiDB Cloud API Keys](https://tidbcloud.com/org-settings/api-keys). A new browser tab will open your TiDB Cloud Web Console. (If you are in the home page instead of **API Keys** page, find it under **Organization Settings**.)
- Click **Create API Key** in the upper right corner.
- Enter `lab-test` in **Description**, then click **Generate API Key**. You will get a pair of API Keys.
- Keep the page open and proceed to the next step.

### Step 3: Configure and get familiar with TiDB Cloud CLI

- In **[Terminal 1](ssh://monitor1-ssh#1)**, run the following command, set the "Default region code" to `aws-${LAB:REGION_CODE}`, then follow the wizard prompts to paste the Public Key and Private Key respectively.

> [!TIP]
> When you paste your private key, nothing will appear in the terminal, this is expected.

```bash
ti configure --region-code aws-${LAB:REGION_CODE}
```

```output
{
  "profile": "default",
  "region_code": "aws-${LAB:REGION_CODE}",
  "credentials_stored": true
}
```

- At this point, your `ti` CLI has the following default configuration:
  - Default region: aws-${LAB:REGION_CODE}
  - Credentials for managing TiDB Cloud services

> [!NOTE]
> In subsequent steps, although the ti CLI has already been configured with a default region, each command will still use the --region parameter to specify the region for clarity of intent.

- Try listing all file systems under the specified region. If there are no file systems in the TiDB Cloud account yet, an empty list is also a correct result.

```bash
ti fs list-file-systems --region aws-${LAB:REGION_CODE}
```

```output
{
  "region_code": "aws-${LAB:REGION_CODE}",
  "file_systems": []
}
```

- Get familiar with `ti`'s online help and do some casual exploration. The following forms cover all of `ti`'s help forms. `ti` has at most two levels of subcommands and will not have more levels.

```bash
# Get overall help for the TiDB Cloud CLI.
ti

# What services does TiDB Cloud CLI have and what global parameters can be used?
ti help

# What are the basic features of TiDB Cloud Filesystem?
ti fs help

# What are the basic features of TiDB Cloud Database?
ti db help

# How do you create a TiDB Cloud file system?
ti fs create-file-system help
```

- In the previous steps, we configured `ti` interactively. You can also do it non-interactively. Let's take a look. Observe the output, then continue.

```bash
ti configure help | grep -i 'non-interactive'
```

```output
[--non-interactive]
  --non-interactive                   Use this option to avoid being prompted for configuration values. You must provide at least three configuration values (--tidb-cloud-public-key, --tidb-cloud-private-key, and --region-code) when using this option. This is useful when running ti in a script or automated environment.
```

- When a resource-modifying command supports `--dry-run`, it displays the plan or validates the request without actually creating or modifying the resource. For example, the following command is for preview only and will not actually create a Filesystem:

```bash
ti fs create-file-system \
  --display-name lab-workspace \
  --dry-run --region aws-${LAB:REGION_CODE}
```

```output
{
  "dry_run": true,
  "command": "ti fs create-file-system",
  "operation": "create_file_system",
  .
  .
  .
    {
      "name": "remote_mutation",
      "status": "skipped",
      "message": "dry-run stopped before sending a mutating remote request"
    }
  ]
}
```

### Step 4: Create a file system

- Use `ti fs create-file-system` to create a new file system.
- Commands that create resources all have a `--wait` flag, which instructs the current workflow to confirm the resource is in a service-ready state before continuing to the next operation, facilitating orchestration. We will use this in subsequent steps.
- Additionally, as you may have already noticed, `ti` defaults to JSON output format, which is suitable for further parsing by scripts; you can use `--query` to select fields from the JSON result via JMESPath. You can also use `--output text` to adjust to a format more suitable for human reading.
- Let's create a new file system and capture the `fs_token` and `file_system_id` field values from the response in variables. `fs_token` **(assigned to** `LAB_FS_TOKEN`**)** is the **unique identifier** of the file system as well as the usage **credential**; `file_system_id` **(assigned to** `LAB_FS_ID`**)** is the unique identifier of the file system but does NOT include the usage credential.

> [!TIP]
> If this is your first time creating a TiDB Cloud file system, the process may take up to 1 minute. Please be patient.

```bash
read LAB_FS_ID LAB_FS_TOKEN <<< "$(ti fs create-file-system \
  --display-name lab-workspace \
  --region aws-${LAB:REGION_CODE} \
  --wait \
  --query "join(' ', [file_system_id, fs_token])" \
  --output text \
  )"
```

- After the command returns, check the `fs_token` of the newly created file system. Your result will definitely differ from the sample.

```bash
echo $LAB_FS_TOKEN
```

```output
drive9_ZXlKaGJHY2lPaUpJV
.
.
.
SzBmUXNtT19rbEZvTjlwZm15
```

- Check the `file_system_id` of the newly created file system. Your result will definitely differ from the sample.

```bash
echo $LAB_FS_ID
```

```output
cd06d327-06ca-4355-9ce5-4bf3cac76bed
```

### Step 5: Mount the file system

- Create an empty directory in preparation for mounting.

```bash
mkdir ~/mnt-module1
```

- As long as you have the `fs_token`, you have access to the corresponding file system. Use `mount` with the `--fs-token` parameter to mount the newly created file system. Let's use the `$LAB_FS_TOKEN` environment variable saved in the previous steps.

```bash
# Provide the file system token as a parameter when mounting
ti fs mount --region aws-${LAB:REGION_CODE} --mount-path ~/mnt-module1 \
  --fs-token $LAB_FS_TOKEN
```

```output
{
  "status": "mounted",
...
  },
  "write_back_cache": true
}
```

- Use `ti fs umount` to umount the file system. Try it now.

```bash
ti fs umount --mount-path ~/mnt-module1 
```

```output
{
  "status": "unmounted",
  "mount_path": "/home/ubuntu/mnt-module1"
}
```

- Mount again, this time using the `$TI_FS_TOKEN` variable to mount the newly created file system. Note that the `ti` command is sensitive to the environment variable name `$TI_FS_TOKEN`, so you do not need to use the `--fs-token` parameter.

```bash
# Provide the file system token as the TI_FS_TOKEN environment variable when mounting; --fs-token can be omitted 
export TI_FS_TOKEN=$LAB_FS_TOKEN
ti fs mount --region aws-${LAB:REGION_CODE} --mount-path ~/mnt-module1
```

```output
{
  "status": "mounted",
...
  },
  "write_back_cache": true
}
```

- Use the directory mounted with TiDB Cloud Filesystem just like a regular directory. For example, save a text file.

```bash
echo "Hello TiDB Cloud FS" > ~/mnt-module1/hello-world.txt
cat ~/mnt-module1/hello-world.txt
```

```output
Hello TiDB Cloud FS
```

- Unmount the directory again.

```bash
# Unmount the directory
ti fs umount --mount-path ~/mnt-module1
```

```output
{
  "status": "unmounted",
  "mount_path": "/home/ubuntu/mnt-module1"
}
```

### Step 6: Prepare file system credentials for the Hermes Agent environment

<!-- markdownlint-disable MD032 -->
> [!IMPORTANT]
> - The `ti fs mount` command only requires the file system token. That is, if your `ti` CLI has not been pre-configured with a TiDB Cloud API Key, as long as you can provide the file system token and the file system's region, the mount will succeed.
> - This means that in such an environment you cannot manage TiDB Cloud Filesystem, but you can use a specific TiDB Cloud Filesystem. Such environments are common in the real world, for example an agent's sandbox.

- You only need to pass the `$TI_FS_TOKEN` variable and `$TI_REGION_CODE` to the Hermes environment. Run the following commands to complete this step.

```bash
echo TI_REGION_CODE=aws-${LAB:REGION_CODE} >> ~/.hermes/.env
echo TI_FS_TOKEN="$LAB_FS_TOKEN" >> ~/.hermes/.env
```

- Confirm that the `TI_` variables are in place in the `.hermes/.env` file.

```bash
grep TI_.*= ~/.hermes/.env
```

```output
TI_REGION_CODE=aws-${LAB:REGION_CODE}
TI_FS_TOKEN=XXXXXXXXXXXXXXXXXXXXX
```

- Clean up environment variables that are no longer needed.

```bash
unset LAB_FS_TOKEN LAB_FS_ID TI_FS_TOKEN
```

### Step 7: Module summary

- You have gained a preliminary understanding of how to use the TiDB Cloud CLI `ti`.
- You created a new TiDB Cloud file system and configured its usage credentials into the Hermes Agent's environment variable file.
- In future practical use, if you lose the `fs_token` of an existing file system, you can use `ti fs generate-file-system-token` to generate a new one, and use `ti fs enable-/disable-/delete-file-system-token` for rotation. A file system can have multiple `fs_token`.
- In the next module, the Agent will also learn how to use the `ti` CLI; it will fully master the use of `ti` in an instant.

Please proceed to the next module.