> ## Documentation Index
> Fetch the complete documentation index at: https://developers.hubspot.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Account CLI commands
> Learn about account and authentication CLI commands.
export const Tag = ({children, type = 'default', className = ''}) => {
return
{children}
;
};
This article provides a reference for managing your authenticated accounts, secrets, and your account's files tool via the CLI.
## Managing authentication and account configuration
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](#link-an-account) 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 migrate` [command](/developer-tooling/local-development/hubspot-cli/commands/debugging-commands#migrate-configuration).
You can also migrate from the older per-directory override model defined by a `.hsaccount` file by running [hs account link](#link-an-account) in the same directory as an existing `.hsaccount` file.
## Account and authentication commands
Review the commands below to learn how to authenticate your HubSpot account or manage existing authenticated accounts.
### Authenticate an account
Generate authentication for a HubSpot account using a [personal access key](/developer-tooling/local-development/hubspot-cli/personal-access-key).
```shell theme={null}
hs account auth [flags]
```
**Flags**
| Flag | Description |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `--account` | The specific account name to authenticate using the CLI. To get a full list of accounts, use the `hs account list` command. |
| `--personal-access-key` | Provide an existing [personal access key](/developer-tooling/local-development/hubspot-cli/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 account 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 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](#authenticate-an-account) command to add accounts to your config file.
```shell theme={null}
hs account list
```
### Get account info
View information about the default account, or a specific authenticated account (including [linked accounts](#link-an-account)).
```shell theme={null}
hs account info [account]
```
**Arguments**
| Argument | Description |
| --------- | ----------------------------------------------- |
| `account` | The name or ID of the account to show info for. |
### Set default account
Set the default account in your config file. If executed inside a [linked directory](#link-an-account), it changes the default account for the linked directory instead of the global default.
```shell theme={null}
hs account 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.
```shell theme={null}
hs account 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.
```shell theme={null}
hs account clean
```
### Link an account
Link an authenticated account to the current working directory.
```shell theme={null}
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.
### Unlink an account
Unlink an authenticated account from the current working directory. Use this command when an account is no longer relevant to a directory.
```shell theme={null}
hs account unlink
```
### 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](#link-an-account) 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:
```shell theme={null}
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.
**Please note:** starting from version 7.4 of the CLI, the new `hs account auth` [command](#authenticate-an-account) 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](#authenticate-an-account) command. When prompted for a name to use for the account, the name can't contain spaces.
```shell theme={null}
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. |
## Make API requests
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](/developer-tooling/local-development/hubspot-cli/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](/api-reference/latest/crm/objects/contacts/get-contact)).
```shell theme={null}
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. |
## 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.
```shell theme={null}
hs secrets add [secret-name]
```
**Arguments**
| 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.
```shell theme={null}
hs secrets update [secret-name]
```
**Arguments**
| 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.
```shell theme={null}
hs secrets delete
```
**Arguments**
| Argument | Description |
| ---------------------------------------------- | ---------------------------------- |
| `secret-name` Required | 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. |
### List secrets
List secrets within your account to know what you have stored already using the add secrets command.
```shell theme={null}
hs secrets list
```
## Sandbox commands
Interact with [standard sandboxes](https://knowledge.hubspot.com/account-management/deploy-sandbox-changes-to-production) and [development sandboxes](/developer-tooling/overview#create-and-use-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 one development sandbox at a time. Additional standard sandboxes can be purchased as an [add-on](https://legal.hubspot.com/hubspot-product-and-services-catalog#Addons). Learn more about [development sandbox limits](/developer-tooling/overview#create-and-use-development-sandboxes).
```shell theme={null}
hs sandbox create
```
### 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.
```shell theme={null}
hs sandbox delete
```
## Create and use development sandboxes
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.
### 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 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](https://knowledge.hubspot.com/import-and-export/import-objects) 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=`.
Development sandboxes are designed to be early proof of concept environments. It is recommended to [delete](#delete-a-development-sandbox) and [create](#create-a-development-sandbox) 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](/apps/developer-platform/add-features/ui-extensions/ui-components/overview), or learn more about [creating apps](/apps/developer-platform/build-apps/create-an-app).
### 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](https://knowledge.hubspot.com/account-management/add-hubspot-users).
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.
### 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**.
## Files tool
Use the commands below to upload and fetch files from your account's files tool.
### Upload files
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](https://knowledge.hubspot.com/files/organize-edit-and-delete-files#edit-the-file-visibility-setting) for more details on file visibility settings.
```shell theme={null}
hs filemanager upload
```
**Arguments**
| Argument | Description |
| --------------------------------------- | ------------------------------------------------------------------- |
| `src` Required | Path to the local file, relative to your current working directory. |
| `dest` Required | Path in the files tool, can be a net new path. |
### Fetch files
Fetch a file from your account's files tool to your local environment.
```shell theme={null}
hs filemanager fetch
```
**Arguments**
| Argument | Description |
| --------------------------------------- | ------------------------------------------------------------------- |
| `src` Required | Path in the files tool to fetch from. |
| `dest` Required | Local destination path, relative to your current working directory. |