COS Documentation

Search HubSpot Designers Site

Beta - COS Uploader

Edit COS assets locally and have them instantly synced to the COS

This beta feature requires API access; therefore, it is only available to be used with Professional and Enterprise HubSpot portals.

The COS Uploader is a command application that you can run on your local computer. The uploader will watch files in your asset folders, and automatically publish them to the HubSpot servers. You can edit your files in the IDE of your choice (Sublime, Emacs, Dreamweaver, whatever you want), save your file, and then reload your site in your web browser and immediately see your changes.

Once you have installed the uploader, you can go through one our tutorials

Help and support for the uploader is provided via the HubSpot forums:


The uploader is not a bidirectional sync. It simply pushes file updates from your local folders to the HubSpot COS instance.

Installing on MacOSX

  • Open up Terminal
  • Go to the folder with your assets.
  • Your asset folder should have one or more subfolders for "templates", "styles", or "files"
  • Run the following commands to download the binary and make it executable:
curl -L -o upload_to_cos ""

chmod 700 upload_to_cos
  • Now you can run the upload watcher:

To get all the options, run with the help flag:

./upload_to_cos -h

Here is a video showing the installation

Installing on Windows

Download the uploader executable from here:

Drag the downloaded file into the folder with your assets. Double click the file to run it, give it permission when the security dialog pops up, then follow the instructions.

You can also run this executable from the command line or install it into your system path so you can run the command from any folder.

Basic Usage

The expected folder structure is:

  • files/
  • templates/

files contain static assets such images, javascript, css, etc.

templates contain files with HubSpot Markup Language. "templates" contain tokens and tags that indicate editable areas for the end customer to edit via the UI. Templates also contain dynamic logic.

When you run the uploader, any relative links in a template file to a static file will be converted to the proper URL in our cloud content delivery network.

All files in templates must have a section in the file for metadata. The metadata is in JSON format and enclosed between two metadata tokens.

Here is an html example: template...
"category": "page", 
"creatable": false, 
"path": "custom/pages/my-folder/my-file.html"


This section can be put anywhere in the file. It will be stripped from the file when uploaded. You can also surround the block with comment tokens to avoid errors when developing locally.

The path parameter controls where the template will show up in template builder. This path can also be used in {% include %} statements by other templates.

Allowed values for category are: email, blog, asset or include. Set to page if you want to be able to create a new landing page or site page with this template. Set to asset for css or javascript files. Set to include for any template that will be included by another template, as opposed to being used directly.

The creatable parameter should be set to true when you want to show this template in the new page, blog post, or email creation screen.

You can set creatable to false while you initially work on your template, and then change it to true when you are ready to create a page with it.

If creatable is true, then the template must have valid source content for that category. For instance, an email template must have CAN-SPAM and unsubscribe tokens and a page template must have the {{standard_header_includes}} and {{standard_footer_includes}} tokens.

View the tutorials on how to use the COS Uploader

Got questions? Help and support for the uploader is provided via the Designers forum on

Want to play with the source of the COS uploader and add your own enhancements? The COS Uploader is open source on GitHub.