Developer projects setup guide (BETA)

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: to create a developer sandbox, your personal access key must have the sandboxes.write scope. If your access key doesn't include that 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 only at the time of sandbox creation. If you create properties in the production account after creating the sandbox, you can either create them in the development sandbox manually or delete and recreate the sandbox account. Properties from the following CRM objects are synced:
    • Contacts
    • Companies
    • Deals
    • Tickets
    • Custom objects

Set up and manage 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. Development sandboxes are automatically created within the defaultPortal in your hubspot.config.yml file. You can confirm that your production account is connected and set as the default by running hs accounts list, and you can set defaultPortal again by running hs accounts use and selecting a connected account.

To set up a development sandbox account:

  • In the terminal, 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.

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.
  • To delete a sandbox, hover over the sandbox, then click Delete. You can also delete a sandbox using the CLI by running hs sandbox delete, then following the prompts.

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.


Connect the development sandbox to the CLI

To connect the development sandbox account to the CLI:

  • In the terminal, run hs auth.
  • Follow the prompts to select your development sandbox account and get its access key.
  • Paste the access key into the terminal, then press Enter.
  • Enter a unique name for the account, then press Enter.
  • You can then set the development sandbox as your default account by entering y, then pressing Enter. Setting the development sandbox to your default account will enable your commands to interact directly with the sandbox, 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.


With your development sandbox set up, you can now start developing your project within your testing environment. Later, when you're ready to deploy your project to the production account, you can either switch your default account to the production account using hs accounts use, or upload to the production account directly with hs project upload --account=productionAccountName

Next, get started building a project by walking through the quickstart guide.

Additional resources

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