The hs account and hs config commands and their associated subcommands provide a streamlined way for you to manage authenticated HubSpot accounts, link specific authenticated accounts to a directory, and manage other configuration options.When you run the hs account auth command for the first time, a global config file will be created at ~/.hscli/config.yml. This file will store the metadata for your authenticated accounts and the account set as your global default.When working across multiple project directories, you can link a specific authenticated account to a directory using the hs account link command.
For example, if you work on a production app in one directory and a sandbox project in another, you can explicitly link specific accounts to each directory to prevent accidentally running a command against the wrong account.
Each linked directory can also have its own default account, which takes precedence over the global default when running commands from that directory.
If you’re using the older hubspot.config.yml file to manage your config, you’ll need to migrate to the newer ~/.hscli/config.yml config file using the hs config migratecommand.You can also migrate from the older per-directory override model defined by a .hsaccount file by running hs account link in the same directory as an existing .hsaccount file.
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 account auth command for new app development moving forward, as it uses a global configuration file to manage authentication across multiple accounts.
Lists the name, ID, and auth type for each account in your config file, along with linked directory and account settings.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 the default account in your config file. If executed inside a linked directory, it changes the default account for the linked directory instead of the global default.
hs account use [accountNameOrID]
Parameter
Description
accountNameOrID
Identify the new default account by its name (as set in the config file) or ID.
Link an authenticated account to the current working directory.
hs account link
After authenticating with hs account auth, navigate to a directory and run hs account link to select which accounts are relevant there. You can link multiple accounts (e.g., a production account and a sandbox) and set a default for the directory.
Linked accounts are saved in a local .hs/settings.json file, which is added to .gitignore automatically so it won’t affect other developers on your team. You can commit this file if it fits your workflow better.
Once linked, all other commands will work seamlessly with your linked accounts (e.g., hs project dev, hs project deploy, hs cms commands etc).
If you run hs account link in a directory with an older per-directory override .hsaccount file, you’ll be prompted to migrate the override settings. Once confirmed, the .hsaccount file will be deleted in favor of a new .hs/settings.json file in the same directory.
Override the default account in your global config
Please note: the command below is an older method for overriding the default authenticated account and is no longer recommended. Instead, use the hs account link command for a more flexible approach to link authenticated accounts to a specific directory.
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
The command will create an .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.
hs init command (deprecated)
Please note: starting from version 7.4 of the CLI, the new hs account authcommand 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.
Creates a 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.
hs init [flags]
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 account list command.
Once you’ve authenticated your account using hs account auth, you can make API requests using the CLI to any HubSpot endpoint associated with a granted permission when you generated your Personal Access Key.For example, if you selected the CRM Objects permission when generating your PAK, you can make API requests to any endpoint that requires the crm.objects.contacts.read scope (e.g., the retrieve contacts endpoint).
hs api [endpoint] [flags]
Arguments
Argument
Description
endpoint
API endpoint path (e.g. /crm/2026-03/objects/contacts)
Flags
Flag
Description
--method
The HTTP method to use. Defaults to GET, or POST if the --data flag is provided.
--data
A JSON-formatted request body for POST, PUT, or PATCH requests.
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.
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]
Arguments
Argument
Description
secret-name
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 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>
Arguments
Argument
Description
secret-name
Name of secret you want to remove.
Flags
Flag
Description
--force
Bypass the confirmation prompt and immediately delete the table once the command is executed.
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 one development sandbox at a time. Additional standard sandboxes can be purchased as an add-on. Learn more about development sandbox limits.
Deletes a sandbox connected to the production account. Follow the prompts to select the sandbox account to delete, then confirm the permanent deletion.
Development sandboxes are only available in accounts with an Enterprise subscription.
After following the steps above to connect a production account to the CLI for private app development, you can create a development sandbox within it to setup a lightweight testing environment. This enables you to develop your apps and extensions in a siloed environment before deploying to a production account.Before proceeding, review the following development sandbox limits:
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.
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 account 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 account 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 account list.If you want to set the development sandbox as your default account, run hs account use, then select the sandbox. To deploy to your sandbox or production account, you can either run hs account 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.
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.
Upload a local file to your account’s files tool. Note that uploaded files will be set to public visibility, making them viewable by anyone with the URL. See HubSpot’s Knowledge Base for more details on file visibility settings.
hs filemanager upload <src> <dest>
Arguments
Argument
Description
src
Path to the local file, relative to your current working directory.
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.
