This article follows the official documentation. We haven’t tested this tool for a hands-on review.
A coding agent working on a HubSpot app or CMS project needs the project files and, for account tasks, a way to contact HubSpot. The HubSpot CLI, whose executable is hs, lets a coding agent use terminal commands to work with project files and a HubSpot account. Commands that upload or deploy assets change content hosted by HubSpot.
HubSpot also documents an MCP setup command. MCP, or Model Context Protocol, lets a coding assistant communicate with tools through a shared interface. The CLI can configure that connection, while you control which HubSpot actions the agent should take. The example below connects an assistant and asks it to research a migration without running it.
Install and connect the CLI
The CLI requires Node.js 20 or later. Install it globally with npm, then authenticate with a HubSpot account:
npm install -g @hubspot/cli
hs account auth
The authentication command starts HubSpot’s account authorization flow and generates a Personal Access Key for CLI access. Complete the authorization yourself. Do not put the key in an agent prompt or commit it to project files. The HubSpot installation instructions cover the prerequisites and authentication.
If you work with multiple HubSpot accounts, set the intended account as the default. The CLI then targets it without requiring an --account flag on each command. Check the HubSpot quickstart for the account setup flow.
Installing the package contacts npm, and authentication contacts HubSpot. Later commands that access an account also make network requests. Commands that only inspect or edit local files do not, though a local edit still changes your working copy.
Connect a coding assistant
After installing and authenticating the CLI, run HubSpot’s MCP setup command:
hs mcp setup
HubSpot says this command configures MCP support for a local coding environment. Restart the assistant after setup so it can load the configuration. The official developer platform announcement describes MCP help for tasks such as searching HubSpot documentation, creating projects, adding features, validating files, and uploading or deploying assets.
The announcement does not provide a complete setup walkthrough for every coding assistant, so the exact configuration details depend on the assistant you use. It describes Cursor as an example, but does not establish support for every agent. Confirm that your assistant recognizes the HubSpot connection before asking it to use HubSpot-specific tools.
For a read-only first task, ask the assistant to look up the migration command and explain its effects without running it:
Use the HubSpot connection to find the official documentation for `hs project migrate`.
Explain what it changes in a local project and what I should review before running it.
Do not run the migration, edit files, upload assets, or deploy anything.
The command hs project migrate moves an existing public app into HubSpot’s Project 2025.2 structure, bringing configuration, assets, and integrations into one directory. The example prompt asks the agent to research that change rather than make it. It should return an explanation based on the documentation; this prompt does not request a HubSpot account change.
Keep local edits separate from HubSpot changes
The CLI can edit local project files and run actions on your HubSpot account. An agent changes your working copy when it edits project files; when it uploads or deploys, it sends changes to HubSpot. Review local changes before authorizing any upload or deployment.
HubSpot documents hs project add for adding app features and hs project migrate for moving an existing app into the newer project structure. Those commands can change project files, so treat them as write actions. The developer platform announcement also says MCP can help validate files. It does not name a validation command or describe a way to preview a migration. Don’t assume that migration has a dry-run option.
When an agent can run terminal commands, authentication connects the CLI to an account, but it does not make later commands read-only. State whether the agent should edit local files, contact the account, or stop before uploading or deploying.
When the CLI fits
Use the CLI when you want an agent to work on a local HubSpot project, use HubSpot’s developer tools, or prepare assets for account tasks. For broader command syntax, start with the HubSpot CLI reference. The CLI gives an agent a way to perform documented HubSpot development tasks from the terminal; it does not make every action safe to run without review.