Skip to content

Home

Jump to bottom
Mythic edited this page Nov 9, 2021 · 14 revisions

Thunderstore CLI (tcli) is a command line tool for building and uploading game mod packages to the Thunderstore mod database.

Authentication

A Thunderstore API token is required to publish packages with tcli. To acquire an API token:

  1. Log in to thunderstore.io
  2. Navigate to your team page: Settings > Teams > [Your team name]
  3. From the left sidebar, select Service Accounts
  4. Select Add service account and fill the name of the account into the form
  5. The API token is shown on the following confirmation page

An API token is required only for the publish command. There's two ways to configure it:

  1. Set it as TCLI_AUTH_TOKEN environment variable (e.g. for GitHub Actions)
  2. Pass it as a parameter to the command: tcli publish --token tss_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

If both methods are used, the command parameter takes precedence.

Installation

tcli doesn't currently support installation. Instead, pre-built single-file executables are distributed for each release on Releases page under the Assets section.

Initiation

To initiate a package, run tcli init in the project root. This creates three files in the current directory:

  • icon.png, which will be used as the package's icon on thunderstore.io
    • This is a boring default icon, so preferably replace it with something unique and suitable for your package
  • README.md, which will be included in the package and shown on the package's page on thunderstore.io
  • thunderstore.toml which is a configuration file for your package
    • This contains placeholder values which should be updated manually

For full list or parameters run tcli init --help

Building

To build a package run tcli build in a initiated package directory. By default, all the values are read from thunderstore.toml, but some values can be overwritten with parameters.

Currently the build command only supports creation of zip files from files already existing on the filesystem based on the mappings provided in thunderstore.toml. In other words, any actual build actions (e.g. building the c# project for your mod) bust be performed separately.

For full list or parameters run tcli build --help

Publishing

To build and publish a package run tcli publish in a initiated package directory (thunderstore.toml bust be present and configured). To publish a package, you must authenticate with an API token.

Currently publishing a package requires at least a single community where to publish the package to be specified. You can access a full list of communities and their identifiers from the API at https://thunderstore.io/api/experimental/community/.

Example community configuration in thunderstore.toml:

[publish]
repository = "https://thunderstore.io"
communities = ["riskofrain2"]
categories = []

It is not required to use a community specific subdomain as the repository setting when publishing; you can use the main domain (https://thunderstore.io/) for all communities. It is possible to change the repository to an entirely different instance such as the Thunderstore development environment: https://thunderstore.dev/. Categories however are only applied for the community residing in the domain the repository option points to.

A list of categories that should be included when publishing can also be configured, however it is not required and an empty list of categories will not remove any existing categories on the package. The values should be the slug of each category (as opposed to name), and you can find all categories for each community via the API. As an example, Risk of Rain 2 categories can be found from https://thunderstore.io/api/experimental/community/riskofrain2/category/. Refer to the API Docs for more details.

A previously built package can be published with the --file parameter.

For full list of parameters run tcli publish --help

Clone this wiki locally