Last modified: September 26, 2025
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 7.7.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 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.
Deploy to HubSpot
Manually deploy the most recent build if the project is not set to auto-deploy.
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. |
Sandbox commands
Interact with standard sandboxes and development sandboxes using the commands below.
Create a sandbox
Creates a new sandbox in a production account. When running this command, you can select whether you want to create a standard sandbox or a development sandbox.
If creating a standard sandbox, when running this command, all supported assets will be synced from production to the standard sandbox by default. You can choose to trigger a one-time sync of the last updated 5,000 contacts and, if applicable, up to 100 associated companies, deals, and tickets (for each associated object type).
A production account can have one standard sandbox and two development sandboxes at a time. Additional standard sandboxes can be purchased as an add-on. Learn more about development sandbox limits.
Delete a sandbox
Deletes a sandbox connected to the production account. Follow the prompts to select the sandbox account to delete, then confirm the permanent deletion.
Create and use development sandboxes
Development sandboxes are only available in accounts with an Enterprise subscription.
- A production account can have only one development sandbox at a time.
- CRM object definitions are synced from the production account to the development sandbox at the time of sandbox creation.
- You cannot create a sandbox within another sandbox.
Create a development sandbox
To set up a development sandbox account:
-
Because development sandboxes are created within the
defaultPortal in your hubspot.config.yml file, first confirm that your production account is connected and set as the default:
-
In the terminal, run
hs accounts list.
-
In your list of connected accounts, confirm that your production account is listed as the default account.
-
If your production account is not the default, run
hs accounts use and select your production account.
-
After confirming your production account is the default, run
hs sandbox create.
-
You’ll then be prompted to select a type of sandbox to create. Select Development sandbox, then press Enter.
-
Enter a
name for the sandbox account, then press Enter.
-
All CRM object definitions will be copied from production to the development sandbox.
-
You can use the import tool to import production object record data, or manually create sample data for testing.
-
The CLI will then begin the sandbox setup process. Once the sandbox is fully set up and synced, you’ll see a Sandbox sync complete confirmation.
With your development sandbox created, it will appear under the associated production account when running hs accounts list.
If you want to set the development sandbox as your default account, run hs accounts use, then select the sandbox. To deploy to your sandbox or production account, you can either run hs accounts use to set the default account, or manually select the account when uploading by running hs project upload --account=<name-of-account>.
Development sandboxes are designed to be early proof of concept environments. It is recommended to delete and create a new Development Sandbox using the CLI. This ensures development sandboxes always have an exact mirror of the production account’s CRM object definitions when beginning new projects.
After setting up your development sandbox, learn how to create a UI extension, or learn more about creating apps.
View a development sandbox in HubSpot
By default, all super admin users are synced to the development sandbox during creation. Super admins can give other users access by adding them as users to the development sandbox.
To access the development sandbox account in HubSpot:
- In your HubSpot account, navigate to CRM Development in the main navigation bar.
- In the left sidebar menu, select Sandboxes.
- Click the Development tab, where your new sandbox will be listed along with its name, create date, and the user who created it.
- To navigate to the sandbox account, click the development sandbox name.
Once a user has been granted access to a development sandbox, they can access it by clicking the Profile picture in the top right of HubSpot, then clicking the Account selection menu and selecting the account.
Sync CRM data manually
To trigger an on-demand sync of CRM contact records and associated deals, tickets, and companies from a standard HubSpot account to your development sandbox, run the following command:
Delete a development sandbox
- To delete a development sandbox using the CLI, run
hs sandbox delete, then follow the prompts.
- To delete a development sandbox in HubSpot:
- In your HubSpot account, navigate to CRM Development in the main navigation bar.
- In the left sidebar menu, select Sandboxes.
- Click the Development tab.
- Hover over the development sandbox, then click Delete.
