CLI

Build, publish, and install Packages and Deployments with the TrakHound CLI (th).
Framework Docs Menu

The TrakHound CLI (th) creates, packs, publishes, and installs Packages, and creates and installs Deployments. It uses the dotnet CLI to build Package projects, so the .NET SDK must be installed.

ProjectYour code and trakhound.package.json
packages dotnet
.thp FileOne Package version
packages push
Package SourceA package server, ex. your own Instance
packages install
InstanceIts packages folder
th packages dotnet --publish builds and uploads in one step, as the next version on each destination
th deployments create / install move whole sets of Packages and configuration between Instances
In Visual Studio, Publish TrakHound Package runs th packages dotnet --publish for you.

Installation

Windows

Download and run the TrakHound CLI installer.

Linux (Snap)

sudo snap install dotnet-sdk --classic
sudo snap install trakhound-cli --devmode
sudo snap alias trakhound-cli th
The Snap is installed with --devmode because the CLI needs access to the .NET SDK directory.

Usage

th <group> <command> [parameters] [--option value] [--flag]
  • Parameters are positional and come first.
  • Options start with -- and can be given in any order, as --option value or --option=value. Some have short aliases (ex. -v for --version), and camel case also works (ex. --projectConfiguration).
  • Flags (true/false options) are set by including the option without a value (ex. --publish).
  • Run th help to list all commands, and th help <group> <command> for details on a command.
  • The exit code is 0 on success, 1 if the command failed, and 2 if the command line was invalid.

CLI Settings

Settings are read from these sources, with later sources overriding earlier ones:

  1. cli.config.yaml in the CLI's installation directory
  2. ~/.trakhound/cli.config.yaml in the user directory
  3. Environment variables
managementServer: https://packages.mycompany.com
organization: MyCompany
apiToken: ********
SettingEnvironment VariableDescription
managementServerTRAKHOUND_MANAGEMENT_SERVERThe default package server URL. The public TrakHound source (https://packages.trakhound.com) when not set
organizationTRAKHOUND_ORGANIZATIONThe default Organization
apiTokenTRAKHOUND_API_TOKENThe API Token sent to the package server, used to publish
dotnetSdkLocationTRAKHOUND_DOTNET_SDKThe directory containing the dotnet executable (if not on the PATH)
A package server is any server running the Packages API (TrakHound.Packages.Api), for example another Instance (see Self-Hosting Packages). The setting keeps its earlier name, managementServer, in cli.config.yaml and trakhound.package.publish.json. A destination with its own apiTokenVariable uses that environment variable's token instead of apiToken.

Packages

CommandDescription
th packages list [path] --category <category> List the installed Packages.
th packages install [packageId] --version <version> --path <path> --server <url> --organization <org> Download and install a Package and its dependencies. If no version is given, the latest version is installed. --configure [--profile] [--group <id>] also adds the default configuration for each Package that doesn't have one, and puts it in a Group (created if it doesn't exist).
th packages verify [packageId] --file --version --path --profile --require-signature Check that a Package's files match its manifest, and who signed it. Exits with an error if a Package fails or has no manifest. --require-signature also fails a Package without a trusted signature.
th packages rebuild <file.thp> --repository --project --allow-untrusted --path --profile Clone the commit recorded in a Package, build it again, and compare the files.
th packages keygen [name] --output Create a key pair for signing Packages.
th trust list|add|remove --path --profile Manage the publishers a configuration profile trusts. th trust add <public-key-file> --name <name> --prefix <id-start> limits a publisher to Package IDs that start with a prefix (see Signing and Verification).
th packages install --file <file.thp> --path <path> --no-dependencies Install a local Package file. Its dependencies are downloaded from the package server unless --no-dependencies is set.
th packages uninstall <packageId> --version <version> --path <path> Uninstall a Package.
th packages dotnet [path] --output <path> --project-configuration <Release> --include-debug-symbols --include-source --publish --target <name> --version <version> --version-suffix <label> --skip-existing --server <url> --organization <org> --sign-key <path> --allow-dirty Build a .NET project into a Package. The version is the manifest's prefix plus the git height (see Versions from Git). With --publish, the Package is published to the Publish Target (--target, or the file's defaultTarget); otherwise it is written to the output directory. --version-suffix adds a prerelease label.
th packages build [path] --only --project --fail-fast --dry-run --target --version-suffix --skip-existing Build (and optionally publish) every project listed in a trakhound.build.json file, after the projects their Package depends on. Nothing is published unless every project builds. --project picks one project by name, and --dry-run lists the projects in build order with their settings.
th packages pack <path> --configuration <config> --category <category> --id <id> --version <version> --version-suffix <label> --description <text> --publisher <name> --output <path> Create a Package from a directory.
th packages publish [path] --configuration --category --id --version --version-suffix --description --publisher --server --organization --target --skip-existing Create a Package from a directory and publish it.
th packages push <path> --server <url> --organization <org> Upload an existing Package file to a package server.
# Build the project in the current directory and publish it to the default Publish Target
th packages dotnet --publish

# Publish to the release Target
th packages dotnet --publish --target release

# Install a Package
th packages install TrakHound.Packages.Api

# Install a specific version
th packages install TrakHound.Packages.Api --version 1.2.0

# Install a local Package file
th packages install --file ./out/MyCompany.Example.Api-1.0.3.thp

A running Instance watches its packages folder, so a Package installed into its folder with --path is picked up within a few seconds, without a restart.

Visual Studio

The CLI installer also installs a Visual Studio extension. Right-click a Package project in Solution Explorer (or open the Tools menu) and choose Publish TrakHound Package. It runs th packages dotnet --project-configuration Release --publish and shows the output in the TrakHound output pane. Publish TrakHound Packages... finds the trakhound.build.json files in and near the solution folder, lets you pick the projects, and runs th packages build for them.

Deployments

CommandDescription
th deployments create <profileId> [path] --version <version> --output <path>Create a Deployment from a root directory.
th deployments install <file.thd> [path]Install a Deployment from a local .thd file.
th deployments clean [path] --yesRemove the installed Packages, configurations, packages file, and deployment file from a directory (asks to confirm unless --yes is set).

Deployments are only installed from files: an Instance doesn't download them from a server. Copy a .thd file to the Instance, or put it in the Instance's deployments folder to install it when the Instance starts.

Licenses

CommandDescription
th licenses keygen [name] --outputCreate a key pair for issuing licenses.
th licenses sign --product <id> --device <id> --limit --expires <yyyy-MM-dd>|--days <n>|--permanent --keyIssue a License Code. --any-device replaces --device, and the key can also come from TRAKHOUND_LICENSE_KEY.
th licenses inspect <code> --public-key --product --deviceShow what a License Code contains and check its signature, product, and device.
th licenses device-idShow this machine's Device ID.

See Licensing Your Own Package.

Configuration

The config commands add, change, remove, and check the configurations and Configuration Variables of a profile, so an Instance can be set up from a script. path is the Instance's root directory and --profile is the configuration profile (default when not set).

CommandDescription
th config list [path] --profile --categoryList the configurations.
th config get <category> <id> [path]Print the YAML of a configuration.
th config add <category> <file> [path] --idAdd a configuration from a YAML file, or replace the one with the same ID.
th config set <category> <id> [path] --param --remove-param --propertyChange a configuration's parameters or properties (ex. packageId, routerId). It's created if it doesn't exist.
th config remove <category> <id> [path]Remove a configuration.
th config validate [path] --package-pathCheck the profile for problems that stop configurations from loading, and exit with 1 if it finds errors.
th config variables [path]List the Configuration Variables.
th config set-variable <name> <value> [path], th config remove-variable <name> [path]Add, change, or remove a Configuration Variable.
  • The categories are api, app, function, group, identity, router, service, worker, and zone.
  • Set packageVersion as well as packageId: the Instance doesn't load a configuration without a version. Use * for the latest installed version.
  • Secret parameters and variables are encrypted with the Instance's key (config/.secretkey), so run the commands against the Instance's own directory. On Linux, run them as the service user (ex. sudo -u trakhound th config list /var/lib/trakhound/instance).
  • A running Instance applies configuration changes within a few seconds. Configuration Variables are read when it starts, so restart it after changing them.
  • th config validate reports unreadable files, missing or duplicate IDs, Packages or versions that aren't installed, unknown Routers, undefined variables, secrets that can't be decrypted, invalid ports, and Groups and Zone members that aren't configured.
th config set worker my-worker ./instance --property packageId=MyCompany.MyWorker --property packageVersion='*' --param interval=5000
th config set-variable dbHost sql01 ./instance
th config validate ./instance

Instance Settings

The instance commands read and change the settings in instance.config.yaml, such as its ports, trusted proxies, and which interfaces it serves:

CommandDescription
th instance settings [path] --profilePrint the settings.
th instance get <name> [path]Print a setting.
th instance set <name> <value> [path]Change a setting. Use . for nested settings (ex. rateLimits.api.permitLimit) and commas for lists (ex. th instance set trustedProxies 127.0.0.1,10.0.0.0/8).

Names are the keys in instance.config.yaml (see Instances). If the file doesn't exist yet, set creates it with the defaults. A setting can reference a Variable (ex. httpPort: ${port}): get prints the reference, and th config validate warns about references it can't resolve. The Instance reads the file when it starts, so restart it to apply a change.

th instance set httpPort 8080 ./instance
th instance get httpPort ./instance

Development

CommandDescription
th dev run [path] --instance --profile --route --project-configuration --no-watch --keepBuild the project, install it in a local Instance with a configuration (dev-<packageId>), and reinstall it each time you save. Ctrl+C removes the configuration and the dev versions unless --keep is set.
th dev clean [path] --instance --profileRemove the configuration and dev versions that th dev run installed.
th host create [path] --name --class-name --api-keyCreate a standalone host project next to an Api, Worker, or Function project. --api-key generates an API key for an Api host.

--instance is the Instance's root directory, or set the TRAKHOUND_DEV_INSTANCE environment variable. See Debugging & Testing and Standalone Hosts.