# CLI

> Build, publish, and install Packages and Deployments with the TrakHound CLI (th).

URL: https://www.trakhound.com/docs/trakhound-framework/cli

The TrakHound CLI (`th`) creates, packs, publishes, and installs Packages, and creates and installs Deployments. It uses the [dotnet CLI](https://learn.microsoft.com/en-us/dotnet/core/tools/) to build Package projects, so the .NET SDK must be installed.

Diagram: th packages dotnet builds a project into a .thp Package file, or with --publish builds and uploads it. th packages push uploads an existing file. th packages install downloads a Package and its dependencies from a source, or installs a local file, into an Instance folder. th deployments create and install move whole sets of Packages and configuration.

## Installation

### Windows

Download and run the [TrakHound CLI installer](https://applications.trakhound.com/TrakHound.CLI/latest/download?prerelease=true&source=website).

### 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: ********
```

| 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) |

> A package server is any server running the Packages API (`TrakHound.Packages.Api`), for example another Instance (see [Self-Hosting Packages](https://www.trakhound.com/docs/trakhound-framework/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](https://www.trakhound.com/docs/trakhound-framework/packages#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](https://www.trakhound.com/docs/trakhound-framework/packages#package-versions)). With `--publish`, the Package is published to the [Publish Target](https://www.trakhound.com/docs/trakhound-framework/packages#publish-targets) (`--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](https://www.trakhound.com/docs/trakhound-framework/configuration#startup-deployments).

## 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](https://www.trakhound.com/docs/trakhound-framework/packages#licensing-a-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`, 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:

| 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](https://www.trakhound.com/docs/trakhound-framework/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](https://www.trakhound.com/docs/trakhound-framework/debugging) and [Standalone Hosts](https://www.trakhound.com/docs/trakhound-framework/standalone-hosts).
