Getting started with local development
The HubSpot CLI (Command Line Interface) connects your local environment to HubSpot, meaning you'll have local copies of your HubSpot web assets. This allows you to use version control, your favorite text editor and various web development technologies when developing on the HubSpot CMS.
This guide is best for those who are already familiar 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.
In this tutorial, you'll learn:
- How to install the CLI and connect it to your HubSpot account.
- How to fetch a module from your HubSpot account.
- How to update the module locally, then upload your changes.
- How to use the
watch
command to continue uploading saved changes.
For more commands and local file formats, see the Local Development Tooling Reference.
To develop on HubSpot locally, you'll need to:
- Install Node.js, which enables HubSpot's local development tools. Versions 18 or higher are supported. It's recommended to use a package manager like Homebrew or nvm to install Node.
- Run npm install -g @hubspot/cli in your command line to install the HubSpot CLI globally. To install the tools in only your current directory instead, run npm install @hubspot/cli.
If you prefer, you can also use Yarn. 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.
Create a folder for the work you'll be doing below. For the purposes of this tutorial, name the folder local-dev-tutorial
.
You can do this locally by running mkdir local-dev-tutorial in the command line, which will create the directory. Then, run cd local-dev-tutorial to navigate to that directory.
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:
Name | Description |
---|---|
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 |
name
Optional
| Under |
portalId
Required
| The account ID. |
defaultMode
Optional
| When uploading to the account, sets the default state to upload content as. Can be either |
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.
For the purpose of this tutorial, you'll first create a new asset in HubSpot so that you can fetch it to your local environment using the CLI.
- In your HubSpot account, navigate to Marketing > Files and Templates > Design tools. This will open the design manager, which is where you can access the files you upload using the CLI. This tree of files and folders is also referred to as the developer file system.
- In the left sidebar of the design manager, select the @hubspot folder to view HubSpot's default assets, such as themes and modules.
- In the left sidebar, scroll down to and right-click the icon module, then select Clone module. The module will be cloned to the root of the developer file system, and your new module copy will be opened on the right.
- At the top of the left sidebar, click Actions, then select Copy path. This will copy the relative path to the module in the developer file system, which you'll use in the next step to fetch the module locally.
With the module cloned, you'll now use the fetch command to bring it into your local environment.
In the terminal, run hs fetch '/icon copy.module'
.
fields.json
: contains the code for the module's various fields. In this case, this includes the icon field, two accessibility option fields, and a set of style fields. You can see these fields in the right sidebar of the module editor in HubSpot.meta.json
: contains the module's basic information, such as its label, ID, and the types of templates it can be used in. This information will be displayed in the right sidebar of the module editor.module.css
: contains the module's CSS, which you can also see in the CSS pane of the module editor in HubSpot.module.html
: contains the module's HTML, which you can also see in the HubL + HTML pane of the module editor in HubSpot.module.js
: contains the module's JavaScript, which you can also see in the JS pane of the module editor in HubSpot.
meta.json
file, then upload it to your account and view the change in HubSpot.First, make a change to the module:
- In your preferred code editor, open the module's
meta.json
file. - Update the
label
field from"Icon"
to"CMS tutorial module"
. Then, save the file.
hs upload
, let's break down the command and the arguments it takes. This command takes two arguments: hs upload <src> <dest>
src
: the relative path of the source folder that you're uploading from your local environment.dest
: the path of the destination directory in HubSpot, local to the root of the developer file system. You can create a new directory in the account by specifying the directory name, such ashs upload <src> /new-directory
.- With that in mind, because you're uploading to the root of the developer file system, run the following command:
- After the CLI confirms that the module has been successfully uploaded, refresh the design manager to view your change in HubSpot. You should now see that the Label field shows your new value.
Now that you've used the upload
command to run a one-time upload of your local files, you'll now use the watch
command to continuously upload saved changes. This command takes the same arguments as upload
, so you can specify the same <src>
and <dest>
as above.
- Run
hs watch 'icon copy.module' 'icon copy.module'
With the watch now running, saved changes will automatically upload to the HubSpot account. As a demonstration, make the following local change to the module:
- In the
meta.json
file, update thehost_template_types
field to remove"BLOG_LISTING"
and"BLOG_POST"
so that the module is only available for pages:"host_template_types"
:["PAGE"]
- Ten, save the file. This should prompt the CLI to automatically upload the file to HubSpot.
- With the file uploaded, refresh the design manager in HubSpot to view your change. The Template types section of the right sidebar should now only include Page.
- To end the watch, press
Control + C
. It's important to note that you won't be able to run other commands in the same terminal window that the watch command is running in. To run other commands while running a watch, you should instead open another terminal window and execute your commands there.
Now that you've walked through how to use the fetch
, upload
, and watch
commands, you may want to check out the full CLI command reference guide to learn what else you can do with the CLI.
It's also recommended to check out the following tutorials:
Thank you for your feedback, it means a lot to us.