This article provides a reference for managing your authenticated accounts and secrets via the CLI.
Account and authentication commands
Review the commands below to learn how to authenticate your HubSpot account or manage existing authenticated accounts.
hs init command
Please note: starting from version 7.4 of the CLI, the new hs account auth command provides an alternative way to manage configuration in a single, global config file instead of using multiple hubspot.config.yml files created using the hs init command. Although the hs init command is still supported, it’s recommended that you switch to using hs account auth instead. hubspot.config.yml file in the current directory and sets up authentication for an account. If you’re adding authentication for a new account to an existing config file, run the auth command. When prompted for a name to use for the account, the name can’t contain spaces.
Flags
| Flag | Description |
|---|
--auth-type | The authentication protocol to use for authenticating your account. Supported values are personalaccesskey (default) and oauth2. |
--account | The specific account name to authenticate using the CLI. To get a full list of accounts, use the hs accounts command. |
Authenticate an account
Generate authentication for a HubSpot account using a personal access key.
Flags
| Flag | Description |
|---|
--account | The specific account name to authenticate using the CLI. To get a full list of accounts, use the hs accounts list command. |
--personal-access-key | Provide an existing personal access key to use for authentication. |
You can also use the older hs auth command to manage authentication via a hubspot.config.yml file, but it’s recommended that you use the newer hs accounts auth command for new app development moving forward, as it uses a global configuration file to manage authentication across multiple accounts.
List authenticated accounts
Lists the name, ID, and auth type for the each account in your config file. If you’re not seeing the accounts you expect, you may need to run the auth command to add accounts to your config file.
Set default account
Set the default account in your config file.
hs accounts use [accountNameOrID]
| Parameter | Description |
|---|
accountNameOrID | Identify the new default account by its name (as set in the config file) or ID. |
Remove an account
Removes an account from your config file.
hs accounts remove [accountNameOrID]
| Parameter | Description |
|---|
accountNameOrID | Identify the account to remove by its name (as set in the config file) or ID. |
Remove invalid accounts
Removes any deactivated HubSpot accounts from your config file.
Override the default account in your global config
If you want to override the default account in the ~/.hscli/config.yml global config file, you can run the following command in any directory:
hs account create-override
.hsaccount file in your current working directory. This file will list a single account from your global config that will act as your default account for the current directory, along with any subdirectories and files. If needed, you can use the hs account remove-override command to remove this file from your current working directory.
Managing secrets
Add a secret
Add a secret to your account which can be used to reference authentication data you don’t want to expose in your project files.
To expose the secret to your function, update your file with the secret’s name, either to the specific endpoints you want to use it in or globally to make it available to all.
hs secrets add [secret-name]
| Argument | Description |
|---|
secret-name Required | Name of the secret to add. |
Update a secret
Update the value of a secret in your account which can be referenced in your project without exposing it directly in your source files.
Please note: due to caching, it can take about one minute to see updated secret values. If you’ve just updated a secret but are still seeing the old value, check again after about a minute.
hs secrets update [secret-name]
| Argument | Description |
|---|
secret-name Required | The name of the secret, which you’ll later use to reference the secret. This can be any unique value, though it’s recommended to keep it simple for ease of use. |
Remove a secret
Remove a secret from your account, making it no longer usable within your project files. You will be prompted to confirm the deletion before proceeding. You can use the --force flag to bypass this confirmation.
hs secrets delete <secret-name>
| Argument | Description |
|---|
secret-name Required | Name of secret you want to remove. |
| Flag | Description |
|---|
--force | Bypass the confirmation prompt and immediately delete the table once the command is executed. |
List secrets
List secrets within your account to know what you have stored already using the add secrets command.
Sandbox commands
Interact with standard sandboxes and development sandboxes using the commands below.
Create a sandbox
Creates a new sandbox in a production account. When running this command, you can select whether you want to create a standard sandbox or a development sandbox.
If creating a standard sandbox, when running this command, all supported assets will be synced from production to the standard sandbox by default. You can choose to trigger a one-time sync of the last updated 5,000 contacts and, if applicable, up to 100 associated companies, deals, and tickets (for each associated object type).
A production account can have one standard sandbox and two development sandboxes at a time. Additional standard sandboxes can be purchased as an add-on. Learn more about development sandbox limits.
Delete a sandbox
Deletes a sandbox connected to the production account. Follow the prompts to select the sandbox account to delete, then confirm the permanent deletion.
Create and use development sandboxes
Development sandboxes are only available in accounts with an Enterprise subscription.
- A production account can have only one development sandbox at a time.
- CRM object definitions are synced from the production account to the development sandbox at the time of sandbox creation.
- You cannot create a sandbox within another sandbox.
Create a development sandbox
To set up a development sandbox account:
-
Because development sandboxes are created within the
defaultPortal in your hubspot.config.yml file, first confirm that your production account is connected and set as the default:
-
In the terminal, run
hs accounts list.
-
In your list of connected accounts, confirm that your production account is listed as the default account.
-
If your production account is not the default, run
hs accounts use and select your production account.
-
After confirming your production account is the default, run
hs sandbox create.
-
You’ll then be prompted to select a type of sandbox to create. Select Development sandbox, then press Enter.
-
Enter a
name for the sandbox account, then press Enter.
-
All CRM object definitions will be copied from production to the development sandbox.
-
You can use the import tool to import production object record data, or manually create sample data for testing.
-
The CLI will then begin the sandbox setup process. Once the sandbox is fully set up and synced, you’ll see a Sandbox sync complete confirmation.
With your development sandbox created, it will appear under the associated production account when running hs accounts list.
If you want to set the development sandbox as your default account, run hs accounts use, then select the sandbox. To deploy to your sandbox or production account, you can either run hs accounts use to set the default account, or manually select the account when uploading by running hs project upload --account=<name-of-account>.
Development sandboxes are designed to be early proof of concept environments. It is recommended to delete and create a new Development Sandbox using the CLI. This ensures development sandboxes always have an exact mirror of the production account’s CRM object definitions when beginning new projects.
After setting up your development sandbox, learn how to create a UI extension, or learn more about creating apps.
View a development sandbox in HubSpot
By default, all super admin users are synced to the development sandbox during creation. Super admins can give other users access by adding them as users to the development sandbox.
To access the development sandbox account in HubSpot:
- In your HubSpot account, navigate to CRM Development in the main navigation bar.
- In the left sidebar menu, select Sandboxes.
- Click the Development tab, where your new sandbox will be listed along with its name, create date, and the user who created it.
- To navigate to the sandbox account, click the development sandbox name.
Once a user has been granted access to a development sandbox, they can access it by clicking the Profile picture in the top right of HubSpot, then clicking the Account selection menu and selecting the account.
Sync CRM data manually
To trigger an on-demand sync of CRM contact records and associated deals, tickets, and companies from a standard HubSpot account to your development sandbox, run the following command:
Delete a development sandbox
- To delete a development sandbox using the CLI, run
hs sandbox delete, then follow the prompts.
- To delete a development sandbox in HubSpot:
- In your HubSpot account, navigate to CRM Development in the main navigation bar.
- In the left sidebar menu, select Sandboxes.
- Click the Development tab.
- Hover over the development sandbox, then click Delete.
