Local Development Tooling: CMS CLI Reference
The CMS CLI Local Development Tooling connects your local workflow to HubSpot, allowing you to utilize version control, your favorite text editor and various web development technologies when developing on the HubSpot CMS.
The Local Development Tooling supports a local project of modules, templates, HTML, CSS, and Javascript files. This project can then be synced to your HubSpot Design Tools. You can also watch
this local project, and automatically sync changes of local files to your HubSpot account, creating a seamless integration between your code editor and HubSpot for rapid development. More developer efficiency tips and tricks.
This doc outlines the available commands and file formatting for HubSpot's CMS Local Development Tooling. For a walkthrough of these tools, see the getting started with local development tutorial. Module fields are defined within a fields.json file, for a listing of module fields and code examples see: Module and Theme Fields.
To install the HubSpot tools globally, in your command line run the command below. This is recommended if you develop frequently on HubSpot.
npm install -g @hubspot/cms-cli
If you instead wish to install the tools in your current directory, run the command below.
npm install @hubspot/cms-cli
Getting an EACCES error when installing?
See NPM Resolving EACCESS permissions errors when installing packages globally.
The CLI is updated regularly, to upgrade to the latest version of the local tools, run:
npm install -g @hubspot/cms-cli@latest
Show all commands.
hs help
Additionally if you simply want to learn more about a specific command, enter the command and --help
to get an explanation without needing to reference these docs.
Creates your hubspot.config.yml
file in the current directory and sets up authentication for an account. If you are adding authentication for a new account to an existing config file, run the auth command. When prompted for a name to use for the account, the name can't contain spaces.
hs init
Generate authentication for a HubSpot using a personal CMS access key. You can generate your access key here. If you already have a hubspot.config.yml
file you can use this command to add credentials for additional accounts. For example you might use your sandbox account as a development environment. When prompted for a name to use for the account, the name can't contain spaces.
hs auth
Using the CLI you can interact with the developer file system, the file system you see in the Design Manager.
List files stored in the developer file system by path or from the root. Works similar to using standard ls
to view your current directory on your computer.
hs ls [path]
hs list [path]
Argument | Description |
---|---|
dest
Optional
| Path to the remote developer file system directory you would like to list files for. If omitted, defaults to the account root. |
Fetch a file, or directory and its child folders and files by path.
This takes files from your HubSpot account and brings them into your local environment. The <src> should be the path from your HubSpot Design tools. The <dest> is the local directory where you'd like to add these files.
As a precaution fetching does not by default overwrite your existing local files, you can use --overwrite
when you want to do that.
hs fetch --account=<name> <src> [dest]
hs filemanager fetch --account=<name> <src> [dest]
Argument | Description |
---|---|
src
Required
| Path in HubSpot Design Tools |
dest
Optional
| Path to the local directory you would like the files to be placed, relative to your current working directory. If omitted, this argument will default to your current working directory. |
Options | Description |
---|---|
--account
| Specify an Supports an alias of |
--overwrite
| Overwrite existing files with fetched files. |
--mode
| Specify if fetching a draft or published version of a file from HubSpot. Click here for more info |
Upload a new local asset to your HubSpot account. Changes will immediately be live.
The <src> in this command is the path to your local file relative to your current working directory. The <dest> is the path to a file in your HubSpot account and can be a net new folder.
hs upload --account=<name> <src> <dest>
hs filemanager upload --account=<name> <src> <dest>
Argument | Description |
---|---|
src
Required
| Path to the local file, relative to your current working directory. |
dest
Required
| Path in HubSpot Design Tools, can be a net new path. |
Options | Description |
---|---|
--account
| Specify a Supports an alias of |
--mode
| Specify if uploaded files are published in HubSpot. See "modes" for more info. |
Subcommands | Description |
---|---|
filemanager
| Uploads the specified src directory to the File Manager, rather than to the developer file system in the Design Manager. Note: Uploaded files will be set to public, making them viewable by anyone with the URL. See our help documentation for more details on file visibility settings. |
Watch your local directory and automatically upload changes to your HubSpot account on file saves. Changes will be live immediately.
NOTE: When in a watch process, deleted files being watched will not automatically be deleted from your HubSpot account. If you want it to delete files, use --remove
.
Renaming a folder locally will cause watch
, to upload the new folder with the new name, the existing folder in the developer file system will not be removed unless you use the --remove
option.
In the past, the watch command would upload the current directory right away, then start watching for changes. This was changed in v2.0 to simply watch.
hs watch --account=<name> <src> <dest>
Argument | Description |
---|---|
src
Required
| Path to the local directory your files are in, relative to your current working directory |
dest
Required
| Path in HubSpot Design Tools, can be a net new path. |
Options | Description |
---|---|
--account
| Specify a Supports an alias of |
--mode
| Specify if uploaded files are published or saved as drafts in HubSpot. Learn more about using modes. |
--initial-upload
| Causes an initial upload to occur before file saves have occured. |
--remove
| Will cause watch to delete files in your HubSpot account that are not found locally. |
--notify=<path/to/file>
| log to specified file when a watch task is triggered and after workers have gone idle. |
This command is currently in beta. Let us know if you have feedback through our developer slack or using an issue in the github for the CLI.
Moves files within the developer file system from one directory to another. Does not affect files stored locally.
hs mv --account=<name> <src> <dest>
Argument | Description |
---|---|
src
Required
| Path to the remote developer file system directory your files are in. |
dest
Required
| Path to move assets to within the developer file system. |
Options | Description |
---|---|
--account
| Specify a Supports an alias of |
Creates the folder/file structure of a new asset. The supported types are module
, template
, global-partial
, website-theme
, react-app
, vue-app
and function
hs create <type> <name> [dest]
Argument | Description |
---|---|
type
Required
| Type of asset. Supported types: |
name
Required
| Name of new asset |
dest
Optional
| Destination folder for the new asset, relative to your current working directory. If omitted, this argument will default to your current working directory. |
Deletes files, or folders and their files, from your HubSpot account. This does not delete the files and folders stored locally. This command has an alias of rm.
hs remove --account=<name> <path>
Argument | Description |
---|---|
path
Required
| Path in HubSpot Design Tools |
Options | Description |
---|---|
--account
| Specify a Supports an alias of |
The HubDB commands are currently in Developer Preview. They are available to use now but understand they are subject to change. Developer previews are subject to our developer beta terms.
Using these commands you can create and delete HubDBs tables, fetch and even clear all rows of a HubDB. The HubSpot account must have access to HubDB to use these commands.
Create a new HubDB table in the HubSpot account.
hs hubdb create <src>
Argument | Description |
---|---|
src
Required
| The local JSON file to use to generate the HubDB table. |
Options | Description |
---|---|
--account
| Specify a Supports an alias of |
Download a HubDB table's data to your computer.
hs hubdb fetch <tableId> <dest>
Argument | Description |
---|---|
tableId
Required
| HubDB table id found in the HubDB dashboard. |
dest
| The local path destination to store the |
Options | Description |
---|---|
--account
| Specify a Supports an alias of |
Clear all of the rows in a HubDB table.
hs hubdb clear <tableId>
Argument | Description |
---|---|
tableId
Required
| HubDB table id found in the HubDB dashboard. |
Options | Description |
---|---|
--account
| Specify a Supports an alias of |
Deletes the specified HubDB table from the account.
hs hubdb delete <tableId>
Argument | Description |
---|---|
tableId
Required
| HubDB table id found in the HubDB dashboard. |
Options | Description |
---|---|
--account
| Specify a Supports an alias of |
When you fetch a HubDB the data is stored as tablename.hubdb.json
. When you create a new table you must specify a source JSON file. Below is an example of a table in JSON format.
// store_locations.hubdb.json
{
"name": "store_locations",
"useForPages": true,
"label": "Store locations",
"allowChildTables": false,
"allowPublicApiAccess": true,
"dynamicMetaTags": { "DESCRIPTION": 3, "FEATURED_IMAGE_URL": 7 },
"enableChildTablePages": false,
"columns": [
{ "name": "name", "label": "Name", "type": "TEXT" },
{
"name": "physical_location",
"label": "Physical Location",
"type": "LOCATION"
},
{ "name": "street_address", "label": "Street address", "type": "TEXT" },
{ "name": "city", "label": "City", "type": "TEXT" },
{
"name": "state",
"label": "State",
"options": [
{ "id": 1, "name": "Wisconsin", "type": "option", "order": null },
{ "id": 2, "name": "Minnesota", "type": "option", "order": null },
{ "id": 3, "name": "Maine", "type": "option", "order": null },
{ "id": 4, "name": "New York", "type": "option", "order": null },
{ "id": 5, "name": "Massachusetts ", "type": "option", "order": null },
{ "id": 6, "name": "Mississippi", "type": "option", "order": null },
{ "id": 7, "name": "Arkansas", "type": "option", "order": null },
{ "id": 8, "name": "Texas", "type": "option", "order": null },
{ "id": 9, "name": "Florida", "type": "option", "order": null },
{ "id": 10, "name": "South Dakota", "type": "option", "order": null },
{ "id": 11, "name": "North Dakota", "type": "option", "order": null },
{ "id": 12, "name": "n/a", "type": "option", "order": null }
],
"type": "SELECT",
"optionCount": 12
},
{ "name": "phone_number", "label": "Phone Number", "type": "TEXT" },
{ "name": "photo", "label": "Store Photo", "type": "IMAGE" }
],
"rows": [
{
"path": "super_store",
"name": "Super Store",
"isSoftEditable": false,
"values": {
"name": "Super Store",
"physical_location": {
"lat": 43.01667,
"long": -88.00608,
"type": "location"
},
"street_address": "1400 75th Greenfield Ave",
"city": "West Allis",
"state": { "id": 1, "name": "Wisconsin", "type": "option", "order": 0 },
"phone_number": "(123) 456-7890"
}
},
{
"path": "store_123",
"name": "Store #123",
"isSoftEditable": false,
"values": {
"name": "Store #123",
"physical_location": {
"lat": 32.094803,
"long": -166.85889,
"type": "location"
},
"street_address": "Pacific Ocean",
"city": "at sea",
"state": { "id": 12, "name": "n/a", "type": "option", "order": 11 },
"phone_number": "(123) 456-7891"
}
}
]
}
CMS Hub
- Enterprise
The local development tools can be used for creating and debugging serverless functions.
Prints a list of all of the account's functions, their endpoints, methods, the names of the secrets they use and last updated date.
hs functions ls --account=<name>
hs functions list --account=<name>
Argument | Description |
---|---|
--account
| The HubSpot account nickname from your hubspot.config. This parameter is required if you do not have a defaultAccount in your Supports an alias of |
--compact
| displays only endpoint names and methods. |
--json
| Output JSON into the command line with data on all of the functions. The JSON data includes, portal id, function id, route, raw asset path, method, secrets, created and last modified dates. |
Prints a log from your serverless function. Displays any console.logs
contained within your function after execution. Logs also include execution time.
hs logs <endpoint-name> --account=<name> --follow
Argument | Description |
---|---|
endpoint-name
Required
| The endpoint name as defined in your serverless.json file. It is not the path to your function file. |
Options | Description |
---|---|
--file
| Output the logs to function.log |
--follow
| Tail the logs to get a live update as you are executing your serverless functions. |
--latest
| Output only the most recent log |
--account
| The HubSpot account nickname from your hubspot.config. This parameter is required if you do not have a defaultPortal in your hubspot.config. Supports an alias of |
--compact
| hides log output/info. Returns success/error and execution time. |
--limit=<number>
| limit the amount of logs displayed in output |
If you see this error: A server error occurred: WARNING: The logs for this function have exceeded the 4KB limit.
It means your log is too large. This can be caused by trying to console log a very large object, or by lots of separate console logs. Try reducing how much you are trying to log, hit your endpoint, and run the command again.
Add a secret to your account which can be used within serverless functions. After running the command you will be prompted to enter the secret's value. To expose the secret to your function, you must edit your serverless.json
adding that secret's name to the specific endpoints you want to use it in or globally to make it available to all.
hs secrets add <secret-name>
Argument | Description |
---|---|
secret-name
Required
| Name of secret. |
secret-value
Required
| API key or other Auth detail. |
Update the value of a secret in your account which can be used within serverless functions. You will then be prompted to enter the secret's value.
hs secrets update <secret-name>
Argument | Description |
---|---|
secret-name
Required
| Name of secret. |
secret-value
Required
| API key or other Auth detail. |
Remove a secret from your account, making it no longer usable within serverless functions. After running this command, you will want to edit your serverless.json
to remove the secret's name.
hs secrets delete <secret-name>
Argument | Description |
---|---|
secret-name
Required
| Name of secret you want to remove. |
List secrets within your account to know what you have stored already using the add secrets command.
hs secrets list
There are so many parts of the HubSpot app that developers need to access frequently. To make it easier to get to these tools you can open them directly from the command line. Your defaultAccount
or --account
argument will be used to open the associated tool for that account.
hs open <shortcut-name or alias>
Argument | Description |
---|---|
shortcut
Required
| Provide the full shortcut name or alias of the short cut you wish to open in your browser. |
hs open --list
Argument | Description |
---|---|
--list
Required
| Lists all of the shortcuts, their aliases and destinations. |
If you use the CLI frequently, it can be useful to be-able-to tab to auto-complete commands.
hs completion >> ~/.bashrc
For Mac OS X
hs completion >> ~/.bash_profile
To learn about local template format annotations, refer to the templates documentation and view the templates in the CMS theme boilerplate.
Local modules are formatted in a series of files, each specifying various components of a module. To learn about developing modules locally, check out the Local Module Development Reference.
You can include a .hsignore file in your project to specify files that should not be tracked when using the CLI. This file functions similar to how .gitignore
files work. Files matching the patterns specified in the .hsignore file will not be uploaded to HubSpot when using the upload or watch commands.
By default there are some rules HubSpot automatically enforces. There is no way to override these defaults.
The following are always ignored:
hubspot.config.yml
/hubspot.config.yaml
node_modules
- dependencies.*
- hidden files/folders*.log
- NPM error log*.swp
- Swap file for Vim stateIcon\\r
- Mac OS custom Finder icon__MACOSX
- Mac resource fork~
Linux Backup fileThumbs.db
- Windows image file cacheehthumbs.db
- Windows folder config fileDesktop.ini
- Windows custom folder attribute information@eaDir
- Windows Synology diskstation "hidden" folder where the server stores thumbnails.
# ignore all files within a specific directory
/ignore/ignored
# ignore a specific file
/ignore/ignore.md
# ignore all .txt files
*.txt
# ignore all log files - useful if you commonly output serverless function logs as files.
*.log
The --mode option allows you to determine if local changes are published when uploaded to HubSpot. This option can be used in each command or set as a default in your hubspot.config.yml file.
The two options for --mode are --mode=draft and --mode=publish.
The following is the order of precedence for setting --mode:
- Using --mode in a command will override all other settings.
- Setting a defaultMode for each account in your hubspot.config.yml file, removes the need to use --mode in each command. It will override the top-level setting.
- Setting a defaultMode at the top-level in your hubspot.config.yml file, sets a default--mode for all accounts. It will override the default behavior.
- The default behavior for --mode is publish
The hubspot.config.yml file contains the credentials for your HubSpot accounts. See the Getting Started Guide for getting set up, or run the auth command to update an existing config file.
If you ran hs init
while using version v1.0.10 (released March 10, 2020) through v1.0.11 of the CLI your config file is placed at /Users/<username>/hubspot.config.yml
.
We have changed back to placing your config file in the folder you ran the command from, to make it obvious where the file is. You do not have to move your config file it will still work fine. If you prefer to keep your file with your project files, it is safe to move your file from this directory to your project folder. Do not commit this file into version control, it contains your auth credentials.
If you ran the command using any other version of the CMS-CLI your config file is placed in the folder you ran the command from.
defaultPortal: DEV
portals:
# Sample apikey entry, manually entered
- name: DEV
portalId: 123
defaultMode: 'publish'
authType: apikey
apiKey: xxxxxx-xxxxx-xxxxx-xxxxx-xxxxx
# Sample personal access key entry, generated from running hs auth personalaccesskey or hs init
- name: PROD
portalId: 456
authType: personalaccesskey
personalAccessKey: >-
xxxxx-xxxxxx-xxxxxxx-xxxxxx-xxxxx-xxxxxxx-xxxxxxxx
auth:
tokenInfo:
accessToken: >-
xxxxx-xxxxxx-xxxxxxx-xxxxxx-xxxxx-xxxxxxx-xxxxxxxx
expiresAt: '2020-01-01T00:00:00.000Z'
Name | Description |
---|---|
defaultPortal
optional
| Replaces the need to run commands using |
defaultMode
optional
| Which mode should be used for an account, draft or publish. |
allowUsageTracking
optional
| Specifies if HubSpot has permission to track usage of the local development tools. Defaults to |
Name | Description |
---|---|
portalId
required
| The account ID of the account you are setting up authentication for. |
authType
required
| Which form of authentication a given entry is using. |
name
optional
| A means to specify a name of an account, which can be used to denote which account a command should interact with. ex. |
defaultMode
optional
| Which mode should be used for an account, draft or publish. |