Developer projects setup guide (BETA)

Below, learn how to connect your production account to the CLI then create a development sandbox within it. After setting up your local environment, you can proceed to creating a project. To learn more about the CLI commands you'll be using, check out the project-specific CLI commands reference.

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

• Install Node.js which enables HubSpot’s local development tools. Versions 18 and higher are supported. It's recommended to use a package manager like Homebrew or nvm to install Node.
• 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. Note that you do not need to complete these steps now if you'll be following the quickstart guide.

• 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 production 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:
    • Ensure that the Developer projects, Sandboxes, and Serverless functions checkboxes are selected, then click Generate personal access key.
    • 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. Your key must include the following scopes to create projects, apps, and sandboxes. If your key is missing these scopes, you'll need to deactivate it and create a new one.
    • developer.projects.write
    • developer.app_functions.read
    • developer.app_functions.write
    • developer.sandboxes.read
    • developer.sandboxes.write
    • sandboxes.read
    • sandboxes.write

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

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.
    
  • 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. 
• You'll then be prompted to select a type of sandbox to create. Select Development sandbox, then press Enter.
• Enter a name for the sandbox account, then press Enter.
• All CRM object definitions will be copied from production to the development sandbox.
• You can use the import tool to import production object record data, or manually create sample data for testing.

• The CLI will then begin the sandbox setup process. Once the sandbox is fully set up and synced, you'll see a Sandbox sync complete confirmation. 

With your development sandbox created, it will appear under the associated production account when running hs accounts list.

If you want to set the development sandbox as your default account, run hs accounts use, then select the sandbox. To deploy to your sandbox or production account, you can either run hs accounts use to set the default account, or manually select the account when uploading by running hs project upload --account=<name-of-account>.

Development sandboxes are designed to be early proof of concept environments. It is recommended to delete and create a new Development Sandbox using the CLI. This ensures development sandboxes always have an exact mirror of the production account’s CRM object definitions when beginning new projects.

After setting up your development sandbox, learn how to quickly create a UI extension by jumping to section three of the UI extensions quickstart guide. Or, learn more about projects, private apps, and UI extensions.

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.

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.

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

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.
  • Following the prompts, enter y (yes) or n (no) to select what you'll be syncing:
    • Sync CRM object definitions: sync the current CRM object definitions from the production account to the sandbox. This includes all custom CRM properties and custom objects.
    • Include up to 100 most recent contact records and associations: if you didn't perform this one-time sync during sandbox creation, this option will also create CRM records for the 100 most recently created contacts in the production account, along with up to 100 of their associated company, deal, and ticket records. You can only perform this sync once per development sandbox, and only if you've chosen to sync CRM object definitions.
• 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.
  • To the right of the sandbox, click Set up sync to sandbox.
    
  • In the right panel, review what you'll be syncing. If you haven't performed a one-time sync of the production account's contacts and associated records, you can select the checkbox to include that data in the sync. This will sync the 100 most recently created contacts from the production account, along with up to 100 associated deals, 100 associated companies, and 100 associated tickets.
    
    
  • 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