Getting started with Helix TeamHub CLI
Helix TeamHub supports Helix TeamHub CLI for Git and Helix Git repositories.
This section will help you to get started with the Helix TeamHub CLI tool. It covers installation, how to set up the hth-cli tool, and the first few steps required to start performing actions on repositories within your project.
For details on the licensing of hth-cli, see Helix TeamHub CLI licensing in the Helix TeamHub User Guide.
Before you begin
Supported operating systems
- Helix TeamHub CLI relies on Git for the repository operations. Git must be installed before you install the hth-cli tool. Download Git for your Operating System from https://git-scm.com/downloads.
- Helix TeamHub CLI relies on Helix TeamHub to operate.
- Helix TeamHub CLI uses HTTP(S) and SSH protocols for repository operations. Make sure that you have SSH keys configured for your account, see Configuring SSH keys in the Helix TeamHub User Guide.
To ensure hth-cli compatibility on Windows when running inside Git Bash command prompt prefix hth-cli commands with winpty. For example, winpty hth setup.
Default file editor
- Linux and MacOS: hth-cli uses the default editor set in your EDITOR or VISUAL env var settings. If these are not set, hth-cli falls back to using xdg-open for Linux and open for MacOS.
- Windows: hth-cli uses the start command to open the file in your default Windows file editor.
Installation and set up
- Download the hth-cli binary from the Helix TeamHub section of the Perforce download page.
- Set up the hth-cli tool, see Set up the hth-cli tool.
Set up the hth-cli tool
In this section we will create the .hth/cli directory and a global config file by running hth setup without flags. You will be prompted to enter your instance, company, and user details.
The location the .hth/cli directory is created in will depend on the operating system you are using:
- Linux: created in the home directory ~/
- MacOS: created in the home directory ~/
- Windows: created in C:\Users\<username>
Run hth setup with flags to specify your instance, company, and user details. You can skip log in with the --no-login flag. For details of the hth setup flags, see Setup hth-cli.
- Set up the hth-cli tool to connect to your Helix TeamHub account and create an active session for the subsequent commands:
- Open your browser and navigate to the project you want to manage from the Helix TeamHub Web UI.
- Create a new repository and select the Manifest and Generate a default manifest file checkboxes.
- Set up your local working directory, see Set up a local working directory.
❯ hth setup Setting up hth-cli. Input details of your Helix TeamHub installation. ? Instance URL https://my.helixteamhub.com ? User ID admin ? Password ******** ✓ hth-cli is set up for /Users/bob/.hth/cli. Run hth config edit --global to edit the global configuration file.
You can invalidate the session at any time by using hth logout.
This creates a manifest repository and populates your existing repositories with the required manifest configuration that ties the repositories together.
Set up a local working directory
A local working directory contains a set of repositories within a Helix TeamHub project.
- From the command line, navigate to the path you want to work in and set up your local working directory.
- To clone the manifest repository to your local working directory, run hth init using the clone URL of your manifest repository:
- Run hth sync to clone all the repositories configured in the manifest file under the current path:
- You are now all set to start using hth-cli, enjoy!
- For information about how and where hth-cli stores its manifest and config files, see Manifest and config files.
- For examples of how to manage your repositories using hth-cli, see the Helix TeamHub CLI examples section on what to do next.
- For information about the hth-cli commands, see Helix TeamHub CLI command reference.
❯ hth init ssh://[email protected]:220/hth_cli/manifest Cloning into '/Users/bob/Projects/hth/hth-cli-testing/.hth/cli/manifest'... remote: Counting objects: 4, done. remote: Compressing objects: 100% (3/3), done. remote: Total 4 (delta 0), reused 4 (delta 0) Receiving objects: 100% (4/4), done.
❯ hth sync ✓ Successfully cloned backend from ssh://[email protected]/hth_cli/backend ✓ Successfully cloned frontend from ssh://[email protected]/hth_cli/frontend ✓ Successfully cloned docs from ssh://[email protected]/hth_cli/docs
Manifest and config files
Helix TeamHub CLI stores its configuration on two levels:
- Global config: stored in your home directory (Linux and MacOS: ~/, Windows: C:\Users\<username>), under .hth/cli. You can change the path to the global config file by setting the HTH_CLI_ROOT environment variable. This directory contains the following files:
- api_keys.json - used to store active sessions (your log in password is never stored)
- config.json - used to store configuration regarding the Helix TeamHub instances, companies and users
- Local config: stored in your local working directory, under .hth/cli. This directory contains the following files:
- config.json - contains local overrides for the global config.json configuration
- manifest - the manifest repository for the local working directory