@hubspot/cli 8.5.0 → 8.6.0-beta.0

package/lang/en.js

@@ -2,11 +2,12 @@ import chalk from 'chalk';
 import { mapToUserFriendlyName } from '@hubspot/project-parsing-lib/transform';
 import { PLATFORM_VERSIONS } from '@hubspot/project-parsing-lib/constants';
 import { PERSONAL_ACCESS_KEY_AUTH_METHOD } from '@hubspot/local-dev-lib/constants/auth';
-import { ARCHIVED_HUBSPOT_CONFIG_YAML_FILE_NAME, GLOBAL_CONFIG_PATH, DEFAULT_HUBSPOT_CONFIG_YAML_FILE_NAME, } from '@hubspot/local-dev-lib/constants/config';
-import { uiAccountDescription, uiBetaTag, uiCommandReference, uiLink, UI_COLORS, uiAuthCommandReference, } from '../lib/ui/index.js';
-import { getProjectDetailUrl, getProjectSettingsUrl, getLocalDevUiUrl, } from '../lib/projects/urls.js';
+import { LOCAL_DEV_DEFAULT_PORT } from '../lib/constants.js';
+import { ARCHIVED_HUBSPOT_CONFIG_YAML_FILE_NAME, DEFAULT_HUBSPOT_CONFIG_YAML_FILE_NAME, GLOBAL_CONFIG_PATH, } from '@hubspot/local-dev-lib/constants/config';
+import { indent, UI_COLORS, uiAccountDescription, uiAuthCommandReference, uiBetaTag, uiCommandReference, uiLink, } from '../lib/ui/index.js';
+import { getLocalDevUiUrl, getProjectDetailUrl, getProjectSettingsUrl, } from '../lib/projects/urls.js';
 import { getProductUpdatesUrl } from '../lib/links.js';
-import { APP_DISTRIBUTION_TYPES, APP_AUTH_TYPES, PROJECT_CONFIG_FILE, PROJECT_WITH_APP, LEGACY_PUBLIC_APP_FILE, } from '../lib/constants.js';
+import { APP_AUTH_TYPES, APP_DISTRIBUTION_TYPES, LEGACY_PUBLIC_APP_FILE, PROJECT_CONFIG_FILE, PROJECT_WITH_APP, } from '../lib/constants.js';
 export const commands = {
     generalErrors: {
         srcIsProject: (src, command) => `"${src}" is in a project folder. Did you mean "hs project ${command}"?`,
@@ -137,8 +138,12 @@ export const commands = {
             },
             list: {
                 accounts: `${chalk.bold('Accounts')}:`,
+                allAccounts: `${chalk.bold('All Accounts')}:`,
+                linkedAccounts: `${chalk.bold('Linked Accounts')}:`,
                 defaultAccountTitle: `${chalk.bold('Default Account')}`,
+                linkedDefaultTitle: `${chalk.bold('Linked Default Account')}`,
                 currentResolvedDefaultAccount: (accountId) => `Account: ${uiAccountDescription(accountId)}`,
+                directory: (dir) => `Directory: ${dir}`,
                 describe: 'List names of accounts defined in config.',
                 configPath: (configPath) => `Source: ${configPath}`,
                 overrideFilePathTitle: `${chalk.bold('Default Account Override')}`,
@@ -185,6 +190,70 @@ export const commands = {
                 success: {
                     defaultAccountUpdated: (accountName) => `Default account updated to "${accountName}"`,
                 },
+                linked: {
+                    editingLinkedDefault: (dir) => `Editing the default linked account for this directory (not the global default):\n${indent(1)}${dir}`,
+                    alreadyDefault: (accountId) => `${uiAccountDescription(accountId)} is the only linked account and is already the default.`,
+                    setLinkedDefault: (account) => `Linked default set to ${chalk.cyan(account)}`,
+                    accountNotLinked: (account) => `${account} is not linked to this directory.`,
+                    promptToLink: (account) => `Would you like to link ${account} to this directory?`,
+                    settingGlobalDefault: 'Setting global default instead.',
+                    nonInteractiveNotLinked: (account) => `${account} is not linked to this directory. Setting global default instead.`,
+                },
+            },
+            link: {
+                describe: 'Link authenticated HubSpot accounts to the current directory',
+                verboseDescribe: `Link one or more authenticated HubSpot accounts to the current directory. Linked accounts are saved in a local ${chalk.bold('.hs/settings.json')} file (added to .gitignore automatically).\n\nThis lets the CLI know which account to use when you run commands from this directory, without changing the global default. Run ${uiCommandReference('hs account current')} to see the active configuration.`,
+                shared: {
+                    noLinkedAccounts: 'No HubSpot accounts are linked in this directory.',
+                    globalAccountsAvailable: (count) => `You have ${chalk.cyan(count.toString())} ${count === 1 ? 'account' : 'accounts'} in your global config.`,
+                    configurePrompt: `To configure this directory, run:\n${indent(1)}${uiCommandReference('hs account link')}`,
+                    deprecatedConfigNotSupported: (command) => `${uiCommandReference(command)} does not support deprecated config. Run ${uiCommandReference('hs config migrate')} to migrate to global config. Then re-run ${uiCommandReference(command)}`,
+                    writeSettingsFailed: (path, err) => `Failed to write to ${path}: ${err}`,
+                    savedToSettings: (path) => `Saved to ${path}`,
+                    usingLinkedAccounts: (settingsPath) => `This directory has linked accounts via ${settingsPath}. Only linked accounts will be available for this command. To manage linked accounts, run ${uiCommandReference('hs account link')}.`,
+                    accountAutoLinked: (accountId) => `Automatically linked ${uiAccountDescription(accountId)} to this directory.`,
+                    accountAutoLinkFailed: (accountId) => `Could not automatically link ${uiAccountDescription(accountId)} to this directory. Run ${uiCommandReference('hs account link')} to link it manually.`,
+                },
+                linkingDirectory: (dir) => `Linking HubSpot account(s) for directory:\n${indent(1)}${dir}`,
+                managingLinkedAccounts: (dir) => `Managing linked accounts for:\n${indent(1)}${dir}`,
+                settingsInfo: (path) => `\u2139 Accounts linked here are saved in ${path}`,
+                success: {
+                    created: (path) => `Linked to ${path} (created .hs and added to .gitignore).\n${indent(1)}Now when you work within this directory, the CLI will use the linked account(s).`,
+                },
+                errors: {
+                    authFailed: `Authentication failed to complete`,
+                },
+                events: {
+                    accountsLinked: (count) => `Linked ${count} account${count !== 1 ? 's' : ''}`,
+                    accountsUnlinked: (count) => `Unlinked ${count} account${count !== 1 ? 's' : ''}`,
+                    overrideAccountDetected: (accountId) => `\nCurrent default account (from .hsaccount):\n${indent(1)}${uiAccountDescription(accountId)}`,
+                    defaultAccountSet: (accountId) => `Linked default account set to ${chalk.cyan(uiAccountDescription(accountId))}`,
+                    defaultAccountRemoved: (isSelectionRequired) => `The linked default account was removed. ${isSelectionRequired ? 'A linked default account is required.\n' : ''}`,
+                    defaultAccountRemains: (accountId) => `Linked default account remains ${chalk.cyan(uiAccountDescription(accountId))}`,
+                    updatedLinkedAccounts: 'Updated linked accounts',
+                    noAccountsLinked: `All accounts have been unlinked. Your global config accounts will be used.\n${indent(1)}The ${chalk.bold('.hs')} directory is no longer needed and can be safely deleted.`,
+                    overrideFileRemoved: '.hsaccount file removed',
+                    invalidDefaultAccount: (accountId) => `Default account ${uiAccountDescription(accountId)} is not in the linked accounts list and has been reset. Please select a new default.`,
+                },
+                prompts: {
+                    howToProceed: 'How would you like to link an account?',
+                    whatToDo: 'Which action would you like to perform?',
+                    linkExisting: 'Link existing authenticated account(s)',
+                    authenticateNew: 'Authenticate and link a new account',
+                    cancel: 'Cancel',
+                    selectDefault: 'Select a linked default account',
+                    selectToLink: 'Select authenticated account(s) to link:',
+                    selectToUnlink: 'Select account(s) to unlink',
+                    alreadyLinked: '- Already linked',
+                    fromHsAccount: '(from .hsaccount)',
+                    newlyAuthenticated: '(just authenticated)',
+                    mustSelectOne: 'You must select at least one account to link',
+                    keepAsDefault: 'Keep this as the default?',
+                },
+            },
+            unlink: {
+                describe: 'Unlink HubSpot account(s) from the current directory',
+                verboseDescribe: `Remove one or more linked accounts from this directory's ${chalk.bold('.hs/settings.json')}. If the default account is removed, you will be prompted to select a new one.\n\nThis does not delete the account from the global config - it only removes the local association.`,
             },
             remove: {
                 describe: 'Remove an account from the config.',
@@ -253,6 +322,9 @@ export const commands = {
                 },
                 name: (name) => `${chalk.bold('Account name')}: ${name}`,
                 scopeGroups: `${chalk.bold('Scopes available')}:`,
+                linkedDefaultTitle: `${chalk.bold('Linked Default Account')}`,
+                settingsPath: (path) => `Source: ${path}`,
+                linkedDefault: (account) => `Account: ${account}`,
             },
             clean: {
                 describe: 'Check for inactive accounts and removes them from the CLI config.',
@@ -1464,6 +1536,7 @@ export const commands = {
                 projectAccount: 'The id of the account to upload your project to. Must be used with --testing-account. Supported on platform versions 2025.2 and newer.',
                 testingAccount: 'The id of the account to install apps and test on. Must be used with --project-account. Supported on platform versions 2025.2 and newer.',
                 account: 'The id of the account to upload your project to. Unsupported on platform versions 2025.2 and newer.',
+                port: `The port for the local dev server. Defaults to ${LOCAL_DEV_DEFAULT_PORT}.`,
             },
         },
         create: {
@@ -1474,6 +1547,9 @@ export const commands = {
                 failedToFetchProjectList: 'Failed to fetch the list of available project templates. Please try again later.',
                 cannotNestProjects: (projectDir) => `A project already exists at ${projectDir}. Projects cannot be nested within other projects. Please choose a different destination and try again.`,
             },
+            warnings: {
+                betaPlatformVersion: (platformVersion) => `Your portal must be enrolled in the beta to use platform version ${platformVersion}. If you are not enrolled in the beta, your upload will fail. ${uiLink('Enroll in the beta', getProductUpdatesUrl('286886'))}`,
+            },
             logs: {
                 success: (projectName, projectDest) => `Project ${chalk.bold(projectName)} was successfully created in ${projectDest}`,
             },
@@ -1881,6 +1957,7 @@ export const commands = {
             loading: {
                 checking: 'Checking lint packages and configuration…',
                 creatingConfig: 'Creating ESLint configuration files…',
+                addingLintScripts: 'Adding lint scripts to package.json files…',
                 linting: 'Linting…',
             },
             noProjectConfig: 'No project detected. Run this command from a project directory.',
@@ -1900,8 +1977,17 @@ export const commands = {
             },
             createEslintConfigPrompt: (directories) => `ESLint configuration file not found in the following ${directories.length === 1 ? 'directory' : 'directories'}:\n${directories.map(d => `  - ${d}`).join('\n')}\n\nWould you like to set up the required ESLint configuration?`,
             eslintConfigCreated: (configPath) => `ESLint configuration created at ${configPath}`,
+            createEslintConfigRequiresV2Platform: (platformVersion) => {
+                if (!platformVersion) {
+                    return 'Automatic ESLint configuration requires a Developer Platform project (2025.2 or later) with platformVersion set in hsproject.json. Add an eslint.config.js file manually, or set platformVersion and try again.';
+                }
+                return `Automatic ESLint configuration is not available for platform version ${platformVersion}. Use Developer Platform 2025.2 or later, or add eslint.config.js manually.`;
+            },
+            failedToFetchRemoteEslintConfig: (platformVersion) => `Could not download the ESLint config from HubSpot project components for platform version ${platformVersion}. Check your network connection and try again, or add eslint.config.js manually.`,
             failedToCreateEslintConfig: (configPath) => `Failed to create ESLint configuration at ${configPath}`,
             eslintConfigRequired: 'ESLint configuration is required to run the lint command. Run the command again to create the configuration.',
+            lintScriptsAdded: (scriptNames, packageJsonPath) => `Added ${scriptNames.map(s => `"${s}"`).join(' and ')} to ${packageJsonPath}`,
+            failedToAddLintScripts: (packageJsonPath) => `Failed to add lint scripts to ${packageJsonPath}`,
         },
         updateDeps: {
             help: {
@@ -2030,6 +2116,25 @@ export const commands = {
                 force: 'skip confirmation prompt',
             },
         },
+        installStatus: {
+            describe: 'Check whether a static auth app in the current project is installed in the target account. This command must be run from within a HubSpot project directory.',
+            examples: {
+                default: 'Check install status for the static auth app in the current project',
+                json: 'Output install status as JSON',
+            },
+            errors: {
+                noProjectConfig: `No project config found. Run this command from within a HubSpot project directory, or use ${uiCommandReference('hs project create')} to create a new one.`,
+                unsupportedPlatformVersion: (platformVersion) => `This command is only supported for projects on platform version 2025.2 or later (detected: ${platformVersion}).`,
+                failedToParseProject: 'Failed to parse the project. Check your project configuration is valid and try again.',
+                noAppInProject: 'No app was found in the local project. Install status is only available for projects that contain an app.',
+                unsupportedAuthType: (authType) => `This command only supports static auth apps. Detected auth type: ${authType}.`,
+            },
+            success: {
+                installed: (appName, accountId) => `${chalk.bold(appName)} is installed in ${uiAccountDescription(accountId)}.`,
+                installedWithOutdatedScopes: (appName, accountId) => `${chalk.bold(appName)} is installed in ${uiAccountDescription(accountId)} with outdated scopes. Reinstall the app to grant the latest scopes.`,
+            },
+            notInstalled: (appName, accountId) => `${chalk.bold(appName)} is not installed in ${uiAccountDescription(accountId)}.`,
+        },
     },
     sandbox: {
         describe: 'Commands for managing sandboxes.',
@@ -2345,7 +2450,7 @@ export const commands = {
                 opsLevel: 'Operations Hub tier. Options: FREE, STARTER, PROFESSIONAL, ENTERPRISE',
                 serviceLevel: 'Service Hub tier. Options: FREE, STARTER, PROFESSIONAL, ENTERPRISE',
                 salesLevel: 'Sales Hub tier. Options: FREE, STARTER, PROFESSIONAL, ENTERPRISE',
-                contentLevel: 'CMS Hub tier. Options: FREE, STARTER, PROFESSIONAL, ENTERPRISE',
+                contentLevel: 'Content Hub tier. Options: FREE, STARTER, PROFESSIONAL, ENTERPRISE',
                 commerceLevel: 'Commerce Hub tier. Options: FREE, PROFESSIONAL, ENTERPRISE',
             },
             example: (configPath) => `Create a test account from the config file at ${configPath}`,
@@ -2998,6 +3103,9 @@ export const commands = {
     },
 };
 export const lib = {
+    linkedDirectory: {
+        warning: (action, settingsPath) => `This directory has linked accounts via ${settingsPath}. ${uiCommandReference(action)} modifies your global config, not the linked directory settings. Use ${uiCommandReference('hs account link')} to manage linked accounts.\n`,
+    },
     parsing: {
         unableToParseStringToNumber: 'Unable to parse string to number',
     },
@@ -3964,9 +4072,9 @@ export const lib = {
             validJson: 'JSON files valid',
         },
         port: {
-            inUse: (port) => `Port ${port} is in use`,
-            inUseSecondary: `Make sure it is available before running ${uiCommandReference('hs project dev')}`,
-            available: (port) => `Port ${port} available for local development`,
+            inUse: (port) => `Default port ${port} is in use`,
+            inUseSecondary: `Make sure it is available before running ${uiCommandReference('hs project dev')}, or use ${uiCommandReference('--port')} to specify a different port`,
+            available: (port) => `Default port ${port} available for local development`,
         },
         projectValidation: {
             valid: 'Project configuration and structure is valid',

package/lib/app/migrate.js

@@ -127,7 +127,8 @@ export async function selectAppToMigrate(allApps, derivedAccountId, appId) {
     let hasLegacyCrmCards = false;
     selectedApp?.migrationComponents.forEach(component => {
         const userFacingComponentType = mapToUserFacingType(component.componentType);
-        if (component.componentType === 'LEGACY_CRM_CARD' && !component.isSupported) {
+        if (component.componentType === 'LEGACY_CRM_CARD' &&
+            !component.isSupported) {
             hasLegacyCrmCards = true;
         }
         const shouldDisplayComponent = !AUTO_GENERATED_COMPONENT_TYPES.includes(userFacingComponentType);

package/lib/constants.d.ts

@@ -142,3 +142,4 @@ export declare const ACCOUNT_LEVELS: {
 };
 export declare const ACCOUNT_LEVEL_CHOICES: readonly ["FREE", "STARTER", "PROFESSIONAL", "ENTERPRISE"];
 export declare const FEEDBACK_URL = "https://developers.hubspot.com/feedback";
+export declare const LOCAL_DEV_DEFAULT_PORT = 4828;

package/lib/constants.js

@@ -143,3 +143,6 @@ export const ACCOUNT_LEVEL_CHOICES = [
     ACCOUNT_LEVELS.ENTERPRISE,
 ];
 export const FEEDBACK_URL = 'https://developers.hubspot.com/feedback';
+// TODO: remove this constant and use PORT_MANAGER_SERVER_PORT from
+// @hubspot/local-dev-lib once LDL changes its default to 4828.
+export const LOCAL_DEV_DEFAULT_PORT = 4828;

package/lib/doctor/Doctor.js

@@ -10,8 +10,8 @@ import fs from 'fs';
 import path from 'path';
 import { Diagnosis } from './Diagnosis.js';
 import { DiagnosticInfoBuilder, } from './DiagnosticInfoBuilder.js';
-import { isPortManagerPortAvailable } from '@hubspot/local-dev-lib/portManager';
-import { PORT_MANAGER_SERVER_PORT } from '@hubspot/local-dev-lib/constants/ports';
+import { isPortAvailable } from '@hubspot/local-dev-lib/portManager';
+import { LOCAL_DEV_DEFAULT_PORT } from '../constants.js';
 import { accessTokenForPersonalAccessKey,
 // scopesOnAccessToken,
  } from '@hubspot/local-dev-lib/personalAccessKey';
@@ -322,16 +322,16 @@ export class Doctor {
         }
     }
     async checkIfPortsAreAvailable() {
-        if (await isPortManagerPortAvailable()) {
+        if (await isPortAvailable(LOCAL_DEV_DEFAULT_PORT)) {
             this.diagnosis?.addProjectSection({
                 type: 'success',
-                message: lib.doctor.port.available(PORT_MANAGER_SERVER_PORT),
+                message: lib.doctor.port.available(LOCAL_DEV_DEFAULT_PORT),
             });
             return;
         }
         this.diagnosis?.addProjectSection({
             type: 'warning',
-            message: lib.doctor.port.inUse(PORT_MANAGER_SERVER_PORT),
+            message: lib.doctor.port.inUse(LOCAL_DEV_DEFAULT_PORT),
             secondaryMessaging: lib.doctor.port.inUseSecondary,
         });
     }

package/lib/link/accountTableUtils.d.ts

@@ -0,0 +1,10 @@
+export interface AccountRow {
+    name: string;
+    accountId: string;
+}
+export declare function buildAccountRow(accountId: number, isDefault: boolean): AccountRow;
+export declare function buildAccountHeader(nameColumnWidth: number): string;
+export declare function getNameColumnWidth(rows: AccountRow[]): number;
+export declare function sortDefaultFirst<T extends number | {
+    accountId: number;
+}>(items: T[], defaultAccount: number | undefined): T[];

package/lib/link/accountTableUtils.js

@@ -0,0 +1,39 @@
+import { HUBSPOT_ACCOUNT_TYPE_STRINGS } from '@hubspot/local-dev-lib/constants/config';
+import { getConfigAccountIfExists } from '@hubspot/local-dev-lib/config';
+import chalk from 'chalk';
+import { commands } from '../../lang/en.js';
+import { indent } from '../ui/index.js';
+import { INK_COLORS } from '../../ui/styles.js';
+export function buildAccountRow(accountId, isDefault) {
+    const account = getConfigAccountIfExists(accountId);
+    let name = String(accountId);
+    if (account && account.accountType) {
+        const typeStr = HUBSPOT_ACCOUNT_TYPE_STRINGS[account.accountType];
+        name = `${account.name} [${typeStr}]`;
+    }
+    if (isDefault) {
+        name = `${name} (default)`;
+    }
+    return { name, accountId: String(accountId) };
+}
+export function buildAccountHeader(nameColumnWidth) {
+    const labels = commands.account.subcommands.list.labels;
+    const paddedName = chalk.bold(chalk.hex(INK_COLORS.INFO_BLUE)(labels.name.padEnd(nameColumnWidth)));
+    const accountId = chalk.bold(chalk.hex(INK_COLORS.INFO_BLUE)(labels.accountId));
+    return `${indent(1)}${paddedName}  ${accountId}`;
+}
+export function getNameColumnWidth(rows) {
+    const labels = commands.account.subcommands.list.labels;
+    return Math.max(labels.name.length, ...rows.map(r => r.name.length));
+}
+export function sortDefaultFirst(items, defaultAccount) {
+    return [...items].sort((a, b) => {
+        const aId = typeof a === 'number' ? a : a.accountId;
+        const bId = typeof b === 'number' ? b : b.accountId;
+        if (aId === defaultAccount)
+            return -1;
+        if (bId === defaultAccount)
+            return 1;
+        return 0;
+    });
+}

package/lib/link/index.d.ts

@@ -0,0 +1,18 @@
+import { HsSettingsFile } from '@hubspot/local-dev-lib/types/HsSettings';
+import { ActionHandlerParams, ActionResult, LinkArgs } from '../../types/Link.js';
+import { ArgumentsCamelCase } from 'yargs';
+export declare class ActionHandlers {
+    static link({ state, context, }: ActionHandlerParams): Promise<ActionResult>;
+    static unlink({ state }: ActionHandlerParams): Promise<ActionResult>;
+    static authenticate({ state, context, args, }: ActionHandlerParams): Promise<ActionResult>;
+    static cancel(): Promise<ActionResult>;
+}
+export declare function handleLinkFlow({ settings, accountOverrideId, args, }: {
+    settings: HsSettingsFile;
+    accountOverrideId: number | null;
+    args: ArgumentsCamelCase<LinkArgs>;
+}): Promise<ActionResult>;
+export declare function handleLinkedUseAction({ state, targetAccountId, }: {
+    state: HsSettingsFile;
+    targetAccountId?: number;
+}): Promise<ActionResult>;

package/lib/link/index.js

@@ -0,0 +1,185 @@
+import { getAllConfigAccounts, getConfigDefaultAccountIfExists, } from '@hubspot/local-dev-lib/config';
+import { confirmPrompt } from '../prompts/promptUtils.js';
+import { promptForAccountsToLink, promptForAccountsToUnlink, promptForAction, promptForDefaultAccount, } from './prompts.js';
+import { ACTION_RESULT_STATUS, } from '../../types/Link.js';
+import { getDefaultAccountOverrideFilePath, removeDefaultAccountOverrideFile, } from '@hubspot/local-dev-lib/config/defaultAccountOverride';
+import { ENVIRONMENTS } from '@hubspot/local-dev-lib/constants/environments';
+import { authenticateNewAccount } from '../accountAuth.js';
+import { commands } from '../../lang/en.js';
+import { uiLogger } from '../ui/logger.js';
+export class ActionHandlers {
+    static async link({ state, context, }) {
+        const { eligibleAccounts, inEligibleAccounts } = context.globalAccountsList.reduce((accumulator, account) => {
+            if (state.accounts.includes(account.accountId)) {
+                accumulator.inEligibleAccounts.push(account);
+            }
+            else {
+                accumulator.eligibleAccounts.push(account);
+            }
+            return accumulator;
+        }, { eligibleAccounts: [], inEligibleAccounts: [] });
+        const toAdd = await promptForAccountsToLink(context, eligibleAccounts, inEligibleAccounts, state.localDefaultAccount);
+        const accounts = [...state.accounts, ...toAdd];
+        uiLogger.info(commands.account.subcommands.link.events.accountsLinked(toAdd.length));
+        const overrideFilePath = getDefaultAccountOverrideFilePath();
+        if (overrideFilePath &&
+            context.accountOverrideId &&
+            accounts.includes(context.accountOverrideId)) {
+            uiLogger.log(commands.account.subcommands.link.events.overrideAccountDetected(context.accountOverrideId));
+            uiLogger.log('');
+            const useOverride = await confirmPrompt(commands.account.subcommands.link.prompts.keepAsDefault);
+            removeDefaultAccountOverrideFile();
+            uiLogger.success(commands.account.subcommands.link.events.overrideFileRemoved);
+            if (useOverride) {
+                uiLogger.success(commands.account.subcommands.link.events.defaultAccountSet(context.accountOverrideId));
+                return {
+                    status: ACTION_RESULT_STATUS.SUCCESS,
+                    settings: {
+                        accounts,
+                        localDefaultAccount: context.accountOverrideId,
+                    },
+                };
+            }
+        }
+        const localDefaultAccount = await resolveDefaultAccount({
+            accounts,
+            currentDefault: state.localDefaultAccount,
+        });
+        return {
+            status: ACTION_RESULT_STATUS.SUCCESS,
+            settings: { accounts, localDefaultAccount },
+        };
+    }
+    static async unlink({ state }) {
+        const toRemove = await promptForAccountsToUnlink(state.accounts, state.localDefaultAccount);
+        if (toRemove.length === 0) {
+            return { status: ACTION_RESULT_STATUS.NOOP };
+        }
+        const remainingAccounts = state.accounts.filter(account => !toRemove.includes(account));
+        const defaultWasRemoved = state.localDefaultAccount !== undefined &&
+            toRemove.includes(state.localDefaultAccount);
+        // All accounts removed
+        if (remainingAccounts.length === 0) {
+            uiLogger.success(commands.account.subcommands.link.events.noAccountsLinked);
+            return {
+                status: ACTION_RESULT_STATUS.SUCCESS,
+                settings: {
+                    accounts: remainingAccounts,
+                    localDefaultAccount: undefined,
+                },
+            };
+        }
+        //  Default was NOT removed — accounts remain, default unchanged
+        if (!defaultWasRemoved) {
+            uiLogger.success(commands.account.subcommands.link.events.accountsUnlinked(toRemove.length));
+            uiLogger.success(commands.account.subcommands.link.events.defaultAccountRemains(state.localDefaultAccount));
+            return {
+                status: ACTION_RESULT_STATUS.SUCCESS,
+                settings: {
+                    accounts: remainingAccounts,
+                    localDefaultAccount: state.localDefaultAccount,
+                },
+            };
+        }
+        //  Default WAS removed — need a new default
+        uiLogger.warn(commands.account.subcommands.link.events.defaultAccountRemoved(remainingAccounts.length !== 1));
+        const localDefaultAccount = await resolveDefaultAccount({
+            accounts: remainingAccounts,
+            currentDefault: undefined,
+        });
+        if (remainingAccounts.length === 1) {
+            uiLogger.success(commands.account.subcommands.link.events.updatedLinkedAccounts);
+        }
+        return {
+            status: ACTION_RESULT_STATUS.SUCCESS,
+            settings: { accounts: remainingAccounts, localDefaultAccount },
+        };
+    }
+    static async authenticate({ state, context, args, }) {
+        const updatedConfig = await authenticateNewAccount({
+            env: args.qa ? ENVIRONMENTS.QA : ENVIRONMENTS.PROD,
+            setAsDefaultAccount: false,
+        });
+        if (!updatedConfig) {
+            return {
+                status: ACTION_RESULT_STATUS.ERROR,
+                reason: commands.account.subcommands.link.errors.authFailed,
+            };
+        }
+        const updatedContext = {
+            globalAccountsList: getAllConfigAccounts(),
+            globalDefaultAccount: getConfigDefaultAccountIfExists(),
+            accountOverrideId: context.accountOverrideId,
+            preselectedAccountId: updatedConfig.accountId,
+        };
+        return ActionHandlers.link({ state, context: updatedContext, args });
+    }
+    static async cancel() {
+        return {
+            status: ACTION_RESULT_STATUS.NOOP,
+        };
+    }
+}
+export async function handleLinkFlow({ settings, accountOverrideId, args, }) {
+    const context = {
+        globalAccountsList: getAllConfigAccounts(),
+        globalDefaultAccount: getConfigDefaultAccountIfExists(),
+        accountOverrideId,
+    };
+    const accounts = settings.accounts ?? [];
+    // The default account must be one of the linked accounts. This can get
+    // out of sync if the settings file is manually edited.
+    const hasInvalidDefault = settings.localDefaultAccount !== undefined &&
+        !accounts.includes(settings.localDefaultAccount);
+    if (hasInvalidDefault) {
+        uiLogger.warn(commands.account.subcommands.link.events.invalidDefaultAccount(settings.localDefaultAccount));
+    }
+    const initialState = {
+        localDefaultAccount: hasInvalidDefault
+            ? undefined
+            : settings.localDefaultAccount,
+        accounts,
+    };
+    return runAction(initialState, context, args);
+}
+async function runAction(state, context, args) {
+    const action = await promptForAction(state);
+    return ActionHandlers[action]({ state, context, args });
+}
+async function resolveDefaultAccount({ accounts, currentDefault, prompt = '', }) {
+    if (accounts.length === 1) {
+        uiLogger.success(commands.account.subcommands.link.events.defaultAccountSet(accounts[0]));
+        return accounts[0];
+    }
+    return promptForDefaultAccount(accounts, currentDefault, prompt);
+}
+export async function handleLinkedUseAction({ state, targetAccountId, }) {
+    if (targetAccountId !== undefined) {
+        if (state.accounts.includes(targetAccountId)) {
+            uiLogger.success(commands.account.subcommands.link.events.defaultAccountSet(targetAccountId));
+            return {
+                status: ACTION_RESULT_STATUS.SUCCESS,
+                settings: {
+                    accounts: state.accounts,
+                    localDefaultAccount: targetAccountId,
+                },
+            };
+        }
+        const accounts = [...state.accounts, targetAccountId];
+        uiLogger.info(commands.account.subcommands.link.events.accountsLinked(1));
+        uiLogger.success(commands.account.subcommands.link.events.defaultAccountSet(targetAccountId));
+        return {
+            status: ACTION_RESULT_STATUS.SUCCESS,
+            settings: { accounts, localDefaultAccount: targetAccountId },
+        };
+    }
+    const localDefaultAccount = await resolveDefaultAccount({
+        accounts: state.accounts,
+        currentDefault: state.localDefaultAccount,
+    });
+    uiLogger.success(commands.account.subcommands.link.events.defaultAccountSet(localDefaultAccount));
+    return {
+        status: ACTION_RESULT_STATUS.SUCCESS,
+        settings: { accounts: state.accounts, localDefaultAccount },
+    };
+}

package/lib/link/linkUtils.d.ts

@@ -0,0 +1,5 @@
+import { HsSettingsFile } from '@hubspot/local-dev-lib/types/HsSettings';
+export declare function isDirectoryLinked(settings: HsSettingsFile | null): settings is HsSettingsFile;
+export declare function hasDeprecatedConfigConflict(commandArgs: (string | number)[]): boolean;
+export declare function addAccountToLinkedSettings(accountId: number): void;
+export declare function writeLinkedSettings(settings: HsSettingsFile, settingsPath: string): boolean;

package/lib/link/linkUtils.js

@@ -0,0 +1,49 @@
+import { localConfigFileExists } from '@hubspot/local-dev-lib/config';
+import { getHsSettingsFileIfExists, writeHsSettingsFile, } from '@hubspot/local-dev-lib/config/hsSettings';
+import { uiLogger } from '../ui/logger.js';
+import { debugError } from '../errorHandlers/index.js';
+import { commands } from '../../lang/en.js';
+export function isDirectoryLinked(settings) {
+    return settings !== null && settings.accounts.length > 0;
+}
+export function hasDeprecatedConfigConflict(commandArgs) {
+    if (localConfigFileExists()) {
+        uiLogger.error(commands.account.subcommands.link.shared.deprecatedConfigNotSupported(`hs ${commandArgs.join(' ')}`));
+        return true;
+    }
+    return false;
+}
+export function addAccountToLinkedSettings(accountId) {
+    if (localConfigFileExists()) {
+        return;
+    }
+    const settings = getHsSettingsFileIfExists();
+    if (!settings || settings.accounts.length === 0) {
+        return;
+    }
+    if (settings.accounts.includes(accountId)) {
+        return;
+    }
+    const updated = {
+        ...settings,
+        accounts: [...settings.accounts, accountId],
+    };
+    try {
+        writeHsSettingsFile(updated);
+        uiLogger.info(commands.account.subcommands.link.shared.accountAutoLinked(accountId));
+    }
+    catch (err) {
+        uiLogger.warn(commands.account.subcommands.link.shared.accountAutoLinkFailed(accountId));
+        debugError(err);
+    }
+}
+export function writeLinkedSettings(settings, settingsPath) {
+    try {
+        writeHsSettingsFile(settings);
+        return true;
+    }
+    catch (err) {
+        uiLogger.error(commands.account.subcommands.link.shared.writeSettingsFailed(settingsPath, err));
+        return false;
+    }
+}

package/lib/link/prompts.d.ts

@@ -0,0 +1,7 @@
+import { HubSpotConfigAccount } from '@hubspot/local-dev-lib/types/Accounts';
+import { ActionName, LinkContext } from '../../types/Link.js';
+import { HsSettingsFile } from '@hubspot/local-dev-lib/types/HsSettings';
+export declare function promptForAction(state: HsSettingsFile): Promise<ActionName>;
+export declare function promptForDefaultAccount(accounts: number[], currentDefaultAccount: number | undefined, prompt?: string): Promise<number>;
+export declare function promptForAccountsToLink(context: LinkContext, eligibleAccounts: HubSpotConfigAccount[], inEligibleAccounts: HubSpotConfigAccount[], localDefaultAccount: number | undefined): Promise<number[]>;
+export declare function promptForAccountsToUnlink(accounts: number[], localDefaultAccount: number | undefined): Promise<number[]>;