App and project CLI commands

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.

You can run hs project --help at any time in your terminal to learn more about project-specific commands.

View all commands

List all project-specific CLI commands.

hs project help

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]

The available flags are provided in the table below, but aren’t required to run the command. If no flags are provided, you’ll be prompted to enter your choices for the project’s name, destination, project base, distribution, authentication type, and features, if applicable. 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 `2026.03`.
`--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: `card`: add support for app cards. `settings`: add support for an app settings page `page`: add support for an app page `webhooks`: set up webhook subscriptions. `workflow`: create a workflow action `scim`: Configure SCIM
`--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:

hs project add [flags]

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: `card`: add support for app cards. `settings`: add support for an app settings page `page`: add support for an app page `webhooks`: set up webhook subscriptions. `workflow`: create a workflow action `scim`: Configure SCIM

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.

hs project upload [flags]

Flags

Flag	Description
`--skip-auto-deploy`	Whether to skip automatic deployment after a successful upload.

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.

hs project download

Deploy to HubSpot

Manually deploy the most recent build if the project is not set to auto-deploy.

hs project deploy

List builds

List build history for a project.

hs project list-builds [flags]

Flags

Flag	Description
`--account`	Filter projects by a specific account ID or a name from the current config.
`--config`	Path to a config file.
`--use-env`	Whether to use environment variable config.
`--project`	Name of the project.
`--limit`	Limit the number of builds to output.

List projects

Display existing projects that have already been uploaded to your account.

hs project list [flags]

Flags

Flag	Description
`--account`	Filter projects by a specific account ID or a name from the current config.
`--config`	Path to a config file.

View logs for an installed app

Review and filter logs for one of your apps directly from the command line.

hs app logs [flags]

Flags

Flag	Description
`--account`	Filter logs by a specific account ID or a name from the current config.
`--config`	Path to a config file.
`--use-env`	Whether to use environment variable config.
`--app`	The ID of the app to retrieve logs for.
`--type`	Filter logs by a specific feature or message type. Available values are: `webhooks`, `api-call`, `serverless-execution`, `crm-extensibility-card`, `crm-legacy-card`, `extension-log`, `extension-render`, `app-settings`, `proxy-execution`, `serverless-gateway-execution`, `acceptance-test`, or `oauth-authorization`.
`--json`	Whether to output logs as JSON.
`--limit`	Maximum number of log messages to return.
`--since`	Filter logs to return results within a provided time increment or timestamp (1h, 30m, 2d, or ISO timestamp).
`--tail`	Whether to follow logs in real-time.
`--errors-only`	Whether to only show error logs.
`--compact`	Whether to display logs in compact format (one line per log).

View specific log entry for an installed app

Review the full details of a specific log entry for one of your installed apps. Details include request and response bodies, additional context, and error information.

hs app logs <log-id> [flags]

Arguments

Argument	Description
`log-id`	The log ID entry to review.

Flags

Flag	Description
`--account`	Filter log entries by a specific account ID or a name from the current config.
`--config`	Path to a config file.
`--use-env`	Whether to use environment variable config.
`--app`	The ID of the app to retrieve the log entry for.
`--type`	Filter log entries by a specific feature or message type. Available values are: `webhooks`, `api-call`, `serverless-execution`, `crm-extensibility-card`, `crm-legacy-card`, `extension-log`, `extension-render`, `app-settings`, `proxy-execution`, `serverless-gateway-execution`, `acceptance-test`, or `oauth-authorization`.
`--json`	Whether to output log entry details as JSON.

Install app in an account using static auth

Install your app in a HubSpot account using a static auth token.

hs project install-app [flags]

Flags

Flag	Description
`--account`	Install the app in a specific account by ID or name.
`--config`	Path to a config file.
`--use-env`	Whether to use environment variable config.
`--force`	Whether to skip all confirmation prompts.
`--profile`	The profile to target with this install.
`--json`	Whether to output log entry details as JSON.

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..]

You can explicitly install specific packages by adding them as arguments (e.g., 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..]

You can explicitly update specific packages by adding them as arguments (e.g., hs project update-deps dependency1 dependency2).

Migrate a public app

Migrate a public app to the projects framework. Use this command for non-project-based legacy public apps. Learn more in the migration overview.

hs app migrate

Migrate an existing project

Migrate an existing project to the new version of the projects framework. Use this command for apps that are already project-based but use an older version of the developer platform. Learn more in the app migration guide.

hs project migrate

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.

hs project dev

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.

hs project open

Get project information

Display project and app metadata, including details for any components you’ve configured such as app cards or serverless functions.

hs project info [flags]

Flags

Flag	Description
`--json`	Output project information in JSON format, which can be useful for scripting or providing to AI agents.

Watch for changes

Please note: this command has been deprecated in favor of hs project dev.

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.

hs project watch

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.

hs project logs

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: Flags

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.

hs project lint

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.

Validate project

Verify that your project’s app-hsmeta.json configuration file is valid and your project is ready to upload to your HubSpot account.

hs project validate

Flags

Flag	Description
`--account`	Filter projects by a specific account ID or a name from the current config.
`--config`	Path to a config file.
`--use-env`	Whether to use environment variable config (defaults to false).

Delete a project

Delete a project from your HubSpot account. You will be prompted to confirm the deletion before proceeding. You can use the --force flag to bypass this confirmation.

hs project delete [flags]

Flag	Description
`--project`	Name of the project to delete.
`--force`	Bypass the confirmation prompt and immediately delete the project once the command is executed.

Add project profile

Add a new project profile, which allows you to reference variables in your component configuration files. Learn more about using config profiles.

hs project profile add

Flags

Flag	Description
`--target-account`	The account ID or name to associate with this profile.

Delete project profile

Delete an existing project profile.

hs project profile delete [name]

Arguments

Argument	Description
`name`	The name of the existing profile you want to delete.

Check app install status

Check whether a static auth app in the current project is installed in the target account. This command must be run from within a HubSpot project directory.

hs project app-install-status [flags]

Flags

Argument	Description
`accountId`	The ID of the HubSpot account where you’re attempting to install the app.

​View all commands

​Create a new project

​Add a feature to a project

​Upload to HubSpot

​Download from HubSpot

​Deploy to HubSpot

​List builds

​List projects

​View logs for an installed app

​View specific log entry for an installed app

​Install app in an account using static auth

​Install dependencies

​Update dependencies

​Migrate a public app

​Migrate an existing project

​Start a local development server

​Open project in HubSpot

​Get project information

​Watch for changes

​View logs

​Analyze and validate code

​Validate project

​Delete a project

​Add project profile

​Delete project profile

​Check app install status

View all commands

Create a new project

Add a feature to a project

Upload to HubSpot

Download from HubSpot

Deploy to HubSpot

List builds

List projects

View logs for an installed app

View specific log entry for an installed app

Install app in an account using static auth

Install dependencies

Update dependencies

Migrate a public app

Migrate an existing project

Start a local development server

Open project in HubSpot

Get project information

Watch for changes

View logs

Analyze and validate code

Validate project

Delete a project

Add project profile

Delete project profile

Check app install status