New Global Configuration

We are introducing a new global configuration system to streamline account management for developers using the HubSpot CLI v7.4.0. This change addresses issues related to using multiple account configuration files, often leading to conflicts and time-consuming debugging. The new global ~/.hscli/config.yml  config file will become the single source of truth for accounts, simplifying debugging, improving security, and enhancing the developer experience. This will deprecate the previous hubspot.config.yml config file.

To override the default account stored in the global configuration file, we are also introducing the .hsaccount file. You can create this file in any directory where you would like to override the default account. The override file provides a more secure method of storing account information, containing only an account ID, thus reducing the risk if exposed in source control. This solves for a power-user trick some developers were previously using, where they would have a separate config.yml file inside of their project files so that the default accounts would automatically switch for the CLI. This override file retains that capability in a more secure and intentional way.

If a developer encounters any issues with the new global configuration, it is important to note that this change is backward compatible. 

What's changing?

• Global Configuration File: The ~/.hscli/config.yml config file offers a single place for account configuration, reducing complexity and conflict potential inherent in multiple configuration files.
• Backward Compatibility: This change maintains full backward compatibility by supporting existing configuration patterns, offering clear migration paths through dedicated commands, and ensuring seamless command functionality.
• Improved Security: By storing only the account ID in the .hsaccount file, developers benefit from reduced potential exposure of personally identifiable information (PII).

• New Commands:
  • hs account auth: Used for creating and updating the global configuration file located in the user’s working directory (~/.hscli/config.yml).
  • hs config migrate: Facilitates migration to the new global configuration system. Works both to migrate a deprecated configuration file and to merge a deprecated and a global config file.
  • hs account create-override: Creates an .hsaccount file in the current working directory. Allows overriding the default account configuration as needed.
  • hs account remove-override: Removes an .hsaccount file from the current working directory. 
• New Properties: 
  • defaultAccount: previously defaultPortalstill behaves and assigns the account interacted with by default when running CLI commands. Use the -account flag to interact with an authenticated account that is not set as the default.
  • accountId: previously portalIdand still behaves as the accountId
  • accounts[]: previously portals[], a list of accounts within the configuration file

What does this mean for developers?

• Update the HubSpot CLI: Developers can opt in to update to the latest version of the HubSpot CLI by running:

• Migrate Existing Configurations: Use the following command to transition to the new ~/.hscli/config.yml global configuration:

• Authentication and Configuration: Utilize the following command below to set up or update the global configuration file: 

Otherwise, if needed, use the command below to create an account override file (.hsaccount) to override the default account in the current working directory: 

Use the following command to remove an account override file from the current working directory: 

This new process aims to prevent confusion and potential security issues by limiting the number of config files and ensuring that only the account ID is exposed in the .hsaccount file.

When is it happening?

This update is available on April 15th, 2025. Developers are encouraged to update their CLI tools and migrate their configurations as soon as possible to take full advantage of the new system and features.

Questions or comments? Join us in the developer forums.