@hubspot/cli 8.16.0-beta.2 → 8.17.0-beta.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/bin/cli.js CHANGED
@@ -39,6 +39,8 @@ import { initializeSpinniesManager } from '../lib/middleware/spinniesMiddleware.
39
39
  import { addCommandSuggestions } from '../lib/commandSuggestion.js';
40
40
  import { pkg } from '../lib/jsonLoader.js';
41
41
  import { parseYargsOrExit } from '../lib/yargs/parseYargsOrExit.js';
42
+ import { getRootAgentHelp, recordCommands } from '../lib/agentHelp.js';
43
+ import { hasFlag } from '../lib/utils/hasFlag.js';
42
44
  function getTerminalWidth() {
43
45
  const width = yargs().terminalWidth();
44
46
  if (width >= 100)
@@ -61,7 +63,16 @@ function handleFailure(msg, err, yargs) {
61
63
  process.exit(EXIT_CODES.ERROR);
62
64
  }
63
65
  }
64
- const argv = yargs(process.argv.slice(2))
66
+ const isAgentHelp = hasFlag('agent-help');
67
+ const isRootAgentHelp = isAgentHelp && process.argv.slice(2).every(arg => arg.startsWith('-'));
68
+ // --agent-help shows the normal help, so the command never runs. Some
69
+ // builders read process.argv directly, so --help goes there too.
70
+ if (isAgentHelp) {
71
+ process.argv.splice(process.argv.indexOf('--agent-help') + 1, 0, '--help');
72
+ }
73
+ const rootYargs = yargs(process.argv.slice(2));
74
+ const rootCommands = isRootAgentHelp ? recordCommands(rootYargs) : [];
75
+ const argv = rootYargs
65
76
  .usage('The command line interface to interact with HubSpot.')
66
77
  .middleware([
67
78
  setCLILogLevel,
@@ -98,6 +109,10 @@ const argv = yargs(process.argv.slice(2))
98
109
  default: false,
99
110
  hidden: true,
100
111
  type: 'boolean',
112
+ })
113
+ .option('agent-help', {
114
+ describe: lib.commonOpts.options.agentHelp,
115
+ type: 'boolean',
101
116
  })
102
117
  .check(performChecks)
103
118
  // Getting started / important
@@ -126,6 +141,9 @@ const argv = yargs(process.argv.slice(2))
126
141
  .command(doctorCommand)
127
142
  .command(mcpCommand)
128
143
  .command(upgradeCommand);
144
+ if (isRootAgentHelp) {
145
+ argv.epilogue(await getRootAgentHelp(rootCommands));
146
+ }
129
147
  const parser = addCommandSuggestions(argv)
130
148
  .help()
131
149
  .alias('h', 'help')
@@ -113,7 +113,7 @@ async function handler(args) {
113
113
  desktopScoreStatus = data;
114
114
  }
115
115
  let mobileScoreStatus = 'COMPLETED';
116
- if (includeDesktopScore) {
116
+ if (includeMobileScore) {
117
117
  const { data } = await getLighthouseScoreStatus(derivedAccountId, {
118
118
  themeId: requestResult.mobileId,
119
119
  });
@@ -3,6 +3,7 @@ interface MCPSetupArgs extends CommonArgs {
3
3
  client?: string[];
4
4
  standalone?: boolean;
5
5
  cliVersion?: string;
6
+ skills?: string[];
6
7
  }
7
8
  declare const mcpSetupCommand: YargsCommandModule<unknown, MCPSetupArgs>;
8
9
  export default mcpSetupCommand;
@@ -3,6 +3,7 @@ import { makeYargsBuilder } from '../../lib/yargsUtils.js';
3
3
  import { commands } from '../../lang/en.js';
4
4
  import { makeWrappedYargsHandler } from '../../lib/yargs/makeWrappedYargsHandler.js';
5
5
  import { configureMcpServer, supportedTools } from '../../lib/mcp/setup.js';
6
+ import { MCP_SKILL_NAMES } from '../../lib/mcp/skills.js';
6
7
  const command = ['setup'];
7
8
  const describe = commands.mcp.setup.describe;
8
9
  async function handler(args) {
@@ -12,6 +13,7 @@ async function handler(args) {
12
13
  targets: args.client,
13
14
  standalone: args.standalone,
14
15
  cliVersion: args.cliVersion,
16
+ skills: args.skills,
15
17
  });
16
18
  }
17
19
  catch (e) {
@@ -33,6 +35,11 @@ function setupBuilder(yargs) {
33
35
  describe: commands.mcp.setup.args.cliVersion,
34
36
  type: 'string',
35
37
  });
38
+ yargs.option('skills', {
39
+ describe: commands.mcp.setup.args.skills,
40
+ type: 'array',
41
+ choices: MCP_SKILL_NAMES,
42
+ });
36
43
  yargs.check(argv => {
37
44
  if (argv.cliVersion !== undefined && argv.standalone !== true) {
38
45
  throw new Error(commands.mcp.setup.errors.cliVersionRequiresStandalone);
@@ -41,7 +48,7 @@ function setupBuilder(yargs) {
41
48
  });
42
49
  yargs.example([
43
50
  [
44
- '$0 mcp setup --client claude --no-standalone',
51
+ '$0 mcp setup --client claude --no-standalone --skills hubspot-new-app hubspot-fix-build',
45
52
  commands.mcp.setup.examples.nonInteractive,
46
53
  ],
47
54
  [
package/lang/en.d.ts CHANGED
@@ -1326,7 +1326,6 @@ export declare const commands: {
1326
1326
  claudeCode: string;
1327
1327
  cursor: string;
1328
1328
  devin: string;
1329
- gemini: string;
1330
1329
  opencode: string;
1331
1330
  vsCode: string;
1332
1331
  other: string;
@@ -1334,6 +1333,7 @@ export declare const commands: {
1334
1333
  client: string;
1335
1334
  standalone: string;
1336
1335
  cliVersion: string;
1336
+ skills: string;
1337
1337
  docsSearch: string;
1338
1338
  };
1339
1339
  examples: {
@@ -1359,10 +1359,6 @@ export declare const commands: {
1359
1359
  cursorNotFound: string;
1360
1360
  failedToConfigureCursor: string;
1361
1361
  configuredCursor: string;
1362
- configuringGemini: string;
1363
- configuredGemini: string;
1364
- geminiNotFound: string;
1365
- geminiInstallFailed: string;
1366
1362
  alreadyInstalled: string;
1367
1363
  configuringDevin: string;
1368
1364
  devinNotFound: string;
@@ -1377,18 +1373,27 @@ export declare const commands: {
1377
1373
  configuredVsCode: string;
1378
1374
  vsCodeNotFound: string;
1379
1375
  vsCodeVersionUnsupported: string;
1376
+ installingSkills: string;
1377
+ installedSkills: (skillNames: string[], targetDirs: string[]) => string;
1378
+ failedToInstallSkills: string;
1380
1379
  };
1381
1380
  otherInstructions: {
1382
1381
  header: string;
1383
1382
  docsNote: string;
1384
1383
  commandLabel: string;
1385
1384
  jsonLabel: string;
1385
+ skillsNote: (skillsDir: string) => string;
1386
1386
  };
1387
1387
  prompts: {
1388
1388
  targets: string;
1389
1389
  targetsRequired: string;
1390
1390
  standaloneMode: string;
1391
1391
  cliVersion: string;
1392
+ selectSkills: string;
1393
+ };
1394
+ skillDescriptions: {
1395
+ newApp: string;
1396
+ fixBuild: string;
1392
1397
  };
1393
1398
  };
1394
1399
  start: {
@@ -3385,6 +3390,28 @@ export declare const lib: {
3385
3390
  noSchemaForCommand: string;
3386
3391
  validationFailed: string;
3387
3392
  };
3393
+ agentHelp: {
3394
+ headings: {
3395
+ conventions: string;
3396
+ jsonOutput: string;
3397
+ workflows: string;
3398
+ exitCodes: string;
3399
+ commands: string;
3400
+ };
3401
+ conventions: string[];
3402
+ jsonOutput: {
3403
+ schema: string;
3404
+ noSchema: string;
3405
+ };
3406
+ workflows: {
3407
+ title: string;
3408
+ steps: {
3409
+ command: string;
3410
+ description: string;
3411
+ }[];
3412
+ }[];
3413
+ exitCodes: string;
3414
+ };
3388
3415
  DevServerManager: {
3389
3416
  portConflict: (port: string) => string;
3390
3417
  notInitialized: string;
@@ -3865,6 +3892,7 @@ export declare const lib: {
3865
3892
  useEnv: string;
3866
3893
  jsonOutput: string;
3867
3894
  jsonSchema: string;
3895
+ agentHelp: string;
3868
3896
  debug: string;
3869
3897
  color: string;
3870
3898
  };
@@ -3925,6 +3953,7 @@ export declare const lib: {
3925
3953
  message: (dataFileNames: string[], cliAccount: HubSpotConfigAccount | null) => string;
3926
3954
  };
3927
3955
  importDataTestAccountSelectPrompt: {
3956
+ message: string;
3928
3957
  errors: {
3929
3958
  noAccountsFound: string;
3930
3959
  noChildTestAccountsFound: (parentAccountId: number) => string;
package/lang/en.js CHANGED
@@ -7,6 +7,7 @@ import { ARCHIVED_HUBSPOT_CONFIG_YAML_FILE_NAME, DEFAULT_HUBSPOT_CONFIG_YAML_FIL
7
7
  import { indent, UI_COLORS, uiAccountDescription, uiAuthCommandReference, uiBetaTag, uiCommandReference, uiDeprecatedTag, uiLink, } from '../lib/ui/index.js';
8
8
  import { getLocalDevUiUrl, getProjectDetailUrl, getProjectSettingsUrl, } from '../lib/projects/urls.js';
9
9
  import { getProductUpdatesUrl } from '../lib/links.js';
10
+ const AGENT_HELP_EXIT_CODES = '0 means success. 1 means an error. 2 means a warning, for example a validation issue or JSON output that does not match its schema.';
10
11
  const MIGRATION_SUPPORT_CUTOFF_NOTICE = 'Automated platform version migrations beyond 2026.09 will not be supported.';
11
12
  export const commands = {
12
13
  generalErrors: {
@@ -1336,7 +1337,6 @@ export const commands = {
1336
1337
  claudeCode: 'Claude Code',
1337
1338
  cursor: 'Cursor',
1338
1339
  devin: 'Devin',
1339
- gemini: 'Gemini CLI',
1340
1340
  opencode: 'OpenCode',
1341
1341
  vsCode: 'VSCode',
1342
1342
  other: 'Other (manual setup)',
@@ -1344,6 +1344,7 @@ export const commands = {
1344
1344
  client: 'Target apps to configure',
1345
1345
  standalone: 'Use npx for all of the hs commands run by the MCP server. This allows you to use the MCP server without having the CLI globally installed.',
1346
1346
  cliVersion: 'Pin a specific CLI version for standalone mode',
1347
+ skills: 'HubSpot skills to install for the selected tools. Pass --skills with no names to skip skills.',
1347
1348
  docsSearch: 'Should the docs search mcp server be installed',
1348
1349
  },
1349
1350
  examples: {
@@ -1372,11 +1373,6 @@ export const commands = {
1372
1373
  cursorNotFound: 'Cursor is not installed. Install it and re-run hs mcp setup.',
1373
1374
  failedToConfigureCursor: 'Failed to configure Cursor',
1374
1375
  configuredCursor: 'Configured Cursor',
1375
- // Gemini
1376
- configuringGemini: 'Configuring Gemini CLI...',
1377
- configuredGemini: 'Configured Gemini CLI',
1378
- geminiNotFound: "Gemini CLI is not installed (missing 'gemini' command). Install it and re-run hs mcp setup.",
1379
- geminiInstallFailed: 'Failed to configure Gemini CLI',
1380
1376
  alreadyInstalled: 'HubSpot CLI mcp server already installed, reinstalling',
1381
1377
  // Devin
1382
1378
  configuringDevin: 'Configuring Devin...',
@@ -1394,18 +1390,28 @@ export const commands = {
1394
1390
  configuredVsCode: 'Configured VSCode',
1395
1391
  vsCodeNotFound: "VSCode CLI is not installed (missing 'code' command). Install it and re-run hs mcp setup.",
1396
1392
  vsCodeVersionUnsupported: 'VSCode 1.99 or later is required for MCP server support. Please update VSCode and try again.',
1393
+ // Skills
1394
+ installingSkills: 'Installing HubSpot skills...',
1395
+ installedSkills: (skillNames, targetDirs) => `Installed ${skillNames.join(', ')} in ${targetDirs.join(', ')}`,
1396
+ failedToInstallSkills: 'Failed to install HubSpot skills',
1397
1397
  },
1398
1398
  otherInstructions: {
1399
1399
  header: 'To connect the HubSpot MCP server to another tool, add the following MCP server configuration.',
1400
1400
  docsNote: "Each tool handles MCP setup differently. Check your tool's documentation for how to add an MCP server using a command or JSON config.",
1401
1401
  commandLabel: 'Command:',
1402
1402
  jsonLabel: 'JSON configuration (for tools that use a config file):',
1403
+ skillsNote: (skillsDir) => `To add HubSpot skills, copy the folders in ${skillsDir} to your tool's skills folder.`,
1403
1404
  },
1404
1405
  prompts: {
1405
1406
  targets: '[--client] Which tools would you like to add the HubSpot CLI MCP server to?',
1406
1407
  targetsRequired: 'Must choose at least one app to configure.',
1407
1408
  standaloneMode: 'Do you want to run in standalone mode? (This will use npx @hubspot/cli instead of the installed hs command)',
1408
1409
  cliVersion: 'Specify a CLI version to pin (leave blank for latest):',
1410
+ selectSkills: '[--skills] Which HubSpot skills do you want to install? (optional)',
1411
+ },
1412
+ skillDescriptions: {
1413
+ newApp: 'Plan and create a HubSpot app project',
1414
+ fixBuild: 'Find and fix a failed project build',
1409
1415
  },
1410
1416
  },
1411
1417
  start: {
@@ -3411,6 +3417,120 @@ export const lib = {
3411
3417
  noSchemaForCommand: 'No schema defined for this command',
3412
3418
  validationFailed: 'JSON output may be missing or malformed fields. The output schema may be out of date.',
3413
3419
  },
3420
+ agentHelp: {
3421
+ headings: {
3422
+ conventions: chalk.bold('Conventions:'),
3423
+ jsonOutput: chalk.bold('JSON output:'),
3424
+ workflows: chalk.bold('Workflows:'),
3425
+ exitCodes: chalk.bold('Exit codes:'),
3426
+ commands: chalk.bold('All commands:'),
3427
+ },
3428
+ conventions: [
3429
+ 'More help: To see the workflows that use one command, run `hs <command> --agent-help`.',
3430
+ 'JSON output: Commands that support `--json` print one JSON object to stdout when they finish. Errors and warnings print to stderr.',
3431
+ 'JSON schemas: To print the JSON Schema for the output of a command, run the command with `--json-schema`.',
3432
+ 'Prompts: Commands prompt for values that you do not pass as flags. To run a command without prompts, pass each value as a flag.',
3433
+ 'Long-running commands: `hs project dev` runs until it is stopped and prompts for input. Ask the user to run it in their own terminal.',
3434
+ 'Accounts: Commands use the default account in the CLI config. To use a different account, pass `--account <name or ID>`. To see the configured accounts, run `hs account list`.',
3435
+ 'Environment variables: To read the account from `HUBSPOT_ACCOUNT_ID` and `HUBSPOT_PERSONAL_ACCESS_KEY` instead of the config file, pass `--use-env`.',
3436
+ 'Config file: The global config file is `~/.hscli/config.yml`. To use a different file, pass `--config <path>`.',
3437
+ 'Color: To remove color from the output, pass `--no-color` or set `NO_COLOR`.',
3438
+ 'Debug logs: To print debug logs, pass `--debug`.',
3439
+ 'MCP server: To connect the HubSpot Dev MCP server to an AI coding tool, run `hs mcp setup`.',
3440
+ ],
3441
+ jsonOutput: {
3442
+ schema: 'With `--json`, the command prints one JSON object to stdout. The object matches this JSON Schema:',
3443
+ noSchema: 'With `--json`, the command prints JSON to stdout. The CLI does not define a schema for this output.',
3444
+ },
3445
+ workflows: [
3446
+ {
3447
+ title: 'Authenticate an account',
3448
+ steps: [
3449
+ {
3450
+ command: 'hs account auth',
3451
+ description: 'Ask the user to run this command in their own terminal. It can open a browser page where the user creates a personal access key, and then it prompts for the key. Do not ask the user to paste the key into the conversation.',
3452
+ },
3453
+ {
3454
+ command: 'hs account list',
3455
+ description: 'List the accounts in the CLI config.',
3456
+ },
3457
+ {
3458
+ command: 'hs account use <account>',
3459
+ description: 'Set the default account. Commands use the default account unless you pass `--account`.',
3460
+ },
3461
+ ],
3462
+ },
3463
+ {
3464
+ title: 'Create a project',
3465
+ steps: [
3466
+ {
3467
+ command: 'hs project create --name <name> --dest <directory> --project-base app --distribution <private|marketplace> --auth <oauth|static> --features --json',
3468
+ description: 'Create a project with an app in a new directory. Pass every flag to skip the prompts. A `--features` flag with no values adds no features.',
3469
+ },
3470
+ {
3471
+ command: 'hs project validate --json',
3472
+ description: 'Run this command in the project directory. It checks the project files before you upload them.',
3473
+ },
3474
+ ],
3475
+ },
3476
+ {
3477
+ title: 'Generate test data',
3478
+ steps: [
3479
+ {
3480
+ command: 'hs test-account create --name <name> --description <description> --marketing-level ENTERPRISE --ops-level ENTERPRISE --service-level ENTERPRISE --sales-level ENTERPRISE --content-level ENTERPRISE --commerce-level ENTERPRISE',
3481
+ description: 'Create a developer test account and save it to the CLI config. Pass every flag to skip the prompts. Do not pass `--json`. With `--json`, the command does not save the account to the config, and the output includes the personal access key of the account.',
3482
+ },
3483
+ {
3484
+ command: 'hs test-account import-data --account <test account> --file-path <import.json> --skip-confirm',
3485
+ description: 'Import CRM records into the test account. The JSON file uses the request format of the CRM imports API: https://developers.hubspot.com/docs/guides/api/crm/imports. Each `fileName` in the file is a path relative to the current directory.',
3486
+ },
3487
+ ],
3488
+ },
3489
+ {
3490
+ title: 'Develop a project',
3491
+ steps: [
3492
+ {
3493
+ command: 'hs project create',
3494
+ description: 'Create the project. The "Create a project" workflow shows the flags that skip the prompts.',
3495
+ },
3496
+ {
3497
+ command: 'hs project upload --json',
3498
+ description: 'Run this command in the project directory. It uploads the project and creates a build. If auto-deploy is on, it also deploys the build, and the output includes `deployId`.',
3499
+ },
3500
+ {
3501
+ command: 'hs project deploy --build <buildId> --json',
3502
+ description: 'Deploy the build. Use this command if the upload output has no `deployId`.',
3503
+ },
3504
+ {
3505
+ command: 'hs project dev',
3506
+ description: 'Ask the user to run this command in their own terminal. It starts local development and runs until it is stopped. Changes upload from the Local Dev Panel, or as you edit with `--auto-upload`. To test on a test account, also pass `--testing-account <test account ID>` and `--project-account <developer account ID>`.',
3507
+ },
3508
+ {
3509
+ command: 'hs project list-builds --limit 1 --json',
3510
+ description: 'Show the status of the latest build. `deployedBuildId` is the build that is deployed now.',
3511
+ },
3512
+ ],
3513
+ },
3514
+ {
3515
+ title: 'Investigate a failed build',
3516
+ steps: [
3517
+ {
3518
+ command: 'hs project list-builds --limit 1 --json',
3519
+ description: 'Get the latest build. Each entry in `subbuildStatuses` has the status and error message of one component.',
3520
+ },
3521
+ {
3522
+ command: 'hs project validate --json',
3523
+ description: 'Validate the local project files.',
3524
+ },
3525
+ {
3526
+ command: 'hs project upload --json',
3527
+ description: 'Upload the project again after you fix the errors.',
3528
+ },
3529
+ ],
3530
+ },
3531
+ ],
3532
+ exitCodes: AGENT_HELP_EXIT_CODES,
3533
+ },
3414
3534
  DevServerManager: {
3415
3535
  portConflict: (port) => `The port ${port} is already in use.`,
3416
3536
  notInitialized: 'The Dev Server Manager must be initialized before it is started.',
@@ -3905,6 +4025,7 @@ export const lib = {
3905
4025
  useEnv: 'Use environment variable config',
3906
4026
  jsonOutput: 'Format output as JSON',
3907
4027
  jsonSchema: 'Print the JSON output schema and exit',
4028
+ agentHelp: 'Show help with workflows and conventions for AI agents',
3908
4029
  debug: 'Set log level to debug',
3909
4030
  color: 'Enable colored output (use --no-color to disable)',
3910
4031
  },
@@ -3965,6 +4086,7 @@ export const lib = {
3965
4086
  message: (dataFileNames, cliAccount) => `You are importing [${dataFileNames.join(', ')}] into ${uiAccountDescription(cliAccount?.accountId)}. Continue?`,
3966
4087
  },
3967
4088
  importDataTestAccountSelectPrompt: {
4089
+ message: '[--account] Select a developer test account:',
3968
4090
  errors: {
3969
4091
  noAccountsFound: 'No accounts found.',
3970
4092
  noChildTestAccountsFound: (parentAccountId) => `No developer test accounts found under the parent account ${uiAccountDescription(parentAccountId)}`,
@@ -0,0 +1,17 @@
1
+ import { Argv } from 'yargs';
2
+ type CommandModule = {
3
+ command?: string | readonly string[];
4
+ describe?: string | false;
5
+ builder?: unknown;
6
+ handler?: unknown;
7
+ };
8
+ export declare function recordCommands(instance: Argv): CommandModule[];
9
+ type VisitedCommand = {
10
+ module: CommandModule;
11
+ commandPath: string[];
12
+ usage: string;
13
+ };
14
+ export declare function walkCommands(modules: CommandModule[], visit: (command: VisitedCommand) => void, parentPath?: string[]): Promise<void>;
15
+ export declare function getRootAgentHelp(rootCommands: CommandModule[]): Promise<string>;
16
+ export declare function getCommandAgentHelp(command: string, helpText: string): string;
17
+ export {};
@@ -0,0 +1,90 @@
1
+ import yargs from 'yargs';
2
+ import { z } from 'zod';
3
+ import { lib } from '../lang/en.js';
4
+ import { indent } from './ui/index.js';
5
+ import { debugError } from './errorHandlers/index.js';
6
+ import { getJsonOutputSchema } from './yargs/makeWrappedYargsHandler.js';
7
+ const { agentHelp } = lib;
8
+ function formatSection(heading, lines) {
9
+ return [heading, ...lines.map(line => `${indent(1)}${line}`)].join('\n');
10
+ }
11
+ function formatWorkflows(workflows) {
12
+ return formatSection(agentHelp.headings.workflows, workflows.flatMap(({ title, steps }) => [
13
+ title,
14
+ ...steps.flatMap(({ command, description }, index) => [
15
+ `${indent(1)}${index + 1}. ${command}`,
16
+ `${indent(2)} ${description}`,
17
+ ]),
18
+ ]));
19
+ }
20
+ export function recordCommands(instance) {
21
+ const commands = [];
22
+ const { command } = instance;
23
+ Object.assign(instance, {
24
+ command(...args) {
25
+ const [module] = args;
26
+ if (typeof module === 'object' && module !== null) {
27
+ commands.push(module);
28
+ }
29
+ return Reflect.apply(command, instance, args);
30
+ },
31
+ });
32
+ return commands;
33
+ }
34
+ export async function walkCommands(modules, visit, parentPath = []) {
35
+ for (const module of modules) {
36
+ const [commandString = ''] = [module.command ?? []].flat();
37
+ const commandPath = [...parentPath, commandString.split(' ')[0]];
38
+ visit({
39
+ module,
40
+ commandPath,
41
+ usage: ['hs', ...parentPath, commandString].join(' '),
42
+ });
43
+ const instance = yargs([]);
44
+ const subcommands = recordCommands(instance);
45
+ try {
46
+ if (typeof module.builder === 'function') {
47
+ await module.builder(instance);
48
+ }
49
+ }
50
+ catch (e) {
51
+ debugError(e);
52
+ }
53
+ await walkCommands(subcommands, visit, commandPath);
54
+ }
55
+ }
56
+ function joinSections(sections) {
57
+ return sections.filter(Boolean).join('\n\n');
58
+ }
59
+ function formatExitCodes() {
60
+ return formatSection(agentHelp.headings.exitCodes, [agentHelp.exitCodes]);
61
+ }
62
+ export async function getRootAgentHelp(rootCommands) {
63
+ const commandLines = [];
64
+ await walkCommands(rootCommands, ({ module, usage }) => {
65
+ if (typeof module.describe === 'string') {
66
+ commandLines.push(`- ${usage}: ${module.describe.replace(/\s*\n\s*/g, ' ')}`);
67
+ }
68
+ });
69
+ return joinSections([
70
+ formatSection(agentHelp.headings.conventions, agentHelp.conventions.map(convention => `- ${convention}`)),
71
+ formatWorkflows(agentHelp.workflows),
72
+ formatSection(agentHelp.headings.commands, commandLines),
73
+ formatExitCodes(),
74
+ ]);
75
+ }
76
+ export function getCommandAgentHelp(command, helpText) {
77
+ const jsonOutputSchema = getJsonOutputSchema(command.replace(/^hs /, '').replaceAll(' ', '-'));
78
+ const workflows = agentHelp.workflows.filter(({ steps }) => steps.some(step => `${step.command} `.startsWith(`${command} `)));
79
+ return joinSections([
80
+ helpText.includes('--json') &&
81
+ formatSection(agentHelp.headings.jsonOutput, jsonOutputSchema
82
+ ? [
83
+ agentHelp.jsonOutput.schema,
84
+ ...JSON.stringify(z.toJSONSchema(jsonOutputSchema), null, 2).split('\n'),
85
+ ]
86
+ : [agentHelp.jsonOutput.noSchema]),
87
+ workflows.length > 0 && formatWorkflows(workflows),
88
+ formatExitCodes(),
89
+ ]);
90
+ }
package/lib/commonOpts.js CHANGED
@@ -10,6 +10,7 @@ import { uiCommandReference } from './ui/index.js';
10
10
  import { lib } from '../lang/en.js';
11
11
  import { getTerminalUISupport, UI_COLORS } from './ui/index.js';
12
12
  import SpinniesManager from './ui/SpinniesManager.js';
13
+ import { getCommandAgentHelp } from './agentHelp.js';
13
14
  export function addGlobalOptions(yargs) {
14
15
  yargs.version(false);
15
16
  yargs.option('debug', {
@@ -129,6 +130,9 @@ export async function addCustomHelpOutput(yargs, command, describe) {
129
130
  const fullCommand = `${commandBase.trim()} ${commandString}`;
130
131
  // Format the original help output to be more readable
131
132
  let commandHelp = await yargs.getHelp();
133
+ if (parsedArgv.agentHelp) {
134
+ commandHelp = `${commandHelp}\n\n${getCommandAgentHelp(`${commandBase.trim()} ${commandString.split(' ')[0]}`, commandHelp)}`;
135
+ }
132
136
  ['Options:', 'Commands:', 'Examples:', 'Positionals:'].forEach(header => {
133
137
  commandHelp = commandHelp.replace(header, chalk.bold(header));
134
138
  });
@@ -1,5 +1,5 @@
1
1
  export declare const MCP_SERVER_NAME = "HubSpotDev";
2
- export type McpClientId = 'codex' | 'claude' | 'cursor' | 'devin' | 'gemini' | 'opencode' | 'vscode';
2
+ export type McpClientId = 'codex' | 'claude' | 'cursor' | 'devin' | 'opencode' | 'vscode';
3
3
  type McpClientDetection = {
4
4
  type: 'json' | 'text';
5
5
  pathSegments: string[];
@@ -7,6 +7,7 @@ type McpClientDetection = {
7
7
  export type McpClient = {
8
8
  id: McpClientId;
9
9
  detection: McpClientDetection;
10
+ skillsPathSegments: string[];
10
11
  };
11
12
  export declare const MCP_CLIENTS: McpClient[];
12
13
  export declare function getMcpClientPathSegments(id: McpClientId): string[];
@@ -1,4 +1,5 @@
1
1
  export const MCP_SERVER_NAME = 'HubSpotDev';
2
+ const SHARED_SKILLS_PATH_SEGMENTS = ['.agents', 'skills'];
2
3
  function getVsCodeMcpConfigPathSegments() {
3
4
  if (process.platform === 'darwin') {
4
5
  return ['Library', 'Application Support', 'Code', 'User', 'mcp.json'];
@@ -15,21 +16,17 @@ export const MCP_CLIENTS = [
15
16
  type: 'text',
16
17
  pathSegments: ['.codex', 'config.toml'],
17
18
  },
19
+ skillsPathSegments: SHARED_SKILLS_PATH_SEGMENTS,
18
20
  },
19
21
  {
20
22
  id: 'claude',
21
23
  detection: { type: 'json', pathSegments: ['.claude.json'] },
24
+ skillsPathSegments: ['.claude', 'skills'],
22
25
  },
23
26
  {
24
27
  id: 'cursor',
25
28
  detection: { type: 'json', pathSegments: ['.cursor', 'mcp.json'] },
26
- },
27
- {
28
- id: 'gemini',
29
- detection: {
30
- type: 'json',
31
- pathSegments: ['.gemini', 'settings.json'],
32
- },
29
+ skillsPathSegments: SHARED_SKILLS_PATH_SEGMENTS,
33
30
  },
34
31
  {
35
32
  id: 'vscode',
@@ -37,6 +34,7 @@ export const MCP_CLIENTS = [
37
34
  type: 'json',
38
35
  pathSegments: getVsCodeMcpConfigPathSegments(),
39
36
  },
37
+ skillsPathSegments: SHARED_SKILLS_PATH_SEGMENTS,
40
38
  },
41
39
  {
42
40
  id: 'devin',
@@ -44,6 +42,7 @@ export const MCP_CLIENTS = [
44
42
  type: 'json',
45
43
  pathSegments: ['.codeium', 'windsurf', 'mcp_config.json'],
46
44
  },
45
+ skillsPathSegments: SHARED_SKILLS_PATH_SEGMENTS,
47
46
  },
48
47
  {
49
48
  id: 'opencode',
@@ -51,6 +50,7 @@ export const MCP_CLIENTS = [
51
50
  type: 'json',
52
51
  pathSegments: ['.config', 'opencode', 'config.json'],
53
52
  },
53
+ skillsPathSegments: SHARED_SKILLS_PATH_SEGMENTS,
54
54
  },
55
55
  ];
56
56
  export function getMcpClientPathSegments(id) {
@@ -11,6 +11,7 @@ interface ConfigureMcpServerOptions {
11
11
  targets?: string[];
12
12
  standalone?: boolean;
13
13
  cliVersion?: string;
14
+ skills?: string[];
14
15
  }
15
16
  export declare function configureMcpServer(options: ConfigureMcpServerOptions): Promise<string[]>;
16
17
  export declare function setupVsCode(mcpCommand?: McpCommand): Promise<boolean>;
@@ -18,6 +19,5 @@ export declare function setupClaudeCode(mcpCommand?: McpCommand): Promise<boolea
18
19
  export declare function setupCursor(mcpCommand?: McpCommand): boolean;
19
20
  export declare function setupDevin(mcpCommand?: McpCommand): boolean;
20
21
  export declare function setupCodex(mcpCommand?: McpCommand): Promise<boolean>;
21
- export declare function setupGemini(mcpCommand?: McpCommand): Promise<boolean>;
22
22
  export declare function setupOpenCode(mcpCommand?: McpCommand): Promise<boolean>;
23
23
  export {};
package/lib/mcp/setup.js CHANGED
@@ -5,6 +5,7 @@ import SpinniesManager from '../ui/SpinniesManager.js';
5
5
  import { logError, getErrorMessage } from '../errorHandlers/index.js';
6
6
  import { execAsync } from '../../mcp-server/utils/command.js';
7
7
  import { MCP_CLIENTS, MCP_SERVER_NAME, getMcpClientPathSegments, } from './clients.js';
8
+ import { MCP_SKILLS, SKILLS_SOURCE_DIR, installSkills } from './skills.js';
8
9
  import path from 'path';
9
10
  import os from 'os';
10
11
  import fs from 'fs-extra';
@@ -16,7 +17,6 @@ const cursor = 'cursor';
16
17
  const devin = 'devin';
17
18
  const vscode = 'vscode';
18
19
  const codex = 'codex';
19
- const gemini = 'gemini';
20
20
  const opencode = 'opencode';
21
21
  const OTHER_TOOL = 'other';
22
22
  const MINIMUM_VSCODE_VERSION = '1.99.0';
@@ -25,7 +25,6 @@ const clientLabels = {
25
25
  claude: commands.mcp.setup.claudeCode,
26
26
  cursor: commands.mcp.setup.cursor,
27
27
  devin: commands.mcp.setup.devin,
28
- gemini: commands.mcp.setup.gemini,
29
28
  opencode: commands.mcp.setup.opencode,
30
29
  vscode: commands.mcp.setup.vsCode,
31
30
  };
@@ -42,7 +41,7 @@ const defaultMcpCommand = {
42
41
  };
43
42
  export async function configureMcpServer(options) {
44
43
  try {
45
- const { targets, standalone, cliVersion: cliVersionFlag } = options;
44
+ const { targets, standalone, cliVersion: cliVersionFlag, skills } = options;
46
45
  let derivedTargets = [];
47
46
  if (!targets || targets.length === 0) {
48
47
  const { selectedTargets } = await promptUser({
@@ -90,6 +89,20 @@ export async function configureMcpServer(options) {
90
89
  cliVersion = response.cliVersion;
91
90
  }
92
91
  }
92
+ const configuredTargets = derivedTargets.filter((target) => target !== OTHER_TOOL);
93
+ let selectedSkills = configuredTargets.length > 0 ? skills : [];
94
+ if (selectedSkills === undefined) {
95
+ const response = await promptUser({
96
+ name: 'selectedSkills',
97
+ type: 'checkbox',
98
+ message: commands.mcp.setup.prompts.selectSkills,
99
+ choices: MCP_SKILLS.map(skill => ({
100
+ name: `${skill.name} - ${skill.description}`,
101
+ value: skill.name,
102
+ })),
103
+ });
104
+ selectedSkills = response.selectedSkills;
105
+ }
93
106
  const cliPackage = cliVersion
94
107
  ? `@hubspot/cli@${cliVersion}`
95
108
  : '@hubspot/cli';
@@ -121,16 +134,15 @@ export async function configureMcpServer(options) {
121
134
  if (derivedTargets.includes(codex)) {
122
135
  await runSetupFunction(() => setupCodex(mcpCommand));
123
136
  }
124
- if (derivedTargets.includes(gemini)) {
125
- await runSetupFunction(() => setupGemini(mcpCommand));
126
- }
127
137
  if (derivedTargets.includes(opencode)) {
128
138
  await runSetupFunction(() => setupOpenCode(mcpCommand));
129
139
  }
140
+ if (selectedSkills.length > 0) {
141
+ await runSetupFunction(() => installSkills(configuredTargets, selectedSkills));
142
+ }
130
143
  if (derivedTargets.includes(OTHER_TOOL)) {
131
144
  logOtherToolInstructions(mcpCommand);
132
145
  }
133
- const configuredTargets = derivedTargets.filter(t => t !== OTHER_TOOL);
134
146
  if (configuredTargets.length > 0) {
135
147
  uiLogger.info(commands.mcp.setup.success(configuredTargets));
136
148
  }
@@ -339,35 +351,6 @@ export async function setupCodex(mcpCommand = defaultMcpCommand) {
339
351
  return false;
340
352
  }
341
353
  }
342
- export async function setupGemini(mcpCommand = defaultMcpCommand) {
343
- try {
344
- SpinniesManager.add('geminiSpinner', {
345
- text: commands.mcp.setup.spinners.configuringGemini,
346
- });
347
- try {
348
- await execAsync('gemini --version');
349
- }
350
- catch (e) {
351
- SpinniesManager.fail('geminiSpinner', {
352
- text: commands.mcp.setup.spinners.geminiNotFound,
353
- });
354
- return false;
355
- }
356
- const mcpCommandWithAgent = buildCommandWithAgentString(mcpCommand, gemini);
357
- await execAsync(`gemini mcp add -s user${buildEnvFlagString(mcpCommand)} "${mcpServerName}" ${mcpCommandWithAgent.command} ${mcpCommandWithAgent.args.join(' ')}`);
358
- SpinniesManager.succeed('geminiSpinner', {
359
- text: commands.mcp.setup.spinners.configuredGemini,
360
- });
361
- return true;
362
- }
363
- catch (error) {
364
- SpinniesManager.fail('geminiSpinner', {
365
- text: commands.mcp.setup.spinners.geminiInstallFailed,
366
- });
367
- logError(error);
368
- return false;
369
- }
370
- }
371
354
  export async function setupOpenCode(mcpCommand = defaultMcpCommand) {
372
355
  try {
373
356
  SpinniesManager.add('openCodeSpinner', {
@@ -419,6 +402,8 @@ function logOtherToolInstructions(mcpCommand) {
419
402
  .join('\n');
420
403
  uiLogger.log(indented);
421
404
  uiLogger.log('');
405
+ uiLogger.log(otherInstructions.skillsNote(SKILLS_SOURCE_DIR));
406
+ uiLogger.log('');
422
407
  }
423
408
  function buildCommandWithAgentString(mcpCommand, agent) {
424
409
  const mcpCommandCopy = structuredClone(mcpCommand);
@@ -0,0 +1,8 @@
1
+ import { McpClientId } from './clients.js';
2
+ export declare const SKILLS_SOURCE_DIR: string;
3
+ export declare const MCP_SKILLS: {
4
+ name: string;
5
+ description: string;
6
+ }[];
7
+ export declare const MCP_SKILL_NAMES: string[];
8
+ export declare function installSkills(targets: McpClientId[], skillNames: string[]): boolean;
@@ -0,0 +1,64 @@
1
+ import path from 'path';
2
+ import os from 'os';
3
+ import fs from 'fs-extra';
4
+ import { fileURLToPath } from 'url';
5
+ import { commands } from '../../lang/en.js';
6
+ import SpinniesManager from '../ui/SpinniesManager.js';
7
+ import { logError } from '../errorHandlers/index.js';
8
+ import { MCP_CLIENTS } from './clients.js';
9
+ const __filename = fileURLToPath(import.meta.url);
10
+ const __dirname = path.dirname(__filename);
11
+ export const SKILLS_SOURCE_DIR = path.join(__dirname, '..', '..', 'mcp-server', 'skills');
12
+ export const MCP_SKILLS = [
13
+ {
14
+ name: 'hubspot-new-app',
15
+ description: commands.mcp.setup.skillDescriptions.newApp,
16
+ },
17
+ {
18
+ name: 'hubspot-fix-build',
19
+ description: commands.mcp.setup.skillDescriptions.fixBuild,
20
+ },
21
+ ];
22
+ export const MCP_SKILL_NAMES = MCP_SKILLS.map(skill => skill.name);
23
+ const INSTALLED_SKILL_MARKER = '.installed-by-hubspot-cli';
24
+ function getInstalledSkillNames(targetDir) {
25
+ if (!fs.existsSync(targetDir)) {
26
+ return [];
27
+ }
28
+ return fs
29
+ .readdirSync(targetDir, { withFileTypes: true })
30
+ .filter(entry => entry.isDirectory())
31
+ .map(entry => entry.name)
32
+ .filter(name => fs.existsSync(path.join(targetDir, name, INSTALLED_SKILL_MARKER)));
33
+ }
34
+ function installSkillsInDir(targetDir, skillNames) {
35
+ new Set([...getInstalledSkillNames(targetDir), ...skillNames]).forEach(name => fs.rmSync(path.join(targetDir, name), { recursive: true, force: true }));
36
+ skillNames.forEach(skillName => {
37
+ const destination = path.join(targetDir, skillName);
38
+ fs.copySync(path.join(SKILLS_SOURCE_DIR, skillName), destination);
39
+ fs.writeFileSync(path.join(destination, INSTALLED_SKILL_MARKER), '');
40
+ });
41
+ }
42
+ export function installSkills(targets, skillNames) {
43
+ const skillsToInstall = MCP_SKILL_NAMES.filter(skillName => skillNames.includes(skillName));
44
+ const targetDirs = [
45
+ ...new Set(MCP_CLIENTS.filter(client => targets.includes(client.id)).map(client => path.join(os.homedir(), ...client.skillsPathSegments))),
46
+ ];
47
+ SpinniesManager.add('mcpSkills', {
48
+ text: commands.mcp.setup.spinners.installingSkills,
49
+ });
50
+ try {
51
+ targetDirs.forEach(targetDir => installSkillsInDir(targetDir, skillsToInstall));
52
+ SpinniesManager.succeed('mcpSkills', {
53
+ text: commands.mcp.setup.spinners.installedSkills(skillsToInstall, targetDirs),
54
+ });
55
+ return true;
56
+ }
57
+ catch (error) {
58
+ SpinniesManager.fail('mcpSkills', {
59
+ text: commands.mcp.setup.spinners.failedToInstallSkills,
60
+ });
61
+ logError(error);
62
+ return false;
63
+ }
64
+ }
@@ -22,7 +22,7 @@ export async function importDataTestAccountSelectPrompt(parentAccountId) {
22
22
  return promptUser({
23
23
  type: 'list',
24
24
  name: 'selectedAccountId',
25
- message: '[--account] Select a developer test account:',
25
+ message: lib.prompts.importDataTestAccountSelectPrompt.message,
26
26
  choices: childAccounts,
27
27
  });
28
28
  }
@@ -4,4 +4,5 @@ import { CommonArgs } from '../../types/Yargs.js';
4
4
  export type WrappedHandlerOptions = {
5
5
  jsonOutputSchema?: z.ZodType;
6
6
  };
7
+ export declare function getJsonOutputSchema(trackingName: string): z.ZodType | undefined;
7
8
  export declare function makeWrappedYargsHandler<T extends CommonArgs>(trackingName: string, handler: (args: ArgumentsCamelCase<T>) => Promise<void>, options?: WrappedHandlerOptions): (args: ArgumentsCamelCase<T>) => Promise<void>;
@@ -14,6 +14,10 @@ import { isPromptExitError } from '../errors/PromptExitError.js';
14
14
  import { debugError } from '../errorHandlers/index.js';
15
15
  import { MAX_LOG_FILES } from '../constants.js';
16
16
  const HANDLER_LOG_DIR = path.join(os.homedir(), '.hscli', 'logs', 'cli');
17
+ const jsonOutputSchemas = new Map();
18
+ export function getJsonOutputSchema(trackingName) {
19
+ return jsonOutputSchemas.get(trackingName);
20
+ }
17
21
  function logUsageTrackingMessage(isJsonOutput) {
18
22
  if (isJsonOutput) {
19
23
  return;
@@ -119,6 +123,9 @@ function createLogFileWriter(trackingName, isJsonOutput) {
119
123
  return { writeLogFile, writeFailureLogFile };
120
124
  }
121
125
  export function makeWrappedYargsHandler(trackingName, handler, options) {
126
+ if (options?.jsonOutputSchema) {
127
+ jsonOutputSchemas.set(trackingName, options.jsonOutputSchema);
128
+ }
122
129
  return async (args) => {
123
130
  const wrappedHandlerArgs = args;
124
131
  const isJsonOutput = Boolean(wrappedHandlerArgs.json || wrappedHandlerArgs.formatOutputAsJson);
@@ -0,0 +1,61 @@
1
+ ---
2
+ name: hubspot-fix-build
3
+ description: Diagnose and fix a failed HubSpot project build with the HubSpot CLI MCP tools. Use when a HubSpot project build failed, an `hs project upload` or `upload-project` failed, or a project deploy is blocked by a build error. Do not use it for other builds, such as npm, CI, or local compiler builds. Also use when `upload-project` returns a build failure. The skill finds the cause, fixes the project files, and asks before it uploads again.
4
+ disable-model-invocation: false
5
+ allowed-tools: Read, Grep, Glob
6
+ argument-hint: '[project-path] [build-id]'
7
+ ---
8
+
9
+ # Fix a failed HubSpot project build
10
+
11
+ Use this skill to find why a build failed and to fix it. Work from the error text. Do not guess a cause.
12
+
13
+ The tools in this skill come from the HubSpot CLI MCP server, which `hs mcp setup` adds as `HubSpotDev`. If more than one server has a tool with the same name, use the one from `HubSpotDev`.
14
+
15
+ ## Task
16
+
17
+ When this skill is invoked:
18
+
19
+ ### 1. Locate the project
20
+
21
+ `get-build-status` and `get-build-logs` need the project path, even when you have a build ID. Find the project before you look at any build.
22
+
23
+ 1. If the user passed a project path as an argument, use it.
24
+ 2. Otherwise call `find-projects`. If it finds several projects, ask the user which one to use.
25
+ 3. If the user passed a build ID, keep it for step 2. A build ID does not tell you which project it belongs to.
26
+
27
+ ### 2. Find the failed build
28
+
29
+ 1. Call `get-build-status` with no `buildId`. It shows the recent builds.
30
+ 2. If the user named a build, use that build. Otherwise use the latest build with a failure status.
31
+ 3. Call `get-build-status` again with that `buildId`. Read `buildErrorMessage` and the failed subbuilds.
32
+
33
+ If the latest build succeeded, tell the user. Ask which build they mean.
34
+
35
+ ### 3. Read the logs only if needed
36
+
37
+ The status output often has enough detail. Call `get-build-logs` in these cases:
38
+
39
+ - The error message is vague or empty.
40
+ - The user asks about warnings.
41
+ - The subbuild failure does not name a file or a field.
42
+
43
+ Start with `logLevel` set to `ERROR`. Use `WARN` for warnings. Use `ALL` as the last choice.
44
+
45
+ ### 4. Fix the cause
46
+
47
+ 1. Name the cause to the user in one or two sentences. Quote the error text.
48
+ 2. If the error points to a `*-hsmeta.json` file, read `platformVersion` in `hsproject.json`. Call `get-feature-config-schema` with that version and the `type` field from the file. Fix the file with values the schema allows.
49
+ 3. For other errors, fix the named file.
50
+ 4. Do not change `distribution` or `auth` in `app-hsmeta.json` to clear an error. These values cannot change after the first upload. Tell the user and ask what they want to do.
51
+ 5. If you cannot find the cause, show the error text to the user without changes. Say which files and logs you read.
52
+
53
+ ### 5. Validate
54
+
55
+ Call `validate-project`. Fix each error and call it again. Repeat until it passes.
56
+
57
+ ### 6. Ask before you upload
58
+
59
+ Say what you changed. Ask the user whether to upload again. If they say yes, call `upload-project`. If the project uses profiles, ask the user which profile to use. Never choose a profile yourself.
60
+
61
+ After the upload, call `get-build-status` to read the status of the new build. If it fails again, go back to step 2. If the same error repeats after two fixes, stop and show the user the error and what you tried.
@@ -0,0 +1,84 @@
1
+ ---
2
+ name: hubspot-new-app
3
+ description: Plan and create a HubSpot developer-platform app project with the HubSpot CLI MCP tools. Use when the user wants to build, start, or scaffold a HubSpot developer-platform app project (an `hsproject.json` project). Also use when the user wants to add features such as cards, webhooks, workflow actions, or app functions to a project. Also use when the user has only a rough idea and needs help to choose features, distribution, and auth type. The skill ends with a local project that passes validation. It does not upload or deploy.
4
+ disable-model-invocation: false
5
+ allowed-tools: Read, Grep, Glob
6
+ argument-hint: '[app-idea]'
7
+ ---
8
+
9
+ # Plan and create a HubSpot app project
10
+
11
+ Use this skill to turn an idea into a local HubSpot project that passes validation. The first upload fixes two choices: distribution and auth type. A wrong choice means a new project, so plan before you scaffold.
12
+
13
+ Never choose distribution, auth type, project name, or destination for the user. Ask.
14
+
15
+ The tools in this skill come from the HubSpot CLI MCP server, which `hs mcp setup` adds as `HubSpotDev`. If more than one server has a tool with the same name, use the one from `HubSpotDev`.
16
+
17
+ ## Task
18
+
19
+ When this skill is invoked:
20
+
21
+ ### 1. Find the starting point
22
+
23
+ 1. If the user wants to add features to an existing project, call `find-projects` on the working directory, then skip to step 4 and use `add-feature-to-project`. If the user wants a new app, do not call `find-projects`. If you cannot tell which one the user wants, ask.
24
+ 2. If any tool reports "No account ID found", or no account is authenticated, call `auth-account`. Tell the user that a browser tab opens and that they must click "Connect to CLI". Then retry the blocked step.
25
+ 3. If the user wants a safe place to test, offer `create-test-account`. Follow that tool's own workflow: look for a test account config file, show it to the user, and ask before you use it. If there is no file, ask for the account name and the tier for each hub.
26
+
27
+ ### 2. Plan
28
+
29
+ If the user already stated what the app does, the features, the distribution, and the auth type, skip this step.
30
+
31
+ 1. If the user passed an app idea as an argument (for example `/hubspot-new-app a card that shows open tickets`), use it. Otherwise ask one question: what must the app do for its users?
32
+ 2. Call `search-docs` for that goal. Call `fetch-doc` on the best results. Choose features from the docs. The valid feature values are:
33
+
34
+ ```
35
+ card, settings, app-function, app-function-endpoint, webhooks,
36
+ workflow-action, workflow-action-tool, app-object, app-event,
37
+ scim, page, crm-bulk-action
38
+ ```
39
+
40
+ 3. Keep these features apart:
41
+ - `app-function` is a private serverless function inside the app.
42
+ - `app-function-endpoint` is an app serverless function with a public endpoint.
43
+ - `workflow-action-tool` is an agent tool.
44
+ - Do not confuse any of them with a CMS serverless function. That is a different product.
45
+ 4. If a fetched doc has a "Supported products" section, tell the user the required product and tier in plain words. For example: "This feature requires Content Hub Enterprise." Do this before you scaffold. If no fetched doc has that section, do not state a tier.
46
+ 5. Ask for the distribution:
47
+ - `private`: the app is not listed on the HubSpot marketplace.
48
+ - `marketplace`: the app is listed on the HubSpot marketplace.
49
+ 6. Ask for the auth type. `oauth` works for both distributions. `static` works only with `private` distribution.
50
+ 7. Ask for the project name. Ask for the destination directory. The destination becomes the project folder itself, so use the exact path that the user gives. Do not use the current directory unless the user says so.
51
+ 8. After the user answers, show the full plan: name, destination, project base (`app` or `empty`), distribution, auth type, and features.
52
+ 9. Ask "Create this project?" Say that distribution and auth type cannot change after the first upload. Wait for a yes in a separate reply. Answers to your questions are not a yes. Do not call `create-project` or `add-feature-to-project` before the yes.
53
+
54
+ ### 3. Create a new project
55
+
56
+ Call `create-project` with every value from the plan:
57
+
58
+ - `name`, `destination`
59
+ - `projectBase`: `app` for a project with an app, `empty` for a project without one
60
+ - `distribution` and `auth` (for base `app` only)
61
+ - `features`
62
+
63
+ If the tool answers with a question, ask the user. Do not guess a value.
64
+
65
+ ### 4. Add features to an existing project
66
+
67
+ Call `add-feature-to-project` with `absoluteProjectPath` and `features`.
68
+
69
+ - If the project has no app, set `addApp` to `true`. A project needs an app before it can hold a feature.
70
+ - When `addApp` is `true`, pass `distribution` and `auth`. Ask the user for them, as in step 2. Otherwise omit them.
71
+
72
+ ### 5. Configure and validate
73
+
74
+ 1. Open `hsproject.json` and read `platformVersion`.
75
+ 2. Before you edit any `*-hsmeta.json` file, call `get-feature-config-schema` with that `platformVersion` and the `type` field from the file. Use only the values the schema allows.
76
+ 3. Edit the file.
77
+ 4. If a feature reads or writes CRM data, add the scopes it needs to `requiredScopes` in `app-hsmeta.json`. The schema does not list scope names, so find the exact names with `search-docs` and `fetch-doc`.
78
+ 5. Call `validate-project`. Fix each error and call it again. Repeat until it passes. If you cannot fix an error, show the error text to the user without changes.
79
+
80
+ ### 6. Finish
81
+
82
+ Tell the user which files you created and which features the project has. Tell them that the project is ready to upload, and that the first upload makes distribution and auth type permanent.
83
+
84
+ Do not call `upload-project` in this skill. Stop here. If the user asks to upload later, treat it as a new request. If that build fails, use the `hubspot-fix-build` skill.
@@ -6,11 +6,14 @@ import { Tool } from '../../Tool.js';
6
6
  declare const inputSchemaZodObject: z.ZodObject<{
7
7
  docUrl: z.ZodString;
8
8
  absoluteCurrentWorkingDirectory: z.ZodString;
9
+ offset: z.ZodDefault<z.ZodNumber>;
10
+ maxCharacters: z.ZodDefault<z.ZodNumber>;
11
+ fullDocument: z.ZodDefault<z.ZodBoolean>;
9
12
  }, z.z.core.$strip>;
10
13
  type InputSchemaType = z.infer<typeof inputSchemaZodObject>;
11
14
  export declare class DocFetchTool extends Tool<InputSchemaType> {
12
15
  constructor(mcpServer: McpServer, logger: McpLogger);
13
- handler({ docUrl, absoluteCurrentWorkingDirectory, }: InputSchemaType): Promise<McpToolResponse>;
16
+ handler({ docUrl, absoluteCurrentWorkingDirectory, offset, maxCharacters, fullDocument, }: InputSchemaType): Promise<McpToolResponse>;
14
17
  register(): RegisteredTool;
15
18
  }
16
19
  export {};
@@ -1,14 +1,40 @@
1
1
  import z from 'zod';
2
2
  import { Tool } from '../../Tool.js';
3
- import { formatTextContents } from '../../utils/content.js';
3
+ import { formatErrorTextContents, formatTextContents, } from '../../utils/content.js';
4
4
  import { absoluteCurrentWorkingDirectory, docUrl } from './constants.js';
5
5
  import { http } from '@hubspot/local-dev-lib/http/unauthed';
6
6
  import { isHubSpotHttpError } from '@hubspot/local-dev-lib/errors/index';
7
7
  import { setupHubSpotConfig } from '../../utils/config.js';
8
8
  import { getErrorMessage } from '../../../lib/errorHandlers/index.js';
9
+ const offset = z
10
+ .number()
11
+ .int()
12
+ .min(0)
13
+ .default(0)
14
+ .describe('The character position to start reading from. When more content is available, the response gives the offset for the next part.');
15
+ const maxCharacters = z
16
+ .number()
17
+ .int()
18
+ .min(1000)
19
+ .max(40000)
20
+ .default(20000)
21
+ .describe('The maximum number of characters to return.');
22
+ const fullDocument = z
23
+ .boolean()
24
+ .default(false)
25
+ .describe('Set to true to return the whole document with no character limit. This ignores offset and maxCharacters. Set this only when the user asks for the whole page.');
9
26
  const inputSchema = {
10
27
  docUrl,
11
28
  absoluteCurrentWorkingDirectory,
29
+ offset,
30
+ maxCharacters,
31
+ fullDocument,
32
+ };
33
+ const outputSchema = {
34
+ text: z.string(),
35
+ offset: z.number(),
36
+ nextOffset: z.number().optional(),
37
+ totalCharacters: z.number(),
12
38
  };
13
39
  // eslint-disable-next-line @typescript-eslint/no-unused-vars
14
40
  const inputSchemaZodObject = z.object({
@@ -19,7 +45,7 @@ export class DocFetchTool extends Tool {
19
45
  constructor(mcpServer, logger) {
20
46
  super(mcpServer, logger, toolName);
21
47
  }
22
- async handler({ docUrl, absoluteCurrentWorkingDirectory, }) {
48
+ async handler({ docUrl, absoluteCurrentWorkingDirectory, offset, maxCharacters, fullDocument, }) {
23
49
  setupHubSpotConfig(absoluteCurrentWorkingDirectory);
24
50
  try {
25
51
  // Append .md extension to the URL
@@ -29,9 +55,27 @@ export class DocFetchTool extends Tool {
29
55
  });
30
56
  const content = response.data;
31
57
  if (!content || content.trim().length === 0) {
32
- return formatTextContents('Document is empty or contains no content.');
58
+ return formatErrorTextContents('Document is empty or contains no content.');
59
+ }
60
+ if (!fullDocument && offset >= content.length) {
61
+ return formatErrorTextContents(`Offset ${offset} is past the end of the document, which has ${content.length} characters.`);
33
62
  }
34
- return formatTextContents(content);
63
+ const start = fullDocument ? 0 : offset;
64
+ const chunkEnd = fullDocument
65
+ ? content.length
66
+ : Math.min(offset + maxCharacters, content.length);
67
+ const nextOffset = chunkEnd < content.length ? chunkEnd : undefined;
68
+ const text = content.slice(start, chunkEnd);
69
+ const result = await formatTextContents(text, nextOffset === undefined
70
+ ? undefined
71
+ : `This is part of the document (characters ${start} to ${chunkEnd} of ${content.length}). More content is available. To read the next part, call ${toolName} again with the same arguments and offset set to ${nextOffset}.`);
72
+ result.structuredContent = {
73
+ text,
74
+ offset: start,
75
+ nextOffset,
76
+ totalCharacters: content.length,
77
+ };
78
+ return result;
35
79
  }
36
80
  catch (error) {
37
81
  this.logger.debug(toolName, {
@@ -39,17 +83,18 @@ export class DocFetchTool extends Tool {
39
83
  error: error instanceof Error ? error.message : String(error),
40
84
  });
41
85
  if (isHubSpotHttpError(error)) {
42
- return formatTextContents(error.toString());
86
+ return formatErrorTextContents(error.toString());
43
87
  }
44
88
  const errorMessage = `Error fetching documentation: ${getErrorMessage(error)}`;
45
- return formatTextContents(errorMessage);
89
+ return formatErrorTextContents(errorMessage);
46
90
  }
47
91
  }
48
92
  register() {
49
93
  return this.mcpServer.registerTool(toolName, {
50
94
  title: 'Fetch HubSpot Developer Documentation (single file)',
51
- description: 'Always use this immediately after `search-docs` and before creating a plan, writing code, or answering technical questions. This tool retrieves the full, authoritative content of a HubSpot Developer Documentation page from its URL, ensuring responses are accurate, up-to-date, and grounded in the official docs. Some pages include a "Supported products" section (a `<SupportedProducts .../>` tag) listing the products and subscription tiers a feature requires. Read it to tell the user whether a feature is available on their plan, stated plainly (for example "requires Content Hub Enterprise") rather than by quoting raw spec fields.',
95
+ description: 'Always use this immediately after `search-docs` and before creating a plan, writing code, or answering technical questions. This tool retrieves the authoritative content of a HubSpot Developer Documentation page from its URL, ensuring responses are accurate, up-to-date, and grounded in the official docs. Long pages return in parts. The response says when more content is available and how to fetch the next part. Some pages include a "Supported products" section (a `<SupportedProducts .../>` tag) listing the products and subscription tiers a feature requires. Read it to tell the user whether a feature is available on their plan, stated plainly (for example "requires Content Hub Enterprise") rather than by quoting raw spec fields.',
52
96
  inputSchema,
97
+ outputSchema,
53
98
  annotations: {
54
99
  readOnlyHint: true,
55
100
  openWorldHint: true,
@@ -30,7 +30,10 @@ export class FindProjectsTool extends Tool {
30
30
  const selected = await elicitSelection(this.mcpServer, this.logger, {
31
31
  message: 'Select the HubSpot project to use.',
32
32
  title: 'HubSpot project',
33
- options: projectDirs.map(dir => ({ value: dir, label: dir })),
33
+ options: projectDirs.map(dir => ({
34
+ value: dir,
35
+ label: path.relative(absoluteDirectory, dir) || '.',
36
+ })),
34
37
  });
35
38
  if (selected) {
36
39
  return formatTextContents(`Selected project: ${selected}`);
@@ -11,8 +11,8 @@ declare const inputSchemaZodObject: z.ZodObject<{
11
11
  logLevel: z.ZodOptional<z.ZodEnum<{
12
12
  ERROR: "ERROR";
13
13
  WARN: "WARN";
14
- INFO: "INFO";
15
14
  ALL: "ALL";
15
+ INFO: "INFO";
16
16
  }>>;
17
17
  }, z.core.$strip>;
18
18
  export type GetBuildLogsInputSchema = z.infer<typeof inputSchemaZodObject>;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@hubspot/cli",
3
- "version": "8.16.0-beta.2",
3
+ "version": "8.17.0-beta.0",
4
4
  "description": "The official CLI for developing on HubSpot",
5
5
  "license": "Apache-2.0",
6
6
  "repository": "https://github.com/HubSpot/hubspot-cli",
@@ -10,11 +10,11 @@
10
10
  "!**/__tests__/**"
11
11
  ],
12
12
  "dependencies": {
13
- "@hubspot/local-dev-lib": "5.12.0",
14
- "@hubspot/project-parsing-lib": "0.23.4",
13
+ "@hubspot/local-dev-lib": "5.13.0",
14
+ "@hubspot/project-parsing-lib": "0.23.6",
15
15
  "@hubspot/ui-extensions-dev-server": "2.2.2",
16
16
  "@inquirer/prompts": "7.10.1",
17
- "@modelcontextprotocol/sdk": "1.30.0",
17
+ "@modelcontextprotocol/sdk": "1.32.1",
18
18
  "archiver": "7.0.1",
19
19
  "chalk": "5.6.2",
20
20
  "chokidar": "3.6.0",
@@ -37,7 +37,7 @@
37
37
  "table": "6.9.0",
38
38
  "tmp": "0.2.7",
39
39
  "update-notifier": "7.3.1",
40
- "ws": "8.21.3",
40
+ "ws": "8.22.0",
41
41
  "yargs": "17.7.3",
42
42
  "yargs-parser": "21.1.1",
43
43
  "zod": "^4.4.3"