Development environment/CLI/deployment workflow

HubSpot CLI setup and authentication

The HubSpot CLI (command line interface) A bidirectional sync tool between your local file system and the HubSpot portal. Rather than operating the design manager on a browser, Fast development with editor and terminalis the biggest advantage.

① Installing Node.js and CLI

# Requires Node.js 20 or higher (required for v8.0.0 or later). Check version
$ node --version
v20.x.x ← Must be 20 or more (18.x is NG)

# Globally install HubSpot CLI with npm
$ npm install -g @hubspot/cli

# Confirm installation (v8.0.0 or higher recommended)
$ hs --version
8.x.x

# or run each time with npx (no installation required)
$ npx @hubspot/cli --version

② Authentication settings (first time only)

# initialize in project root
$ hs init# Setup proceeds interactively
? Enter a name for this account (e.g. "my-sandbox"): my-company-dev
? Enter your HubSpot portal ID: 12345678
? How would you like to authenticate your account?
  ❯ Personal Access Key (recommended)
    OAuth2

# Select Personal Access Key and your browser will open.
# You can issue a Personal Access Key from the HubSpot admin screen
# Obtained from Developer Accounts → Account → Personal Access Keys

? Enter your personal access key: eu1-xxxx-xxxx-xxxx-xxxx
✔ Authenticated account: my-company-dev (12345678)
✔ Config file created: ~/.config/@hubspot/cli/config.yml

③ Check the configuration file for the project

hs init When you run hubspot.config.yml will be generated. This file is the starting point for CLI configuration.

defaultPortal: my-company-dev
portals:
  - name: my-company-dev
    portalId: 12345678
    authType: personalaccesskey
    personalAccessKey: eu1-xxxx-xxxx-xxxx-xxxx
    auth:
      tokenInfo:
        accessToken: CJa...
        expiresAt: '2024-12-31T00:00:00.000Z'

CLI full command reference

Old command → new command correspondence table

List of main commands (v8 new system)

Practical usage of commands (v8 compatible)

# ===== Upload the entire theme =====
$ hs cms upload ./src/my-theme @my-theme --portal=my-company-dev

# ===== Start watch mode during development =====
$ hs cms watch ./src/my-theme @my-theme --portal=my-company-dev
Watcher started, watching "./src/my-theme"
Uploaded "templates/page.html" to "@my-theme/templates/page.html"
Uploaded "modules/hero-banner.module/module.html"

# ===== Get the latest from HubSpot (before checking the difference) =====
$ hs cms fetch @my-theme ./src/my-theme-remote --portal=my-company-prod --overwrite

# ===== Lint check before deployment =====
$ hs cms lint ./src/my-theme --portal=my-company-dev
✔ No lint errors found

# ===== Upload only specific files =====
$ hs cms upload ./src/my-theme/modules/hero-banner.module @my-theme/modules/hero-banner.module

# ===== Generate new module template =====
$ hs cms module pricing-table --path=./src/my-theme/modules
✔ Created "pricing-table.module" at ./src/my-theme/modules/pricing-table.module

# ===== Check portal file list =====
$ hs cms list --portal=my-company-prod
@my-theme/
├── templates/
├── modules/
├── css/
├── js/
└── theme.json

Utilizing hs cms lint

$ hs cms lint ./src/my-theme

✖ Error in "templates/blog-post.html" line 42:
  Unexpected tag: endmodule (did you mean end_module?)

⚠ Warning in "modules/card-grid.module/module.html" line 18:
  Variable "module.subtitle" used but not defined in fields.json

Lint complete: 1 error, 1 warning

# Rerun after fixing the error
$ hs cms lint ./src/my-theme
✔ No lint errors found (1 warning)

Local development flow (watch mode)

Development in practice hs cms watch Use the editor with . Every time you save a file, it's automatically uploaded to HubSpot. You can check it immediately by reloading your browser.

Recommended directory structure

my-project/
├── src/                         # ← Files to be synchronized using CLI
│   └── my-theme/               # Theme body
│       ├── theme.json
│       ├── templates/
│       ├── modules/
│       ├── css/
│       ├── js/
│       └── images/
├── .gitignore
├── .hsignore                    # define files that CLI ignores
├── hubspot.config.yml           # Authentication settings (add to .gitignore)
├── package.json                  # Define development commands with npm scripts
└── README.md                    # Setup instructions documentation

Organize commands in package.json

{
  "name": "my-company-hubspot",
  "version": "1.0.0",
  "scripts": {

    // ===== Development commands =====
    "dev": "hs cms watch src/my-theme @my-theme --portal=dev",
    // Start watch mode with npm run dev (sync to dev portal)

    // ===== Deploy command =====
    "deploy:dev"  : "hs cms upload src/my-theme @my-theme --portal=dev --overwrite",
    "deploy:prod" : "hs cms upload src/my-theme @my-theme --portal=prod --overwrite",

    // ===== Check command =====
    "lint"       : "hs cms lint src/my-theme --portal=dev",
    "fetch:prod"  : "hs cms fetch @my-theme src/my-theme-remote --portal=prod --overwrite",

    // ===== Compound command =====
    "predeploy:prod": "npm run lint"
    // Automatically run lint before deploy:prod (aborts deployment if there is an error)
  },
  "devDependencies": {
    "@hubspot/cli": "^8.0.0"
    // Specify CLI v8 or higher (Node.js 20 required)
  }
}

# === At the start of daily development ===
$ npm run devWatcher started, watching "src/my-theme"
# Edit the file in the editor → Save → Automatically upload → Confirm reload in the browser

# === Stop watch with Ctrl+C when finished ===

# === Checks before production deployment ===
$ npm run lint✔ No lint errors found

# === Production deployment (executed only if lint passes) ===
$ npm run deploy:prodUploading "src/my-theme" to "@my-theme" on portal "prod"...
✔ Done uploading 48 files

Management strategy for multiple portals (separation of development and production)

In the actual caseDevelopment portal (Sandbox/Developer Account)and User privilege managementseparate and manage. Watching the production environment directly is strictly prohibited as it may cause accidents.

Overview of portal configuration

hubspot.config.yml configuration for multiple portals

# Default portal (used when --portal is omitted in hs cms upload)
defaultPortal: dev

portals:
  # ===== Development portal (for daily development) =====
  - name: dev
    portalId: 11111111
    authType: personalaccesskey
    personalAccessKey: eu1-dev-key-xxxxxxxxxx

  # ===== Production portal (only when deploying) =====
  - name: prod
    portalId: 22222222
    authType: personalaccesskey
    personalAccessKey: eu1-prod-key-xxxxxxxxxx

  # ===== For client verification (optional) =====
  - name: staging
    portalId: 33333333
    authType: personalaccesskey
    personalAccessKey: eu1-staging-key-xxxxxxxxxx

Operation rules by portal

Synchronization exclusion settings using .hsignore

.hsignore The file is .gitignore In the same format as hs cms upload or hs cms watch Specify the files and directories that you do not want to synchronize.

Advanced settings in hubl.config.yml

hubspot.config.yml In addition to authentication information, There are options to further customize CLI behavior.

defaultPortal: dev

# ===== CLI global settings =====
httpTimeout: 30000
# API request timeout (ms)
# Increase this value when uploading large themes

allowUsageTracking: false
Move under cms subcommand

portals:
  - name: dev
    portalId: 11111111
    authType: personalaccesskey
    personalAccessKey: eu1-dev-key

    # ===== Portal individual settings =====
    defaultMode: write
    # write (upload priority) / read (download priority)

  - name: prod
    portalId: 22222222
    authType: personalaccesskey
    personalAccessKey: eu1-prod-key
    defaultMode: write

Integration with GitHub and GitHub Actions CI/CD

By linking Git repositories and GitHub Actions, "Automatically deploy to production once merged into main branch" You can build a CI/CD pipeline called

branch strategy

Configuring GitHub Secrets

Register your Personal Access Key to Secrets in your GitHub repository. Configure from the GitHub repository page → Settings → Secrets and variables → Actions.

Implementing GitHub Actions workflows

name: Deploy to Dev Portalon:
  push:
    branches:
      - develop

jobs:
  deploy:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      - name: Install HubSpot CLI
        run: npm install -g @hubspot/cli

      - name: Create HubSpot config
        # Dynamically generate hubspot.config.yml from Secrets
        run: |
          cat > hubspot.config.yml << EOF
          defaultPortal: dev
          portals:
            - name: dev
              portalId: ${{ secrets.HUBSPOT_PORTAL_ID_DEV }}
              authType: personalaccesskey
              personalAccessKey: ${{ secrets.HUBSPOT_ACCESS_KEY_DEV }}
          EOF

      - name: Lint check
        run: hs cms lint src/my-theme --portal=dev

      - name: Deploy to Dev
        run: hs cms upload src/my-theme @my-theme --portal=dev --overwrite

      - name: Notify Slack on success
        if: success()
        uses: slackapi/slack-github-action@v1
        with:
          payload: |
            {
              "text": "✅ 開発環境へのデプロイ完了: ${{ github.event.head_commit.message }}"
            }
        env:
          SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}

name: Deploy to Productionon:
  push:
    branches:
      - main

jobs:
  lint:
    name: Lint Check
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: '20' }
      - run: npm install -g @hubspot/cli
      - name: Create config
        run: |
          cat > hubspot.config.yml << EOF
          defaultPortal: dev
          portals:
            - name: dev
              portalId: ${{ secrets.HUBSPOT_PORTAL_ID_DEV }}
              authType: personalaccesskey
              personalAccessKey: ${{ secrets.HUBSPOT_ACCESS_KEY_DEV }}
          EOF
      - run: hs cms lint src/my-theme --portal=dev

  deploy:
    name: Deploy to Production
    needs: lint        # Execute only if lint job is successful
    runs-on: ubuntu-latest
    environment: production   New creation of the old API key (hapikey parameter) will be discontinued after November 2022.
      Whenever you update an existing integration,

    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: '20' }
      - run: npm install -g @hubspot/cli

      - name: Create production config
        run: |
          cat > hubspot.config.yml << EOF
          defaultPortal: prod
          portals:
            - name: prod
              portalId: ${{ secrets.HUBSPOT_PORTAL_ID_PROD }}
              authType: personalaccesskey
              personalAccessKey: ${{ secrets.HUBSPOT_ACCESS_KEY_PROD }}
          EOF

      - name: Deploy to Production
        run: hs cms upload src/my-theme @my-theme --portal=prod --overwrite

      - name: Notify on success
        if: success()
        uses: slackapi/slack-github-action@v1
        with:
          payload: |
            {
              "text": "🚀 本番デプロイ完了！\ncommit: ${{ github.event.head_commit.message }}\nby: ${{ github.actor }}"
            }
        env:
          SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}

      - name: Notify on failure
        if: failure()
        uses: slackapi/slack-github-action@v1
        with:
          payload: |
            {
              "text": "❌ 本番デプロイ失敗！確認が必要です。\n${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}"
            }
        env:
          SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}

HubSpot Developer MCP Server — Accelerate development with AI agents

February 19, 2026HubSpot Developer MCP Server is officially GA (publicly available)It was done. MCP (Model Context Protocol) is a standard for AI tools to collaborate with external services. By installing HubSpot's Developer MCP Server locally, AI editors such as VS Code, Claude Code, and Cursor Generate, deploy, and debug CMS assets using natural language while referring to HubSpot's developer documentation.It will look like this.

Setup steps

# Prerequisite: CLI v8.0.0 or higher has been installed
$ hs --version
8.x.x

# Set up MCP Server (interactive)
$ hs mcp setup# ↓ Select MCP client to connect interactively
? Which clients would you like to add the MCP server to?
  ❯ ◉ VS Code
    ◉ Claude Code
    ◯ Cursor
    ◯ OpenAI Codex
(Use arrow keys and spacebar to select, Enter to proceed)

✔ HubSpotDev MCP server has been added to: VS Code, Claude Code
Restart your client to apply the changes.

What you can do with MCP server

Deployment workflow best practices

Pre-deployment checklist

Rollback procedure

HubSpot design managerVersion history featureThere is, You can revert to previous versions from the change history of each file. However, bulk upload via CLI overwrites all files, so Version control using “Git tag + hs cms upload” is a safe rollback methodIt will be.

# === Always use Git tag during production deployment ===
$ git tag v1.2.0 -m "Hero Banner Renewal"
$ git push origin v1.2.0

# === Rollback if problems are discovered after deployment ===

# ① Check out the tag of the version you want to rollback
$ git checkout v1.1.0
HEAD is now at abc1234 v1.1.0

# ② Upload old version file to production
$ hs upload src/my-theme @my-theme --portal=prod --overwrite
✔ Rollback complete: v1.1.0 deployed to production

# ③ Return to working branch
$ git checkout main

# ④ Correct the problematic changes and redeploy

Deployment strategy for large-scale changes

• Major template changes: Create and test a new template file with a different name, and if there are no problems, replace the old template. Do not suddenly overwrite existing templates.
• Global partial (header/footer) changes: This will affect all pages, so check 5 to 10 representative pages after making the change. Visually check for any collapse while scrolling on both SP and PC.
• Change CSS variables (theme.json): Changing the color may result in unintended appearance on unintended pages. Take a screenshot before the change and compare it with the after change.
• Form module changes: Be sure to test whether the form can be submitted, whether the redirect is normal, and whether the data is delivered to the CRM.

Best practices for team development

Documentation of directory structure

# my-company-hubspot

## Prerequisites
- Node.js 20 or higher (CLI v8.0.0 or later required)
- @hubspot/cli global installation
- Access rights to the development portal (portal ID is shared separately)

## Setup steps

### 1. Clone the repository
git clone https://github.com/mycompany/hubspot-theme.git
cd hubspot-theme

### 2. HubSpot CLI authentication settings
hs init
# Development portal ID: 12345678 (separately shared on Slack)
# Personal Access Key: Issued individually from the HubSpot admin screen
# https://app.hubspot.com/personal-access-key/12345678

◎ Can be set in detail
# ✅ CMS - Design Manager
# ✅ Content

### 4. Start development
npm run dev
# Open the development portal in your browser and check your edits
# https://app.hubspot.com/website-pages/12345678

## Branch strategy
# feature/xxx → develop (automatically deploy to DEV portal)
# develop → main (automatically deploy to production portal)

Required scope for Personal Access Key

Common conflict problems and solutions

Code review points

• Default values ​​for fields.json: Do all fields have meaningful default values? Avoid leaving it empty.
• Missing existence check: The image field is .src, the link field is .url Are you checking for existence?
• Using get_asset_url(): CSS/JS/image path references get_asset_url() Are you passing it through?
• loading attribute: The LCP element has loading="eager", and others loading="lazy" Is it attached?
• Accessibility: Does the img tag have an alt attribute? Does the interactive element have appropriate ARIA attributes?
• Presence of standard footer: for all templates {{ standard_footer_includes }} Is it included?

Personal Access Key expiration management

Personal Access Keys do not have an expiration date, but For security reasons, we recommend regular rotation every 6 months to 1 year. If a team member leaves the company, please deactivate it immediately. Don't forget to update your GitHub Secrets.