Getting started with local development

Last updated:

The HubSpot CLI (Command Line Interface) connects your local workflow to HubSpot, allowing you to utilize version control, your favorite text editor and various web development technologies when developing on CMS Hub.

This guide is best for folks who are familiar already with the CMS but want to learn about working with the CLI. If you are completely new to HubSpot CMS Hub development, we encourage you to:

Build for the first time with CMS Hub

The HubSpot CLI is used to upload, and fetch files from the developer file system. A best practice for this is keeping a local project folder of the modules, templates, CSS and JavaScript files. You can then watch this project folder to have your local changes automatically uploaded as you work, creating a seamless integration between your code editor and HubSpot for rapid development. 

When creating new assets, like templates, modules, themes, and functions, the HubSpot CLI has a create command to help you rapidly scaffold them locally.


In this guide, we'll walk through installing the basics, fetching a project from your HubSpot account, and then sync changes back to your Design Tools. Starting a brand new project or website? Go through the quick start guide to building a website on the HubSpot CMS instead to get set up with local development and deploy a boilerplate theme. 

To get the most out of this workflow, you'll need some working knowledge of the Command Line. For more commands and local file formats, see the Local Development Tooling Reference.

Install dependencies

To use the local tooling, you'll need to:

  1. Install Node.js, a Javascript runtime environment that enables the local tools. Versions 10 or higher of Node are supported, but we recommend the long-term support (LTS) version.
  2. To install the HubSpot tools globally, run npm install -g @hubspot/cli in your command line. To install the tools in your current directory, run npm install @hubspot/cli.

Note: If you prefer, you can also use Yarn. Homebrew is not required but recommended for easy installation. If you are using Yarn, commands are run with the yarn prefix.

Getting an EACCES error when installing? 
See NPM Resolving EACCESS permissions errors when installing packages globally.

1. Create a working directory

Create a folder for your local project. For example, run mkdir local-cms-dev in the command line, which will create a directory. Then, run cd local-cms-dev to navigate to that directory.

2. Configure the local development tools

Run hs init to connect the tools to your HubSpot account. This command will walk you through the following steps:

  1. First you’ll be guided to create a personal CMS access key to enable authenticated access to your account via the local development tools. You’ll be prompted to press "Enter" when you’re ready to open the Personal CMS Access Key page in your default browser. This page will allow you to view or generate your personal access key, if necessary. (Note: You’ll need to select at least the "Design Manager" permission in order to complete this tutorial.) Copy your access key and paste it in the terminal.
  2. Next, you’ll enter a name for the account. This name is only seen and used by you, For example, you might use "sandbox" if you're using a developer sandbox or "" if you’re using a full customer account. This name can't contain spaces. This name will be used when running commands.

Once you've completed this simple init flow, you'll see a success message confirming that a configuration file, hubspot.config.yml, has been created in your current directory.

Your  hubspot.config.yml will look something like this:

defaultPortal: sandbox
  - name: sandbox
  	portalId: 345
    authType: personalaccesskey
    personalAccessKey: >-
        accessToken: >-
        expiresAt: '2020-02-24T19:38:39.164Z'

hubspot.config.yml supports multiple portal entries. The easiest way to add more portals after you already have a hubspot.config.yml is to use hs auth.

When running commands, either name or portalId can be used in the --account= option (ex. --account=123 and --account=sandbox will both interact with account ID 123 based on the above example). If you set a top-level defaultPortal, you can exclude the --account= option from your commands, commands will reference that default portal.

3. Fetch a project from your account

Using the fetch command, run hs fetch --account=<name> <src> <dest> to get an entire projects folder tree and files from your HubSpot account into your local environment. The src is the project path in your HubSpot Design Tools, and the dest is the path to the local directory you would like the files to be placed, relative to your current working directory. To fetch the project to your current working directory, you can leave out the <dest> argument.

Here is an example of how you would fetch a project from your HubSpot account:

Shell script
hs fetch cms-project

This is the Design Tools project we fetched to our local environment:

local and design manager project

4. Make changes and sync to your HubSpot account

Using the upload command, run hs upload --account=<name> <src> <dest> to upload the project in your local environment to your HubSpot account. This will copy the contents of the <src> and upload them to your HubSpot account in the <dest>. If you're creating a new project in your Design Tools, the <dest> can be a net new folder in HubSpot.

Here is an example of how you would upload the example project into your HubSpot account:

hs upload cms-project cms-project

5. Watch your local project and automatically upload changes

Run  hs watch --portal=<name> <src> <dest> to watch your local directory and automatically upload changes to your HubSpot account on file saves.

Here is an example of how you would run that command with the watch command:

hs watch cms-project cms-project

For comprehensive documentation on the HubSpot CLI, see the reference documentation

Share your feedback

Was this page helpful? *
This form is for feedback on our developer docs. If you have feedback on the HubSpot product, please share it in our Idea Forum instead.