Developer projects setup guide (BETA)

APPLICABLE PRODUCTS
  • Sales Hub
    • Enterprise
  • Service Hub
    • Enterprise

To develop HubSpot projects, you’ll first need to set up your local environment, including installing the HubSpot CLI and connecting it to your HubSpot account. Below, you'll also learn how to create a development sandbox to build and deploy your project in a testing environment before deploying to the production account.

This guide walks through the setup instructions for building projects with HubSpot CLI. However, if you prefer to use GitHub for version control, you can also link a GitHub repository to a project to develop projects using GitHub tools instead. 

Set up your local environment

To start setting up your local environment, you'll first need to: 

  • Install Node.js which enables HubSpot’s local development tools. Versions 10 or higher are supported.
  • Install the HubSpot CLI globally by running npm install -g @hubspot/cli@next in the terminal. This command will also update the CLI to the latest version if you’ve already installed it.

With the CLI installed, you can now connect it to the account you'll be uploading to:

  • In the terminal, navigate to the directory where you’ll be working.
  • Run hs init.
  • Press Enter to open the personal access key page in your browser.
  • Select the account that you want to deploy to, then click Continue with this account. You’ll then be redirected to the personal access key page of the account.
  • To retrieve your personal access key:
    • If you haven't generated a key yet, click Generate personal access key. Then click Show to reveal the key, then click Copy to copy it to your clipboard.
    • If you've already generated a key, next to Personal CMS Access Key, click Show to reveal your key, then click Copy to copy it to your clipboard.

Please note: your personal access key will need the following scopes:

  • developer.projects.write
  • developer.app_functions.read and developer.app_functions.write
  • sandboxes.write
If your access key doesn't include these scope, you'll need to deactivate it and generate a new one.
  • Paste the copied key into the terminal, then press Enter.
  • Enter a unique name for the account, which is only used when running CLI commands. Then, press Enter.

The CLI will display a success message confirming that the hubspot.config.yml file was created, which stores your connected accounts. After creating this file, you can add more accounts by running the hs auth command. At any time, you can view all the currently connected accounts by running hs accounts list

When you later run commands to upload, fetch, or watch a project, HubSpot will use the account that’s set as the default in the file. When developing on multiple accounts, you can change the default account by running hs accounts use accountName. You can also interact with a specific account by adding the following flag to the end of a command: --account=accountName.

Below, learn more about developing in sandbox accounts.

Create and use development sandboxes

When developing a project, you may want to first work in a lightweight testing environment to ensure your project's components work as expected before deploying to a standard sandbox or production account.

To do so, you'll first need to connect your standard production account to the CLI as outlined in the previous section. Then, you can create a development sandbox within that account by running hs sandbox create. Below, learn more about setting up and using a development sandbox.

Please note: ensure you’re on the latest version of the CLI by running npm install -g @hubspot/cli@next.

Development sandbox limits

  • A production account can have only one development sandbox at a time.
  • CRM object definitions are synced from the production account to the development sandbox at the time of sandbox creation. If you create properties in the production account after creating the sandbox, they will not automatically sync over. Learn how to resync a development sandbox.

Create a development sandbox

Once you've followed the steps at the top of this article to connect your production account to the CLI with hs init or hs auth, you can proceed to set up a development sandbox in the production account.

Please note: attempting to create a development sandbox in another sandbox account will result in an error.

To set up a development sandbox account:

  • Because development sandboxes are created within the defaultPortal in your hubspot.config.yml file, first confirm that your production account is connected and set as the default:
    • In the terminal, run hs accounts list.
    • In your list of connected accounts, confirm that your production account is listed as the Default account.
      hs-acounts-list-default
    • If your production account is not the default, run hs accounts use and select your production account.
  • After confirming your production account is the default, run hs sandbox create
  • Enter a name for the sandbox account, then press Enter.
  • The CLI will display a confirmation message once the sandbox has been successfully created. 

After creating the sandbox, you'll be prompted to authenticate it:

  • Press Enter to begin the personal access key setup process. A browser window will then open.
  • On the personal access key page, select the scopes that you'll need, then click Generate personal access key. Ensure that the following are selected:
    • Developer projects (developer.projects.write)
    • Serverless functions (developer.app_functions.read and developer.app_functions.write)
  • Under the personal access key, click Show, then click Copy.
  • Paste the access key into the terminal, then press Enter.
  • Enter a unique name for the account, then press Enter.
  • Choose whether you want to set the sandbox as the default account by entering y or n, then press Enter. Setting the development sandbox to your default account will enable commands to interact directly with the sandbox by default, rather than needing to add an --account flag. You can reset the default account at any time by running hs accounts use.

You can later run hs accounts list to view your connected HubSpot accounts, including development sandbox accounts which appear beneath their associated production account.

cli-connected-accounts-sandbox

With your development sandbox set up, you can now start developing your project within your testing environment.

View a development sandbox in HubSpot

By default, only the user who created the development sandbox can access it in HubSpot. However, you can enable other users to access it by adding them as users to the development sandbox. Super admins who haven't been added as users will still be able to view the development sandbox details in HubSpot, and can delete the sandbox if needed.

sandbox-request-access

To access the development sandbox account in HubSpot:

  • In your HubSpot account, navigate to CRM Development in the main navigation bar.
  • In the left sidebar menu, select Sandboxes.
  • Click the Development tab, where your new sandbox will be listed along with its name, create date, and the user who created it. 
  • To navigate to the sandbox account, click the development sandbox name.

Once a non-super admin user has been granted access to a development sandbox, they can access it by clicking the Profile picture in the top right of HubSpot, then clicking the Account selection menu and selecting the account.

portal-picker-hobbes

Delete a development sandbox

  • To delete a development sandbox using the CLI, run hs sandbox delete, then follow the prompts.
  • To delete a development sandbox in HubSpot:
    • In your HubSpot account, navigate to CRM Development in the main navigation bar.
    • In the left sidebar menu, select Sandboxes.
    • Click the Development tab.
    • Hover over the development sandbox, then click Delete.

delete-development-sandbox

Resync a development sandbox

After creating a development sandbox, new properties and property groups created in the production account will not automatically sync over to the sandbox. You can resync the development sandbox as needed either from the CLI or within HubSpot:

  • To resync a development sandbox in the CLI:
    • First ensure that the development sandbox is set as the default account by running hs accounts use, then selecting the sandbox.
    • With the sandbox set as the default, run hs sandbox sync.
  • To resync a development sandbox in HubSpot:
    • In your HubSpot account, navigate to CRM Development in the main navigation bar.
    • In the left sidebar menu, select Sandboxes.
    • Click the Development tab.
    • Hover over the development sandbox, then click Set up sync to sandbox.
    • In the right panel, click Sync to development sandbox.
    • When the sync is complete, the Last sync status will display any changes synced to the sandbox.

Properties and property groups from the following CRM objects will then be synced:

  • Contacts
  • Companies
  • Deals
  • Tickets
  • Custom objects

Was this article helpful?
This form is used for documentation feedback only. Learn how to get help with HubSpot.