CMS Developer Tools

Table of contents
Close

Local Development Tooling [BETA]: Reference

⚠️ This is a beta pre-release not intended for mission-critical usage. During the beta period expect lots of changes to commands, configuration structure, and capabilities. For support with this tooling, please join the #local-dev room of the Designers and Developers Slack. Please refer to our developer beta terms. ⚠️

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

Commands

help

Show all commands.

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

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

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

sync

This command is deprecated with release 0.0.21. Use upload instead.

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 automatically be deleted from your HubSpot account.

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

create

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

npx hscms 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 command has an alias of rm.

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

Required arguments

dest
Path in HubSpot Design Tools

Options

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

auth

Generate authentication for a HubSpot using OAuth2. This will update your hubspot.config.yml file.

npx hscms auth oauth2

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, search_results_page
isAvailableForNewContent Specifies if a template is available for selection in the content creation process. true, false

Example:


<!--
  templateType: page
  isAvailableForNewContent: false
-->
<!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.

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.


defaultPortal: 'DEV'
defaultMode: 'draft'
portals:
  - name: 'DEV'
    portalId: 123
    defaultMode: 'publish'
    authType: 'apikey'
    apiKey: 'xxxxxx-xxxxx-xxxxx-xxxxx-xxxxx'

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. If you are manually entering authentication using an api key, set 'apikey'. See the auth command for details on how to automatically create an Oauth2 authentication entry.
apikey The apikey of the portal you are setting up authentication for. 
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