Command Line Tools

Two command line tools are offered, both to help package the update bundles, and to install them. The update client is designed to apply updates to a given device safely and securely. It only accepts a subset of manual command line operations, as it receives its operating instructions from the Thistle Backend, as defined by update manufacturers.

The Thistle Release Helper is here to assist with the packaging of updates. This helper program will help with creating new configuration files for devices, as well as manifest files - defining the update itself. Uploading assets is also possible directly from this tool.

Update Client Usage

$ tuc --help
Thistle Update Client (TUC) 0.1.10
TUC is responsible for downloading, verifying, and applying file updates & root filesystem updates
to embedded platforms, as well as managing all communications with Thistle's backend.

Refer to https://docs.thistle.tech/ for more information

USAGE:
    tuc [OPTIONS] [SUBCOMMAND]

OPTIONS:
    -h, --help                     Print help information
    -c, --config <CONFIG>          Set configuration file path. [default: config.json]
        --log-file <LOG_FILE>      Set optional log file path.
        --log-level <LOG_LEVEL>    Set logging level. Possible values are 'trace', 'info', 'warn',
                                   and 'error'. [default: error]

SUBCOMMANDS:
    help       Print this message or the help of the given subcommand(s)
    install    Install a manifest from a local file or a URL

In normal circumstances, the Thistle Update Client will be executed simply with a configuration file. The install subcommand can be helpful to locally test out a single given manifest file, as it makes it accepts local paths.

Thistle Release Helper Usage

$ trh --help
Thistle Release Helper (TRH) 0.1.11
Manage Thistle assets, updates and developer workflow.

Examples:
    Initialize:                  ./trh init
    Prepare assets:              ./trh prepare --target=file-or-filetree
    Upload and release assets:   ./trh release

USAGE:
    trh [OPTIONS] [TOKEN] <SUBCOMMAND>

ARGS:
    <TOKEN>    Credentials used to authenticate against Thistle's Backend
                [env: THISTLE_TOKEN=]

OPTIONS:
    -s, --secret-key <SECRET_KEY>
            Path to secret key used for signing assets
             [env: THISTLE_KEY=] [default: ~/.minisign/minisign.key]

    -p, --password <PASSWORD>
            Password used to protect secret key. If none provided, user will be prompted
             [env: THISTLE_KEY_PASS=]

        --external-sign <EXTERNAL_SIGN>
            External signing command to use

    -m, --manifest-path <MANIFEST_PATH>
            Path used to fetch manifest
             [default: ./manifest.json]

    -h, --help
            Print help information

    -V, --version
            Print version information

SUBCOMMANDS:
    init             Initialize a new Thistle update manifest and configuration
    prepare          Prepare manifest with assets indicated
    release          Release manifest to Thistle Backend
    fetch-current    Fetch current manifest
    identity         Generate a device specific identity file

Init subcommand

init is used to initialize a working environment. This command will fetch a new device_enrollment_token from the Thistle Platform Backend using the authentication token. In addition, the pre-enroll option will automatically enroll a new device with the Thistle Backend and append the enrollment credentials into the newly created configuration file.

If no signing key is available at the given path (default ~/.minisign/minisign.key) a new keypair will be generated.

# initialize a new device, setting `/tmp/persist` as reboot-persistent directory on device
$ ./trh init -p="/tmp/persist"

Prepare subcommand

The prepare subcommand packages the indicated target, compresses it, adds it to the manifest, and signs this manifest with the private key.

More options are available to add pre and post install scripts. See trh --help for more information related to the supported options.

# prepare the manifest with a filesystem tree under /path/to/dir. When `--file-base-path` is
# not present, the filesystem tree which will be installed on-device to a path
# relative to the directory where `tuc` is executed.
$ ./trh prepare --target=/path/to/dir

# prepare the manifest with a filesystem tree under /path/to/dir.  When `--file-base-path` is
# present, the filesystem tree is installed on-target under /opt/project.
$ ./trh prepare --target=/path/to/dir --file-base-path=/opt/project

# prepare the manifest with a single rootfs
$ ./trh prepare --target=rootfs.img

Release subcommand

The release subcommand publishes the assets previously prepared, amends the manifest with the new remote URLs, resigns this manifest, and uploads it according to the supplied authenticated token.

Note that this command will automatically increase the release version in the manifest, and update the timestamp.

# upload assets and manifest
$ ./trh release

Fetch-current subcommand

This subcommand can be used to fetch the latest manifest the Thistle Backend is currently holding for a given THISTLE_TOKEN. The manifest will be fetched and written on disk at the specified path.

# fetch current manifest for a given
$ ./trh fetch-current

Identity subcommand

This subcommand helps create an identity file. If the pre-enroll option is used, a device will be pre-enrolled with the Thistle Backend and the enrollment credentials will be appended in the identity file.

# Enroll a device with Thistle & create an identity file with the new credentials
$ ./trh identity --device-name "tutorial" --pre-enroll