CMS Developer Tools

Table of contents

Local HubL server (HubDB Support BETA)

The Local HubL Server allows web developers that are comfortable with markup and the HubL templating language to build and test HubSpot CMS templates locally. The server runs 100% locally with no external dependencies.  Once running, you will be able to build and test templates without loading templates into the HubSpot interface.

This BETA version of the local HubL server supports rendering HubDB data locally, and should be configured independently of the existing local HubL server.

Please note that this tutorial assumes you already have HubDB tables created. Please see the HubDB documentation if you are unfamiliar with HubDB or want to create your first HubDB tables. 

This tool is designed for developers comfortable with (OS X, Windows, or Linux) shell commands, and requires installation of Java 8 (or later) development kit to run. Also note that this tool is only meant to allow rendering content locally. It does not connect to HubSpot or load files into the HubSpot system. However, it can be used in conjunction with FTP or stand alone.


Before following these instructions, please ensure that you have the following installed on your local machine:

  1. Java 8 (or later) developers kit 
  2. Node/npm 
  3. Gulp

Follow these steps to set up the Local HubL Server:

1. Download the BETA package

Download the BETA version of the package.

2. Unzip the package

Unzip the file. This will create a local-hubl-server directory. You can move this folder to a directory of your choosing.

3. Move to the local-hubl-server directory

Open Terminal or Command Prompt and change directory to local-hubl-server. In Terminal the command is:

cd local-hubl-server
Please note that the path to the file will vary based on where you unzip and move the directory. Alternatively, you can navigate to the server folder via Finder or Windows Explorer.

4. Install Node dependencies

Run the following command from the local-hubl-server directory to install Node dependencies:

cd bin; npm install

NOTE: This command only needs to be run once.

5. Set Portal ID in site-settings.json file

In the local-hubl-server/conf/context/site-settings.json file, enter the Portal ID you wish to render pages locally for. 

6. Run the Gulp task to pull down HubDB table data

Run the following command from the local-hubl-server directory:

cd bin; gulp hubdb_download --hapikey <hapikey>

The hubdb_download task downloads all published HubDB tables from a specified portal, and stores them in a sqlite table (which will be created in ../hubdb/<portalId>/hubdb.db). Additional table metadata will be stored in .json files in the same directory. Authentication for requesting the HubDB data is supplied via a HubSpot API key (hapikey)

If you want to update the SQL batch size (default is 1) you can use the --batchSize parameter, but you may see this error: An error occurred while populating table 12345: { [Error: SQLITE_ERROR: too many SQL variables] errno: 1, code: 'SQLITE_ERROR' }. Lower your set batch size if you are running into this error. 

7. Run the server

Run the following command from the local-hubl-server directory to start the server:


NOTE: If you have already setup all of the dependencies in the steos listed above, you can run one command from the local-hubl-server directory to pull down HubDB data, and start the server:

cd bin; gulp hubdb_download --hapikey <hapikey>; ./local-hubl-server

Please note that if you update your HubDB tables, you will need to re-run the Gulp task and re-start the server to see updated changes.

If you do not have the Java 8 Developers Kit installed, you will be prompted to download and install it. If successful the browser will open to

As an alternative, if you accessed the local-hubl-server directory via Finder or Windows Explorer, run the local-hubl-server executable in the 'bin' directory.

HubSpot Help article screenshot

8. Explore the default template content

List of templates

While running the server, the IP address will show you a list of templates that have been created in your working directory. The default distribution comes with a codified hubtheme to play with.

You can see that the 'conf/config.yaml' is set up to point at 'work/hubthemes/vast as a baseDir', which is where everything all of the default tempates live. If you wish to change the baseDir, you will need to edit the config.yaml file.

You may notice that the folder structure of the work/hubthemes/vast directory resembles the folder structure of Design Manager. When you create new HTML files, in your working directory, you will see them automatically added to the list of links available at

Local HubL Server + FTP

You can use the HubL Local Server with an FTP client to sync both the local and remote 'custom' directories. To learn more, check out this article.

Learn more about local development on HubSpot CMS

There is a good forum thread on this topic  👉  "Can you set up local development on HubSpot CMS?"

You can also ask questions to the community in the CMS Developer Slack.