DOCSEARCHbyAlgolia
Submit Docs

HubSpot CLI

repository·main·Indexed 42 days ago

https://github.com/hubspot/hubspot-cli

The official command-line interface for HubSpot developers, version 8.15.0. It enables local development workflows and automation for the HubSpot platform, providing tools for authentication, account management, project and app management, and CMS content interaction (including HubDB and File Manager).

Tokens
45.8K
Snippets
205
Records
224
Agent score
51%

What's inside HubSpot CLI

  2. Install the HubSpot CLI

    main

    Install the @hubspot/cli globally using npm to enable local development and automation for HubSpot developers.

    If you prefer not to install it globally, you can run commands using npx (for npm users) or yarn (for yarn users) by prefixing the command.

    npm install -g @hubspot/cli

  3. Authenticate your HubSpot account

    main
    After installing the CLI, you must authenticate your HubSpot account to link your local environment to your HubSpot portal. Run the hs init command to begin the configuration and authentication process.
    hs init

  4. Use the HubSpot CLI

    main

    The HubSpot CLI is a command-line interface used to interact with HubSpot services. It supports a wide range of commands for managing authentication, configuration, projects, CMS content (like HubDB and File Manager), and more.

    To use the CLI, you must provide at least one command. Running the CLI without a command will display the help menu.

    # Example usage (command required)
# hs <command> [options]

# To see all available commands:
# hs --help

  5. Convert JS field definitions to JSON during upload

    main

    When working with HubSpot CMS fields, you can use the --convert-fields flag to automatically convert JavaScript-based field definitions into the required .json format during the upload process.

    When this flag is used:

    1. The CLI identifies the project root (looking for theme.json).
    2. It initializes a FieldsJs process to handle the conversion.
    3. The destination path is automatically adjusted to end in fields.json to ensure compatibility.
    4. If --save-output is also provided, the resulting converted files are saved to your local disk.
    hubspot cms upload ./my-fields.js /path/on/hubspot --convert-fields --save-output

  6. HubSpot CLI MCP Server Tool Categories

    main

    The server provides tools organized into two main functional categories:

    1. Project Tools: Registered via registerProjectTools. These are used for managing HubSpot projects, builds, deploys, and project-level configurations.
    2. CMS Tools: Registered via registerCmsTools. These are used for managing CMS assets like modules, templates, and serverless functions.

  7. How project profiles work with `upload`

    main

    For non-legacy projects, the CLI supports Project Profiles. A profile allows you to map a project to a specific HubSpot account.

    When running hs project upload:

    1. If a --profile is provided, the CLI loads and validates that profile to determine the targetAccountId.
    2. If no profile is provided, the CLI may prompt you to select a profile from your local project directory.
    3. The --profile option conflicts with the global --account option; you must choose one or the other.

  8. Previewing a project build

    main

    You can preview a project build without deploying it to your main environment by using the --preview flag. This requires providing a specific portal ID via the --target flag.

    Requirements:

    • You must use --preview if you provide a --target.
    • You must provide --target if you use --preview.

    When a preview is triggered, the CLI will poll the build and return a preview object in the JSON output containing the releaseTag and succeeded status.

    # Preview the build on a specific portal
$ hs project upload --preview --target 1234567

  9. Use the get-started command to initialize a project

    main

    The get-started command provides an interactive workflow to help you set up a new HubSpot development project. It allows you to choose between creating a Private App or a CMS-based project.

    If you choose a Private App, the command will:

    1. Prompt you for a project name and destination directory.
    2. Clone a standard GitHub template for your project.
    3. Configure the project locally.
    4. Offer to automatically upload the project to your HubSpot portal.
    5. If uploaded, it can provide a direct link to the developer overview for your newly created app.

    If you choose CMS, the command provides guidance and an option to open the HubSpot Design Manager in your browser.

    hubspot get-started

  10. Run the unified project development flow

    main

    The unified project development flow is a comprehensive CLI command that sets up a local development environment for HubSpot projects. It automates several complex steps:

    1. Translation: Translates project source files into an Intermediate Representation (IR) for local execution.
    2. Account Selection: Identifies or prompts for a target project account and a testing account (such as a Developer Test account or a Development Sandbox).
    3. Project Synchronization: Checks if the project exists in HubSpot. If it does, it compares the local version to the deployed version; if not, it creates a new project and an initial build.
    4. Dependency Management: Checks for and installs necessary dependencies.
    5. Local Server Startup: Starts a port manager, a local development process, a websocket server for real-time updates, and a file watcher to trigger reloads on changes.

    This flow is designed to provide a seamless 'edit-and-see' experience locally before deploying to HubSpot.

    Key behaviors:

    • If a local development process is already running, the command will exit with an error.
    • If the project directory is linked to specific accounts via hs-settings.json, the CLI will use those linked accounts.
    • It supports automatic uploading of changes if the project's auto-deploy setting is enabled.
    • The process can be stopped by pressing Ctrl+C or q in the terminal.
    # Note: This is a programmatic entrypoint for the 'project dev' command.
# Usage typically involves:
# hubspot project dev [options]

# Example conceptual invocation:
# hubspot project dev --auto-upload --port 3000

  11. Use the HubSpot CLI MCP Server for local development

    main

    The HubSpot CLI MCP Server exposes the HubSpot CLI (hs) through the Model Context Protocol. It is designed to assist with local development of HubSpot projects, apps, and CMS assets by handling configuration loading, authentication, platform-version flags, and providing structured output.

    When to use this server

    • When working in a HubSpot project directory (containing hsproject.json or *-hsmeta.json files) or scaffolding a new one.
    • When performing tasks related to HubSpot apps, CMS modules, templates, serverless functions, project builds, deploys, or developer test accounts.
    • When answering HubSpot platform or API questions (use the provided documentation tools instead of prior knowledge).

    Required Workflows

    • Authentication: If a tool reports "No account ID found" or no accounts are authenticated, call auth-account. This opens a browser tab for authorization; no Personal Access Key is required initially.
    • Documentation Lookup: Always call search-docs first, followed by fetch-doc on relevant results, before writing code or answering platform questions.
    • Locating Projects: If the current directory is not a HubSpot project, call find-projects before running tools that require a project path.
    • Editing Metadata: To edit *-hsmeta.json files, call get-feature-config-schema first to identify allowed fields and values.
    • Debugging Builds: Use get-build-status to see error messages. Use get-build-logs only for deeper troubleshooting.
    • Serverless Functions: Use list-cms-serverless-functions to find endpoint paths, then use get-cms-serverless-function-logs to read logs.
    • App Analytics: Use get-apps-info to find appId values before calling get-api-usage-patterns-by-app-id.

  12. Clean upload: Syncing local folders to HubSpot

    main

    To ensure that the destination folder on HubSpot exactly matches your local source (by removing files that exist on HubSpot but not locally), use the --clean flag.

    Behavior:

    • If --clean is used, the CLI will first attempt to delete the destination path on HubSpot.
    • If --force is not used, the CLI will prompt you for confirmation before deleting the remote files.
    • If --force is used, the deletion happens automatically without a prompt.

    Warning: This will permanently delete files at the specified dest on HubSpot.

    hubspot cms upload ./local-folder /remote-folder --clean --force