Skip to main content
Last modified: August 22, 2025
Within a project, you can set up config profiles to dynamically apply relevant configuration and variables at build time for different target environments. Each profile will provide a set of values that correspond with variables defined in any *-hsmeta.json configuration files in the project. When running hs project upload or hs project dev, you’ll specify the profile you want to use, and HubSpot will apply variable values accordingly. This can allow you to streamline building and testing without impacting the production version of your app and without having to manually update configuration values based on your testing environment. For example, you can set up profiles for development and production to handle switching auth redirect URL domains (see example usage).
To use config profiles, ensure you’re on the latest version of the CLI by running npm install -g @hubspot/cli@latest. If you haven’t installed the HubSpot CLI yet, you can run npm install -g @hubspot/cli.

​
Create and manage config profiles

To create a config profile, run hs project profile add in your project directory, then follow the terminal prompts to assign the profile a name and a target HubSpot account. It’s highly recommended to use a different account for each profile. You can also provide the profile name as an argument when running the command, as shown below with an example profile named prod. 
hs project profile add prod
Please note:Only authenticated accounts can be selected during profile creation. If an account is missing from the list, you’ll need to run hs account auth.
The profile will then be created in the src directory as a hsprofile.*.json file, which has the following schema: 
{
  "accountId": 1234567,
  "variables": {
    "VAR": "value",
    "OTHER_VAR": "value"
  }
}
FieldTypeDescription
accountIdIntegerThe ID of the HubSpot account to target when using the profile.
variablesObjectAn object containing key-value pairs for each variable and its assigned value for the profile. You’ll reference these variables in your *-hsmeta.json files using ${VARIABLE_NAME} syntax.
Once a project contains a profile, running the hs project profile add command again will include an option to copy the variables from an existing profile into the new one. To delete a profile, run the hs project profile delete command. To completely disable profiles for a project, delete all profile files and variables from your configuration files.
At any time, you can run hs project profile --help to view more information about the available profile commands.

​
Using profile variables

With your variables defined for each profile, you can reference them in the project’s various *-hsmeta.json files using the format ${VARIABLE_NAME}. For example, the app-hsmeta.json file below is configured to append the VAR variable value to the app name when uploaded using that profile. 
{
  "uid": "my-example-app",
  "type": "app",
  "config": {
    "description": "An example app",
    "name": "MyApp-${VAR}",
    ...
  }
}
Each profile must define values for all variables used in your configuration files. If a variable or value is missing from a profile, the CLI will return an error when attempting to upload your project.

​
Using profiles with upload commands

After defining profiles in a project, you’ll need to specify the profile to use when running hs project upload or hs project dev by including the --profile or -p flag. The CLI will then use the account specified by the profile and apply the profile’s variable values. The code block below demonstrates this usage with an example profile named qa. 
hs project upload -p qa
Once you’ve added profiles to a project, you must specify a profile when running the upload or dev command. The CLI will return an error if no profile is specified.

​
Usage example

As an example, let’s say you want to set your app’s authentication redirect URL based on whether you’re targeting a development environment or a production environment.
  1. In your app configuration (app-hsmeta.json), include a ${DOMAIN} variable in the redirectUrls field.
{
  "uid": "my-example-app",
  "type": "app",
  "config": {
    "description": "An example app",
    "name": "MyOAuthApp",
    "distribution": "marketplace",
    "auth": {
      "type": "oauth",
      "redirectUrls": ["http://${DOMAIN}/oauth-callback"],
      "requiredScopes": [
        "crm.objects.contacts.read",
        "crm.objects.contacts.write"
      ],
      "optionalScopes": [],
      "conditionallyRequiredScopes": []
    }
  }
}
  1. Set the variable value within each profile configuration file (hsprofile.*.json):
{
"accountId": 1234567,
"variables": {
"DOMAIN": "test-env-domain.com"
}
}
  1. During development, you’ll specify the config profile (qa) via the --profile or -p flag in the hs project upload or hs project dev command.
hs project upload -p qa
The app will upload to your development environment account with the redirect URL set to http://test-env-domain.com/oauth-callback. 
{
  "uid": "my-example-app",
  "type": "app",
  "config": {
    "description": "An example app",
    "name": "MyOAuthApp",
    "distribution": "marketplace",
    "auth": {
      "type": "oauth",
      "redirectUrls": ["http://test-env-domain.com/oauth-callback"],
      ...
    }
  }
}
  1. When you’re ready to upload your changes to the production version of the app, you’ll specify the production profile (prod) when running hs project upload.
hs project upload -p prod
The app will upload to your production environment account with the redirect URL set to http://production-domain.com/oauth-callback. 
{
  "uid": "my-example-app",
  "type": "app",
  "config": {
    "description": "An example app",
    "name": "MyOAuthApp",
    "distribution": "marketplace",
    "auth": {
      "type": "oauth",
      "redirectUrls": ["http://production-domain.com/oauth-callback"],
      ...
    }
  }
}

​
Use config profile variables in UI extensions

Config profile variables are also available when building UI extensions (e.g., an app card or app settings page) via the variables property within the context object. You can define any profile variables within each profile configuration file (hsprofile.*.json):
  • hsprofile.qa.json
{
  "accountId": 1234567,
  "variables": {
    "DOMAIN": "test-env-domain.com"
  }
}
Once defined in the profile configuration file, you can then access the variable in your UI extension code: 
import React, { useEffect } from 'react';
import { hubspot } from '@hubspot/ui-extensions';

hubspot.extend(({ context }) => <Hello context={context} />);

const Hello = ({ context }) => {
  useEffect(() => {
    let url = context.variables.DOMAIN;
    hubspot.fetch(url, {...});
  })
});