The HubSpot command line interface (CLI) connects your local development tools to HubSpot, allowing you to develop on HubSpot with version control, your favorite text editor, and various web development technologies.
Below, learn about the CLI commands available while you’re developing with HubSpot projects. You can also refer to the standard CLI commands reference for general commands such as hs auth.
The latest version of the HubSpot CLI, which is recommended, is 8.0.0. You can check which version of the CLI you have installed by running hs --version.
You can run hs project --help at any time in your terminal to learn more about project-specific commands.
Update the CLI
Update your CLI to the latest version.
npm install -g @hubspot/cli@latest
View all commands
List all project-specific CLI commands.
To learn more about a specific command, enter the command followed by --help.
Create a new project
Create a project in a specified directory. You’ll be prompted to give the project a name, confirm the local location on your computer, and specify additional configuration details.
A new folder will be created in the specified directory containing an hsproject.json file and an src folder where you’ll build out your project components.
Once you’ve created a project, you can run other project commands inside your project directory and HubSpot will automatically recognize your project.
hs project create [flags]
| Flag | Description |
|---|
--name | The name of the project (cannot be changed once created). |
--dest | The full path for the directory where the project should be created. |
--platform-version | The target platform version for the new project. Defaults to 2025.2. |
--project-base | The top level component to include in the project. Available options are empty or app. |
--distribution | How the app will be distributed. Available options are private or marketplace. |
--auth | Authentication model for the application. Available options are oauth or static. |
--features | Array of space-separated features to include in the project. Only valid if the project-base is app. Available options include: |
--debug | Set log level to debug (defaults to false). |
--account | HubSpot account ID or name from config. |
--config | Path to a config file. |
--use-env | Whether to use environment variable config (defaults to false). |
--template | The starting template. This option is only available for when the targeted platform version is less than 2025.2, but isn’t required. |
--template-source | Path to custom GitHub repository from which to create project template. |
Add a feature to a project
To add a new feature to an existing app, run the following command:
If no flags are provided, you’ll be prompted to specify which features to add, using the keyboard to navigate and make your choices:
- Press spacebar to select a feature.
- Press the a key to toggle all features.
- Press the i key to invert your current selection.
- Press the enter key to confirm your choices and proceed.
| Flag | Description |
|---|
--features | Array of space-separated features to include in the project. Available options include: |
Upload to HubSpot
Upload the project to your HubSpot account and create a build. If the project hasn’t been created in the account yet, you’ll be asked whether you want to create it.
If the project is configured to auto-deploy, this command will automatically deploy after the build is successful. By default, new projects are set to auto-deploy.
You can upload a project to a specific account in your ~/.hscli/config.yml file by adding --account=accountName to the command. For example, hs project upload --account=main. This can be useful when switching between uploading to a sandbox account and then uploading to the main account. For example, your workflow might look like:
- When developing your project in a sandbox, you upload changes with
hs project upload --account=sandbox.
- Then when uploading the project to a main account, you upload the project with
hs project upload --account=main.
You can use the same configuration when using the watch command.
Download from HubSpot
Download the last uploaded version of a project to your local computer.
Deploy to HubSpot
Manually deploy the most recent build if the project is not set to auto-deploy.
Install dependencies
Install dependencies (either from HubSpot or a third-party library) for your project, or add a dependency to a project subcomponent.
hs project install-deps [packages..]
hs project install-deps dependency1 dependency2).
Update dependencies
Update dependencies (either from HubSpot or a third-party library) for your project, or update the specific dependencies for a project subcomponent.
hs project update-deps [packages..]
hs project update-deps dependency1 dependency2).
Migrate a public app
Migrate an existing public app to the new developer projects framework (v2025.2). Learn more in the public app migration guide.
Start a local development server
Start a local development server to view extension changes in the browser without needing to refresh. With the server running, saving changes to any JSX files when you’re developing an app card or settings page using UI components will cause the page to automatically refresh. This does not include changes made to the .json config files, which need to be manually uploaded using the hs project upload command instead.
As of
Google Chrome version 142, you will receive a one time time popup asking for
app.hubspot.com to access devices on your local network. Select
Accept to enable local development for your apps.
You can also manage this setting in your Chrome settings by navigating to
Settings >
Privacy & Security >
app.hubspot.com >
Permissions >
Local network access.
Open project in HubSpot
Opens the project in HubSpot where you can view the project’s settings, build history, and more. By default, will attempt to open the project in the default account set in ~/.hscli/config.yml. Specify an account by adding the --account=accountName flag.
Watch for changes
Watches the project directory and uploads to HubSpot upon saving, including deleting files. Each upload will result in a new build with a new build ID. A successful build will deploy automatically if the project’s auto-deploy setting is turned on.
You can further configure watch to send changes to a specific account with ---account=accountName. For example, hs project watch --account=main.
View logs
Get logs for a specific function within a project.
Running this command will guide you through selecting the project and app to get logs for. However, you can also manually specify this information by including the following flags in the command:
| Flag | Description |
|---|
--project=projectName | The name of the project as set in the hsproject.json file. |
--app=appName | The name of the app as set in the app.json file. |
Analyze and validate code
To validate the configuration of your project components like your app cards and settings pages, you can statically analyze your project using ESLint v9.
This command will check for and configure the required devDependencies for each project component, and define each dependency and its minimum version.
This will create an ESLint configuration file for each project component, and warn about existing ESLint files that are deprecated (non-flat files created before ESLint v9).
Note that any existing v9 ESLint configuration files that you’ve already created will not be overwritten and your existing configuration will be used instead.
