Skip to content

Home

Jump to bottom
Joe Clack edited this page Dec 4, 2023 · 14 revisions

!! TCLI is currently a pre-release !!

TCLI is currently in a pre-release stage and might change drastically without warning

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

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.

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.

Commands

You can view the full list of commands by running tcli help:

$ tcli --help
tcli 0.1.0
Copyright (C) 2021 Thunderstore

  init       Initialize a new project configuration

  build      Build a package

  publish    Publish a package. By default will also build a new package.

  help       Display more information on a specific command.

  version    Display version information.

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:

$ tcli init --help
tcli 0.1.0
Copyright (C) 2021 Thunderstore

  --overwrite            (Default: false) If present, overwrite current configuration

  --config-path          (Default: ./thunderstore.toml) Path for the project configuration file

  --package-name         Name for the package

  --package-namespace    Namespace for the package

  --package-version      Version number for the package

  --help                 Display this help screen.

  --version              Display version information.

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) must be performed separately.

For full list or parameters run tcli build --help:

$ tcli build --help
tcli 0.1.0
Copyright (C) 2021 Thunderstore

  --config-path          (Default: ./thunderstore.toml) Path for the project configuration file

  --package-name         Name for the package

  --package-namespace    Namespace for the package

  --package-version      Version number for the package

  --help                 Display this help screen.

  --version              Display version information.

Publishing

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

Make sure namespace has been set in thunderstore.toml to match the team you're uploading to!!

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:

[general]
repository = "https://thunderstore.io"

[publish]
communities = ["riskofrain2"]

[publish.categories]
riskofrain2 = [ "artifacts", "skills" ]

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 for each community can also be configured. Similar to above, the values should be the slug of each community 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:

$ tcli publish --help
tcli 0.1.0
Copyright (C) 2021 Thunderstore

  --file                 If provided, use defined package instead of building.

  --token                Authentication token to use for publishing.

  --repository           URL of the repository where to publish.

  --config-path          (Default: ./thunderstore.toml) Path for the project configuration file

  --package-name         Name for the package

  --package-namespace    Namespace for the package

  --package-version      Version number for the package

  --help                 Display this help screen.

  --version              Display version information.

GitHub Actions

As of now, there is no official GitHub action provided, but a community contribution can be found here: https://github.com/GreenTF/upload-thunderstore-package

Community contributions aren't governed nor actively reviewed by the Thunderstore dev team and as such make sure to thoroughly review them before use

Clone this wiki locally