Local Development Tooling: CMS CLI Reference

Last updated:

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.

Watch
Fork
Star

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.

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.

Install

To install the HubSpot tools globally, run npm install -g @hubspot/cms-cli in your command line. To install the tools in your current directory, run npm install @hubspot/cms-cli.

Commands

help

Show all commands.

Shell script 
hs help

fetch

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.

Shell script 
hs fetch --portal=<name> <src> [dest]
hs filemanager fetch --portal=<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
--portal

Specify a portalId or name to fetch from

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

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.

Shell script 
hs upload --portal=<name> <src> <dest>
hs filemanager upload --portal=<name> <src> <dest>
Argument Description
src
Required

Path to the local file, relative to your current working directory.

dest
Optional

Path in HubSpot Design Tools, can be a net new path.
Options Description
--portal

Specify a portalId or name to fetch from

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

watch

Watch your local directory and automatically upload changes to your HubSpot account on file saves. 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.

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.

Shell script 
hs watch --portal=<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
--portal

Specify a portalId or name to fetch from

--mode

Specify if uploaded files are published in HubSpot. Click here for more info.

--disable-initial

Disable the initial upload when watching a directory

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

create

Creates the folder/file structure of a new asset. The supported types are module, template, global-partial, website-theme, react-app and function

Shell script 
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.

remove

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.

Shell script 
hs remove --portal=<name> <dest>
Argument Description
dest
Required

Path in HubSpot Design Tools
Options Description
--portal

Specify a portalId or name to remove a file from

init

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. 

Shell script 
hs init

auth

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 portals. For example you might use your sandbox account as a development environment.

Shell script 
hs auth personalaccesskey

Serverless Commands

APPLICABLE PRODUCTS
  • CMS Hub
    • Enterprise

The local development tools can be used for creating and debugging serverless functions.

logs

Prints a log from your serverless function. Displays any console.logs contained within your function after execution. Logs also include execution time.

Shell script 
hs logs <endpoint-name> --portal=<portal> --file
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

--portal

The HubSpot account nickname from your hubspot.config. This parameter is required if you do not have a defaultPortal in your hubspot.config.

--compact

hides log output/info. Returns success/error and execution time.

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 logs. Try reducing how much you are trying to log.

add secret

Add a secret to your account which can be used within serverless functions. After running this command, you must edit your serverless.json to expose that secret's name to the specific endpoints you want to use it in or globally.

Shell script 
hs secrets add <secret-name> <secret-value>
Argument Description
secret-name
Required

Name of secret.

secret-value
Required

API key or other Auth detail.

remove secret

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.

Shell script 
hs secrets delete <secret-name>
Argument Description
secret-name
Required

Name of secret you want to remove.

list secrets

List secrets within your account to know what you have stored already using the add secrets command.

Shell script 
hs secrets list

Upgrade

To upgrade your version of the local tools, run:

Shell script 
npm install -g @hubspot/cms-cli@latest

Local Template Format

To learn about local template format annotations, refer to the templates documentation and view the templates in the CMS theme boilerplate. 

Local Module Format

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.

.hsignore

You can include a .hsignore file in your project to specify files that should not be tracked when using the CLI. Files matching the patterns specified in the .hsignore file will not be uploaded to HubSpot when using the upload or watch commands.

Modes

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:

  1. Using --mode in a command will override all other settings.
  2. Setting a defaultMode for each portal in your hubspot.config.yml file, removes the need to use --mode in each command. It will override the top-level setting.
  3. Setting a defaultMode at the top-level in your hubspot.config.yml file, sets a default--mode for all portals. It will override the default behavior.
  4. The default behavior for --mode is publish

Authentication

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.

YAML 
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'

Top level parameters

Name Description
defaultPortal
optional

Replaces the need to run commands using --portal= to specify which portal you are interacting with. If --portal= is not specified when running a command, the defaultPortal will be used.

defaultMode
optional

Which mode should be used for a portal, draft or publish. 

allowUsageTracking
optional

Specifies if HubSpot has permission to track usage of the local development tools. Defaults to true. Set false to disable all tracking. 

Portals: parameters

Name Description
portalId
required

The account ID of the portal you are setting up authentication for.

authType
required

Which form of authentication a given entry is using. personalaccesskey or apikey. NOTE: You must additionally set a config parameter for your authentication methods value. See the above example config file for how to set your personalAccessKey or apiKey in addition to specifying the authType.

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. --portal=123 and --portal=DEV will both interact with account ID 123 based on the above example.

defaultMode
optional

Which mode should be used for a portal, draft or publish.