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.

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.

   

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

   

   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.

   

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

   

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 and install it.

2. Open a terminal and confirm the install:

   node --version
   # Example output: v24.15.0

Install the HubSpot CLI

1. In the terminal, install the CLI globally:

   npm install -g @hubspot/cli

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

   

2. Optionally, check the installed version:

   hs --version
   # Example output: 8.9.0

Connect the CLI to HubSpot

1. Run the authentication command:

   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.

   

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:

   # 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:

   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.

   

   

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:

     "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"
     ]

   

   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:

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

   b. Run:

   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.

   

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.

What to do next

• Open the app’s Auth tab to find the Client ID and Client secret you’ll need for the integration.

  

• Integrate Cloud Voice with HubSpot CRM.