CMS Developer Tools

Table of contents
Close

Local Development Tooling: Reference

This outlines the available commands and file formatting for HubSpot's CMS Local Development Tooling. For a walkthrough of these new tools, see the Getting Started Guide.

Note: If you prefer, you can also use YarnHomebrew is not required but recommended for easy installation. If you are using Yarn, commands are run with the yarn prefix.

ℹ️ Did you know you can use free CMS developer sandbox accounts as development environments? Create one now by clicking "Create an Account", selecting your user, and opting to "Create a new, fresh account" here.  ℹ️

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.

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

Note: on Windows npx has a bug where it doesn't support spaces in file paths. This bug is specific to npm. Running the commands without npx and just hs works.

npx hs fetch --portal=<name> <src> [dest]

Required arguments

src
Path in HubSpot Design Tools

Optional arguments

dest
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

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

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.

Note: on Windows npx has a bug where it doesn't support spaces in file paths. This bug is specific to npm. Running the commands without npx and just hs works.

npx hs upload --portal=<name> <src> <dest>

Required arguments

src
Path to the local file, relative to your current working directory
dest
Path in HubSpot Design Tools, can be a net new path

Options

--portal
Specify a portalId or name to fetch from
--mode
Specify if uploaded files are published in HubSpot.

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: Deleted files being watched will not automatically be deleted from your HubSpot account, unless you use --remove.

Note: on Windows npx has a bug where it doesn't support spaces in file paths. This bug is specific to npm. Running the commands without npx and just hs works.

npx hs watch --portal=<name> <src> <dest>

Required arguments

src
Path to the local directory your files are in, relative to your current working directory
dest
Path in HubSpot Design Tools, can be a net new path

Options

--portal
Specify a portalId or name to fetch from
--mode
Specify if local changes are published in HubSpot.
--disable-initial
Disable the initial upload when watching a directory
--remove
Makes it so that files deleted locally while watching are deleted within HubSpot as well.

create

Creates the folder/file structure of a new asset. The supported type are module and template

Note: on Windows npx has a bug where it doesn't support spaces in file paths. This bug is specific to npm. Running the commands without npx and just hs works.

npx hs create <type> <name> [dest]

Required arguments

type
Type of asset. Must be module or template
name
Name of new asset

Optional arguments

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

Note: on Windows npx has a bug where it doesn't support spaces in file paths. This bug is specific to npm. Running the commands without npx and just hs works.

npx hs remove --portal=<name> <dest>

Required arguments

dest
Path in HubSpot Design Tools

Options

--portal
Specify a portalId or name to remove a file from

init

Sets up authentication configuration and creates a hubspot.config.yml file in the current directory for an account using a personal access key. If you need to update, or add to an existing config file, use the auth command. 

npx hs init

auth

Generate authentication for a HubSpot using a personal access key. This will update your hubspot.config.yml file.

npx hs auth personalaccesskey

Upgrade

To upgrade your version of the local tools, run npm install -g @hubspot/cms-cli@latest.

Local Template Format

HubSpot template asset options are defined via annotations at the top of .html files.

Annotation Description Values
templateType Specifies which template type a file is. page, email, blog, error_page, password_prompt_page, email_subscription_preferences_page, email_backup_unsubscribe_page, email_subscriptions_confirmation_page, global_partial, search_results_page
isAvailableForNewContent Specifies if a template is available for selection in the content creation process. true, false
enableDomainStylesheets Specifies if the template should load stylesheets defined under settings > website > pages true, false
label User friendly description of the template, displayed in the template selection screen About Page

Example:


<!--
  templateType: page
  isAvailableForNewContent: false
  enableDomainStylesheets: false
  label: Homepage
-->
<!doctype html>
<html>
...

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. If you need to add or update a config entry for an account to an existing hubspot.config.yml file, use the auth command. 


defaultPortal: DEV
defaultMode: 'draft'
portals:
  - name: DEV
    portalId: 123
    defaultMode: 'publish'
    authType: apikey
    apiKey: xxxxxx-xxxxx-xxxxx-xxxxx-xxxxx
  - name: PROD
  	portalId: 345
    authType: personalaccesskey
    personalAccessKey: >-
      xxxxxxxxx-xxxxxxx-xxxxxxx-xxxxxxx-xxxxxxxx
    auth:
      tokenInfo:
        accessToken: >-
          xxxxxxxxx-xxxxxxx-xxxxxxx-xxxxxxx-xxxxxxxx
        expiresAt: '2020-02-24T19:38:39.164Z'

Top level parameters

These optional parameters apply to all portals in your file, and are used to simplify commands.

Name Description
defaultPortal 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. 
allowUsageTracking Specifies if HubSpot has permission to track usage of the local development tools. Defaults to true. Set false to disable all tracking. 

Portals: parameters

These parameters set the authentication configuration of a specific portal.

Name Description
portalId The account ID of the portal you are setting up authentication for. 
authType 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