> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thistle.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Started: File Update

> How to update a single file with Thistle

This guide will show you the implest use case applicable to the Thistle: how
to update a single file. You may run the update client directly on a
desktop/laptop computer (Linux, macOS, or Windows) as it will run in the same
manner on an embedded device.

## Tools needed

* Version 1.6.0 (or above) of TUC and TRH for your platform
  * The [Thistle Update Client](/binaries#thistle-update-client-tuc): A binary
    to run on the device side to obtain the latest OTA update
  * The [Thistle Release
    Helper](/binaries#release-helper-trh): A CLI developer
    tool to prepare and publish OTA releases
  * One may also try out TUC and TRH on a web browser using
    [Thistle OTA update demo](https://demo.thistle.tech)
* On the [Thistle Control Center App](https://app.thistle.tech/projects). Visit
  the settings section of a project to obtain the API token ("Project Access
  Token") to be used as `THISTLE_TOKEN` in the configuration step below.

<img src="https://mintcdn.com/thistletechnologies/MrBm0BC7xpW_ySdM/images/project_access_token.png?fit=max&auto=format&n=MrBm0BC7xpW_ySdM&q=85&s=1129e068e7bcd14eef517b02cf3474fa" alt="Project's Access Token" width="1394" height="637" data-path="images/project_access_token.png" />

## TRH configuration and initialization

Configure your Thistle project's access token for TRH

<Tabs>
  <Tab title="Bash">
    ```bash theme={"dark"}
    $ export THISTLE_TOKEN=$(cat)
    (paste access token, press enter, then ctrl-d)
    $ ./trh --signing-method="remote" init
    ```
  </Tab>

  <Tab title="Windows PowerShell">
    ```bash theme={"dark"}
    # Set up your project's access token - Windows PowerShell
    $ $env:THISTLE_TOKEN = "[Access Token Obtained from Thistle App's Project Settings section]"

    $ .\trh.exe --signing-method="remote" init
    ```
  </Tab>
</Tabs>

First we initialize the local development environment by executing the `init`
command. This creates a Cloud-KMS-backed OTA update bundle signing key pair on
the Thistle backend, and an OTA update manifest file `manifest.json` locally in
the current directory, if they do not exist. If they already exist, the public
key portion of the key pair and the latest manifest file will be obtained.

<Note>
  Your local working environment is now ready.
</Note>

## What's in an update

We will now package our first update. For the purpose of this test, the update will contain a single binary called `my_app`, that will be installed at path `/tmp/my_app`. Complete "rootfs" system update are also possible using similar commands. Updates are defined by manifest files, they contain the assets' definition and a cryptographic signature.

```bash theme={"dark"}
$ mkdir -p ./example
$ echo "hello world" > ./example/my_app

# my_app will be installed on target system at /tmp/my_app
$ ./trh --signing-method="remote" prepare --target="./example" --file-base-path="/tmp"
```

Upon success, `manifest.json` will be amended and signed for the OTA release.

## Upload and test deployed release

Now that we have prepared the update bundle, we can use the `trh` tool to upload the release and its assets.

```bash theme={"dark"}
$ ./trh --signing-method="remote" release
```

With the OTA update artifacts and manifest uploaded to the Thistle Backend, we
are now ready to run the Thistle Update Client (TUC) to fetch and install the
OTA update on a device.

First generate a device configuration file `config.json` for group enrollment
(cf. [Group Enrollment](../device_provisioning#group-enrollment)).

```bash theme={"dark"}
./trh --signing-method="remote" gen-device-config \
--device-name="my-demo-device" \
--enrollment-type="group-enroll" \
--persist="${HOME}/thistle-ota"
```

The above command generates `config.json` in the current directory. It
configures the client to store persistent data between device reboots in path
`~/thistle-ota/`. Place `config.json` on a device to receive the OTA update, and
run TUC with this configuration. In this guide we will run TUC on the same
machine where TRH is run.

```bash theme={"dark"}
./tuc -c ./config.json
# by default the TUC continues running. Use ctrl-C to exit from it.

# verify installation below
$ cat /tmp/my_app
hello world
```

<Note>
  You can confirm your file was installed as defined by looking at the install path /tmp/my\_app.
</Note>

## Upload a new update bundle

To update the manifest we just released with newer content, we need to re-run
the `prepare` and `release` commands. All the devices using the device
configuration file `config.json` will then receive this update.

```bash theme={"dark"}
echo "hello new world" > ./example/my_app
./trh --signing-method="remote" prepare --target="./example" --file-base-path="/tmp"
./trh --signing-method="remote" release
```

## More options

In this get started guide, we explained the usage of the Thistle Update Client
alongside the Thistle Release Helper to perform updates on a single file - and
many more use cases are supported!

* [AI model update, with provenance](/update/get_started/ai_model_update_signed_model)
* [AI model update, end-to-end encrypted model](/update/get_started/ai_model_update_encrypted_model)
* [Encrypted OTA update](/update/get_started/encrypted_ota_file_update)
* [A/B tested Raspberry Pi 4 update support](/hardware/raspberry_pi/rpi4_ota_ab_update)
* Support for pre & post install scripts
* OTA bundle signing using external signing tools
  * [With YubiKey-protected signing key](https://github.com/thistletech/trh-y)
  * [With GCP-KMS-backed signing key](https://github.com/thistletech/trh-k)