Getting started with Helix TeamHub CLI

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.

Before you begin

Supported operating systems

• Linux
• macOS
• Windows

Prerequisites

• 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.

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

Install hth-cli

1. Download the hth-cli binary from the Perforce hth-cli download page.
2. Uncompress the downloaded file, this creates a directory with the same name as the download file.
3. 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>

1. Set up the hth-cli tool to connect to your Helix TeamHub account and create an active session for the subsequent commands:

❯ hth setup
  Setting up hth-cli.
  Input details of your Helix TeamHub installation.
? Instance URL https://my.helixteamhub.com
? User ID bob
? Password ********
✓ hth-cli is set up for /Users/bob/.hth/cli.
  Run hth config edit --global to edit the global configuration file.

Tip

You can invalidate the session at any time by using hth logout.

2. Open your browser and navigate to the project you want to manage from the Helix TeamHub Web UI.
3. Create a new repository and in the Advanced Settings, select the Manifest and Generate a default manifest file check boxes.

This creates a manifest repository and populates your existing repositories with the required manifest configuration that ties the repositories together.

4. Set up your local working directory, see Set up a local working directory.

Set up a local working directory

A local working directory contains a set of repositories within a Helix TeamHub project.

1. From the command line, navigate to the path you want to work in and set up your local working directory.
2. To clone the manifest repository to your local working directory, run hth init using the clone URL of your manifest repository. To find the clone URL:
   1. Go to the repository in Helix TeamHub, click the Clone dropdown, and select SSH.
   2. Copy the clone URL and paste it in when running the hth init command.

Do one of the following:

• If your project has a manifest file:

❯ hth init git@<GitConnectorURL>.com: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.

• If your project does not have a manifest file:

❯ hth init git@<GitConnectorURL>.com:hth_cli
  Initializing a local working directory.
✓ Local working directory initialized successfully.
  Run hth config edit --local to edit the local configuration file.
  Run hth manifest edit to edit the manifest file.

Tip

If the hth init command fails, you will see an error message similar the messages below:

✘ Local working directory already exists under /Users/bob/git/hth-cli.

Clean your local working directory before you run hth init again by running the following command in your local working directory:

Linux/macOS: from your local working directory run rm -rf .hth

Windows: from your local working directory run rmdir /S .hth

You can now run the hth init command again.

3. Run hth sync to clone all the repositories configured in the manifest file under the current path:

❯ hth sync
✓ Successfully cloned backend from git@<GitConnectorURL>.com/hth_cli/backend
✓ Successfully cloned frontend from git@<GitConnectorURL>.com/hth_cli/frontend
✓ Successfully cloned docs from git@<GitConnectorURL>.com/hth_cli/docs

4. 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.

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