Connect directly with our accredited consultant to get clear answers on your HubSpot underutilized features, integrations, reporting and automation.
HubSpot Consulting Needs
Custom Automation Plan 
If you’ve worked with HubSpot CMS development for even a short while, chances are you’ve come across the powerful but sometimes puzzling HubSpot CLI.
One common point of confusion? The behavior of the hs upload command—when dealing with folders and subdirectories.
In this blog, we’ll break down exactly how to use hubspot hs upload with folders and subdirectories, explore common issues (like why hubspot hs upload folder and subdirectories not working shows up so often in community threads), and show how to resolve them based on years of HubSpot CMS project experience.
The hs upload command is part of the HubSpot CLI, a tool that allows developers to interact with their HubSpot CMS environment directly from their local machine.
Its essential for syncing code from local development environments to HubSpot Design Manager.
hs upload <localPath> <hubspotDestination>
Lets say you have a theme folder called my-theme with multiple nested files and directories:
my-theme/
│
├── templates/
│ └── homepage.html
├── modules/
│ └── hero.module
└── assets/
└── style.css
To upload the entire folder and its structure to HubSpot designs directory, you might expect this command to work:
hs upload my-theme my-theme
The entire structure—templates, modules, assets—should be uploaded to the HubSpot file manager or design tools.
Subdirectories are retained.
File paths remain consistent across environments.
A frustrating issue for many developers is running hs upload and finding:
Subdirectories didn’t upload.
The CLI reports success, but files are missing.
An error like: Error: Path does not exist or Must specify destination folder.
So whats going wrong?
HubSpot destination path must already exist. If you’re trying to upload into a directory that doesn’t yet exist in the HubSpot Design Manager, it can fail silently or misplace your files.
Fix
Ensure the remote folder exists or let the CLI create it by giving a valid destination.
hs upload my-theme my-theme
If the my-theme directory doesn’t exist remotely, it will be created.
Using relative vs. absolute paths in local systems can confuse the CLI, especially if you’re not in the right working directory.
Fix
Run the upload command from the root of your local theme folder or specify a clear relative path:
cd ~/dev/hubspot/themes/
hs upload ./my-theme my-theme
MacOS, for example, can insert .DS_Store files that may trip the upload process or cause permission errors.
Fix
Use .hsignore or pre-clean your folders before uploading:
find . -name ‘.DS_Store’ -type f -delete.
Open Terminal in your project root
Check your HubSpot CLI is authenticated
hs auth list
Test a dry-run with hs fetch to make sure destination folder exists.
hs fetch my-theme ./temp-check
Upload with the correct command
hs upload my-theme my-theme
This ensures that my-theme from your local directory is mirrored inside HubSpot Design Tools.
| Issue | Probable Cause | Solution |
|---|---|---|
| Subfolders not uploading | Incorrect working directory | Use correct relative path |
| Files missing | Destination folder misnamed | Double check destination |
| CLI error: “Must specify destination” | Missing argument | Add target folder path |
| Permissions error | OS system files interfering | Clean directory before upload |
hs watch for Continuous SyncOnce the initial upload works, consider switching to hs watch for continuous syncing:
hs watch my-theme my-theme
This command watches your local directory for changes and automatically syncs updates to HubSpot—ideal for rapid theme development.
Just make sure the destination path is correct, or it may throw the common error:
“hs watch asking for destination path”
You may wonder—should I use hs upload or just rely on VS Code HubSpot integration?
Heres the short answer:
Use CLI (hs upload) for full folder uploads, automation, and scripting.
Use VS Code UI for one off file edits or quick pushes.
For enterprise grade projects, CLI is more reliable, faster, and better for CI/CD workflows.
When used correctly, hubspot hs upload folder and subdirectories is a powerful way to move code from local to cloud.
But when it misfires, it can cost hours in debugging and guesswork.
Hopefully, with the tips above, you can avoid the most common pitfalls and make the most of your CLI-based development workflow.
How Much Does It Cost To Be a HubSpot Agency
Does HubSpot Integrate with Salesforce
