Create a CRM application using HubSpot CLI

This topic describes how to create a new application using the HubSpot CLI. You can define the application's configurations in local files, which are bundled into a project and can be uploaded to your developer account for later integration.

Prerequisites

Procedure

  1. Obtain required authentication information
  2. Set up the local environment
  3. Create and configure an application

Obtain required authentication information

Obtain all the necessary authentication credentials required during the application creation process.
  1. Get a personal access key from HubSpot.
    1. Log in to your HubSpot developer account.
    2. At the left navigation bar, go to Development > Keys > Personal Access Key, and click Generate personal access key.

    3. In the Personal Access Key section, copy the generated key and store it securely for later use.

  2. Get the redirect URL from Yeastar PBX.
    1. Log in to PBX web portal, go to Integrations > CRM.
    2. Click HubSpot.

    3. In the Network section, select and note down the Redirect URL for later use.

Set up the local environment

Prepare your local development environment by installing the required dependencies and authenticating with HubSpot.

  1. Install Node.js (Version 20 or later).
    1. Go to nodejs.org, download the latest TLS version, and install it on your computer.
    2. Launch a terminal, and run the following command to verify the installation:
      node --version
# Example output: v24.15.0
  2. Install the HubSpot CLI.
    1. In the terminal, run the following command to install the HubSpot CLI globally:
      npm install -g @hubspot/cli

      When you see output similar to changed 704 packages in 2m, the installation has succeeded.

    2. Optional: Run the following command to verify the installation:
      hs --version
# Example output: 8.9.0
  3. Connect your local environment to HubSpot.
    1. In the terminal, run the following command:
      hs account auth
      The terminal will prompt you to enter a Personal Access Key.
    2. Directly press any key to proceed, and paste the personal access key when prompted.
    3. Set a unique name to reference this account in the CLI.

      When the terminal displays success confirmation messages, it indicates that the account is connected and set as default.

Create and configure an application

Define your application's settings locally, including permissions and redirect URIs, then upload the project to HubSpot.

  1. Create a local folder for your project and open 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 a project.
    1. Run the following command.
      hs project create
    2. Set up the project.

      • name: Enter a name for your project.
      • dest: Specify where to create the project.
        Note: To use the current folder, press Enter directly.
      • project-base: Select App.
      • distribution: Select Privately.
      • auth: Select OAuth.
      • features: Press Enter directly to skip and proceed.

      Wait until a SUCCESS message is displayed. An app-hsmeta.json file will be added to the project.

  3. Modify application configuration.
    1. In the file explorer, navigate to the following path to locate the app-hsmeta.json file.
      <your_project_folder>/src/app/app-hsmeta.json
    2. Open the file using a code editor.
    3. Modify the following settings:

      • redirectUrls: Paste the Redirect URL obtained from the PBX.
      • requiredScopes: Paste the following scopes:
         "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"
      ]
    4. Save the changes.
  4. Upload the project to HubSpot.
    1. In the terminal, navigate to the root directly of the project.
      # Example 
cd D:\HubSpot CLI\pbx-hs-integration
    2. Run the following command:
      hs project upload
      The terminal will prompt that the project does not exist and ask for confirmation to create it.
    3. Enter Y to confirm.

      HubSpot will create the application and trigger a new build.

Result

The application is created and uploaded to your HubSpot account. You can log in to your HubSpot portal and view the application details (Path: Development > Projects).
Note: The application configuration files are managed in your local source code. To make changes, update the files locally and run hs project upload to update on HubSpot.

What to do next