tmc

Thing Model Catalog CLI

Find, use and contribute device descriptions for industrial IoT devices!

⚠ This software is experimental and may not be fit for any purpose.

The Thing Model Catalog Command Line Client, or tmc for short, is a tool for browsing, consuming, contributing and serving Thing Models specified by WoT Thing Description standard.

Read our Documentation for more.

Installation

Prebuilt

Download binary from releases page or

go install github.com/wot-oss/[email protected]

From Source

Run go install to install tmc to your install path. You can find the install path by running go list -f '{{.Target}}'. Switch to the install path folder and run the binary.

Quick Start

We recommend you to start with the Command Line Interface (CLI) so that you can add a TM repository. Once that is done, you can use TMC over its REST API.

Configure Autocompletion (Optional)

1. Read the help of the completion command to find out which shells are supported

   tmc completion -h
   

2. Follow the instructions of the shell-specific help text

   tmc completion <shell> -h
   

Browse the Example Catalog

We provide an example repository for you to get acquainted with tmc. The following commands assume that you use the example repository. If your organization hosts a TM catalog as a default, you must change the commands accordingly.

Configure the Example Repository

tmc repo add -t http example https://raw.githubusercontent.com/wot-oss/example-catalog/refs/heads/main

List the Contents of the Example Repository

tmc list

The listed names are formatted as follows

<author>/<manufacturer>/<model>[/<optional-path>]

You can specify a part of that path after the list command to filter the list for only parts of the list tree ( use tab to auto-complete path parts):

tmc list omnicorp/omnicorp

There are also other options to list a subset of available TMs from a catalog. See tmc list -h for details.

List Versions

Every model entry in the list may contain multiple versions, reflecting the evolution of the Thing Model (bugfixes, additions, changes in the device itself ...). List the available versions with the versions command:

tmc versions omnicorp/omnicorp/lightall

Fetch a Thing Model

Like what you see? Fetch and store locally using the fetch command. It will print the Thing Model to stdout to enable unix-like piping:

tmc fetch omnicorp/omnicorp/lightall/v2.0.1-20241008124326-8c75753996b3.tm.json

If you specify just the name, the CLI will fetch the latest version automatically.

tmc fetch omnicorp/omnicorp/lightall

You can fetch the latest TM matching a specific semantic version or part of it by adding the version to the TM name, separated by a colon. For example, all the following commands fetch the same version 'v2.0.1'.

tmc fetch omnicorp/omnicorp/lightall:v2
tmc fetch omnicorp/omnicorp/lightall:v2.0
tmc fetch omnicorp/omnicorp/lightall:v2.0.1

To store the Thing Model locally instead of printing to stdout, specify the -o flag and point it to a directory:

tmc fetch omnicorp/omnicorp/lightall-mk2 -o .

REST API

Almost all of the TMC functionality is available over a REST API. You can find ths OpenAPI definition at api/tm-catalog.openapi.yaml. Please read our documentation to learn more.

License