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.
trakhound.package.jsonpackages folderth packages dotnet --publish builds and uploads in one step, as the next version on each destinationth deployments create / install move whole sets of Packages and configuration between Instancesth 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
--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 valueor--option=value. Some have short aliases (ex.-vfor--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 helpto list all commands, andth help <group> <command>for details on a command. - The exit code is
0on success,1if the command failed, and2if the command line was invalid.
CLI Settings
Settings are read from these sources, with later sources overriding earlier ones:
cli.config.yamlin the CLI's installation directory~/.trakhound/cli.config.yamlin the user directory- Environment variables
managementServer: https://packages.mycompany.com
organization: MyCompany
apiToken: ********
| Setting | Environment Variable | Description |
|---|---|---|
managementServer | TRAKHOUND_MANAGEMENT_SERVER | The default package server URL. The public TrakHound source (https://packages.trakhound.com) when not set |
organization | TRAKHOUND_ORGANIZATION | The default Organization |
apiToken | TRAKHOUND_API_TOKEN | The API Token sent to the package server, used to publish |
dotnetSdkLocation | TRAKHOUND_DOTNET_SDK | The directory containing the dotnet executable (if not on the PATH) |
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
| Command | Description |
|---|---|
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
| Command | Description |
|---|---|
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] --yes | Remove 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
| Command | Description |
|---|---|
th licenses keygen [name] --output | Create a key pair for issuing licenses. |
th licenses sign --product <id> --device <id> --limit --expires <yyyy-MM-dd>|--days <n>|--permanent --key | Issue a License Code. --any-device replaces --device, and the key can also come from TRAKHOUND_LICENSE_KEY. |
th licenses inspect <code> --public-key --product --device | Show what a License Code contains and check its signature, product, and device. |
th licenses device-id | Show 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).
| Command | Description |
|---|---|
th config list [path] --profile --category | List the configurations. |
th config get <category> <id> [path] | Print the YAML of a configuration. |
th config add <category> <file> [path] --id | Add a configuration from a YAML file, or replace the one with the same ID. |
th config set <category> <id> [path] --param --remove-param --property | Change 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-path | Check 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, andzone. - Set
packageVersionas well aspackageId: 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 validatereports 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:
| Command | Description |
|---|---|
th instance settings [path] --profile | Print 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
| Command | Description |
|---|---|
th dev run [path] --instance --profile --route --project-configuration --no-watch --keep | Build 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 --profile | Remove the configuration and dev versions that th dev run installed. |
th host create [path] --name --class-name --api-key | Create 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.