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 follow the quickstart guide.

Quick start to CMS Hub development

The HubSpot CLI is used to upload,  fetch, and watch files from the developer file system. Building with the CLI means you'll have local copies of your assets.  Because you have the code locally you can use your preferred code editor, you can use build tools, you can commit your code to a git repository.

Additionally the CLI has helper functionality that can speed up your development. For example the hs create command gives you ways to quickly create different types of assets locally, from modules to creating a theme from the boilerplate.

In this guide, we'll walk through installing the CLI, and the core features of the CLI fetching a project from your HubSpot account, and then uploading changes back to your Design Tools.

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

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

Next, run hs init to connect the tools to your HubSpot account. This command will walk you through the steps below.

  • To connect the CLI to a HubSpot account, you'll need to copy the account's personal access key. When prompted, press Enter to open hubspot.com to the personal access key page of the account. If you have multiple accounts, you'll be prompted in the browser to select an account first.
  • On the personal access key page, you can generate a new personal access key or copy the existing key value if one already exists.
    • If you're creating a key for the first time, select which scopes the key has access to. You'll need to select at least the Design Manager permission to interact with the account's design tools. 
    • After selecting the key's permissions, click Generate personal access key.
  • Once a key has been generated, copy its value by first clicking Show under the key, then clicking Copy.
  • Paste the key into the command line, then press Enter.
  • Next, enter a name for the account. This name is only seen and used by you when running commands. For example, you might use "sandbox" if you're using a developer sandbox or "company.com" if you’re using a standard account. This name can't contain spaces. 
  • Press Enter. 

With the init flow complete, 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: mainProd portals: - name: mainProd portalId: 123456 defaultMode: publish authType: personalaccesskey auth: tokenInfo: accessToken: >- {accessTokenValue} expiresAt: '2023-06-27T19:45:58.557Z' personalAccessKey: >- {personalAccessKeyValue} sandboxAccountType: null parentAccountId: null - name: mainSandbox portalId: 18569211 authType: personalaccesskey auth: tokenInfo: accessToken: >- {accessTokenValue} expiresAt: '2023-06-27T19:47:32.583Z' personalAccessKey: >- {personalAccessKeyValue} sandboxAccountType: STANDARD parentAccountId: 123456
Use this table to describe parameters / fields
NameDescription
defaultPortal
Optional

The account that is interacted with by default when running CLI commands.

To interact with an authenticated account that is not set as the default, you can add a --account= flag to the command, followed by the account name or ID. For example, --account=12345 or --account=mainProd.

name
Optional

Under portals you'll find an entry for each connected account. name specifies the given name for the account. You can use this name when setting a new default account or specifying an account with the --account flag.

portalId
Required

The account ID.

defaultMode
Optional

When uploading to the account, sets the default state to upload content as. Can be either draft or publish.

authType
Required

The form of authentication used to auth the account. 

sandboxAccountType
Optional

If the account is a sandbox account, indicates the ID of the parent production account.

parentAccountId
Optional

parentAccountId

The hubspot.config.yml file supports multiple accounts. To authenticate more accounts, run hs auth and follow the prompts.

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:

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 upload 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 --account=<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. 

Related tutorials and resources

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