# Create a CRM application using HubSpot CLI

Before Cloud Voice can talk to HubSpot, HubSpot needs an app that grants the two systems permission to exchange data. This page walks you through building that app with the HubSpot command-line interface (CLI). Instead of clicking through a web form, you describe the app in a small set of local files, group them into a project, and push the project up to your HubSpot developer account.

## Prerequisites

You need a [HubSpot developer account](/pbx/integrations/hubspot/hubspot-crm-integration-guide/#about-this-guide__developer-account).

## Overview

Creating the app takes three stages:

1. Gather the authentication details you'll be prompted for.
2. Prepare your local machine with the tools HubSpot needs.
3. Define the app locally and upload it.

## Gather authentication details

Collect the two credentials you'll be asked for while building the app: a personal access key from HubSpot and a redirect URL from Cloud Voice.

### Generate a personal access key in HubSpot

1. Sign in to your HubSpot developer account.
2. In the left navigation, open **Development > Keys > Personal Access Key**, then select **Generate personal access key**.

   ![The Personal Access Key page in the HubSpot developer account with the generate button](/images/pbx/get-private-ak.png)

3. Copy the key that HubSpot displays and keep it somewhere safe, you'll paste it in later.

   ![The generated personal access key ready to copy](/images/pbx/copy-private-ak.png)

   :::caution
   The personal access key is a secret credential that grants CLI access to your HubSpot account. Do not commit it to source control, share it, or paste it anywhere others can see it. If it is ever exposed, revoke it under **Development > Keys** and generate a new one.
   :::

### Get the redirect URL from Cloud Voice

1. Sign in to Cloud Voice and go to **Integrations > CRM**.
2. Select **HubSpot**.

   
   ![Cloud Voice, the CRM integration list with HubSpot selected](/images/pbx/enter-hubspot-crm.png)

3. Under **Network**, choose and record the **Redirect URL**. You'll add it to the app configuration later.

   ![The Network section showing the Redirect URL field to copy](/images/pbx/pbx-redirect-url.png)

## Set up your local environment

Install the tools the CLI depends on and connect the CLI to your HubSpot account.

### Install Node.js

The CLI runs on Node.js version **20** or later.

1. Download the latest LTS release from [nodejs.org](https://nodejs.org/en/download) and install it.
2. Open a terminal and confirm the install:

   ```bash
   node --version
   # Example output: v24.15.0
   ```

### Install the HubSpot CLI

1. In the terminal, install the CLI globally:

   ```bash
   npm install -g @hubspot/cli
   ```

   Output similar to `changed 704 packages in 2m` means the install worked.

   
   ![Cloud Voice, the terminal reporting a successful CLI installation](/images/pbx/cli-intall-ok.png)

2. Optionally, check the installed version:

   ```bash
   hs --version
   # Example output: 8.9.0
   ```

### Connect the CLI to HubSpot

1. Run the authentication command:

   ```bash
   hs account auth
   ```

   The terminal asks for a personal access key.

2. Press any key to continue, then paste the personal access key you generated earlier.
3. Give the account a unique name so you can refer to it in the CLI. Success messages confirm the account is connected and set as the default.

   
   ![Cloud Voice, the terminal confirming the HubSpot account is authenticated](/images/pbx/auth.png)

## Create and configure the app

Describe the app in local files, its permissions and redirect URL, then push the project to HubSpot.

1. Create a folder for the project and move into it in the terminal:

   ```bash
   # Example
   # Create a folder named "HubSpot CLI" on the D drive
   mkdir D:\HubSpot CLI

   # Navigate into the folder
   cd D:\HubSpot CLI
   ```

2. Create the project:

   a. Run:

      ```bash
      hs project create
      ```

   b. Answer the prompts:

      - **name**: A name for the project.
      - **dest**: Where to create the project.

        :::note
        Press **Enter** to use the current folder.
        :::

      - **project-base**: Select **App**.
      - **distribution**: Select **Privately**.
      - **auth**: Select **OAuth**.
      - **features**: Press **Enter** to skip and continue.

      Wait for the `SUCCESS` message. The project now includes an `app-hsmeta.json` file.

      ![The terminal prompts for setting up a new HubSpot project](/images/pbx/create-project.png)

      ![The terminal showing the project created successfully](/images/pbx/create-project-ok.png)

3. Edit the app configuration:

   a. Locate the `app-hsmeta.json` file inside the project:

      ```
      <your_project_folder>/src/app/app-hsmeta.json
      ```

   b. Open it in a code editor.

   c. Update these settings:

      - `redirectUrls`: Paste the Redirect URL you copied from Cloud Voice.
      - `requiredScopes`: Set the scopes to the following:

        ```json
        "requiredScopes": [
          "oauth",
          "crm.objects.contacts.read",
          "settings.users.write",
          "crm.objects.contacts.write",
          "crm.objects.companies.write",
          "settings.users.read",
          "crm.schemas.contacts.read",
          "crm.objects.companies.read",
          "crm.objects.deals.read",
          "crm.objects.deals.write",
          "crm.schemas.companies.read",
          "crm.schemas.companies.write",
          "crm.schemas.contacts.write",
          "crm.schemas.deals.read",
          "crm.schemas.deals.write",
          "crm.objects.owners.read",
          "settings.users.teams.write",
          "settings.users.teams.read"
        ]
        ```

      ![The app-hsmeta.json file with the redirect URL and scope settings](/images/pbx/app-config.png)

      :::caution
      The redirect URL in the app configuration must match the one shown in Cloud Voice exactly, including the `https://` prefix and any trailing path. If the two do not match, HubSpot rejects the connection during authorization and the integration fails.
      :::

   d. Save the file.

4. Upload the project to HubSpot:

   a. In the terminal, move to the project's root folder:

      ```bash
      # Example
      cd D:\HubSpot CLI\pbx-hs-integration
      ```

   b. Run:

      ```bash
      hs project upload
      ```

      The terminal notes that the project doesn't exist yet and asks whether to create it.

   c. Enter `Y` to confirm. HubSpot creates the app and starts a new build.

      ![The terminal reporting a completed deployment to HubSpot](/images/pbx/deploy-done.png)

## Result

The app is created and uploaded to your HubSpot account. To view its details, sign in to HubSpot and go to **Development > Projects**.

:::note
The app's configuration lives in your local source files. To change the app later, edit the files and run `hs project upload` again to push the update to HubSpot.
:::

![The new app listed under Projects in the HubSpot developer account](/images/pbx/project.png)

## What to do next

- Open the app's **Auth** tab to find the **Client ID** and **Client secret** you'll need for the integration.

  ![The Auth tab showing the app's Client ID and Client secret](/images/pbx/new-app-auth.png)

- [Integrate Cloud Voice with HubSpot CRM](/pbx/integrations/hubspot/integrate-cloud-voice-cloud-voice-with-hubspot-crm/).