@adkit/cli 1.13.9 → 1.13.11

package/dist/cli.js

@@ -1233,16 +1233,18 @@ async function disconnectAccount(client, args, _flags) {
 }
 async function updateAccount(client, args, flags) {
   const id = requireArg(args, 0, "account-id", 'Run: adkit manage meta accounts <account-id> update --beneficiary "Company Name"');
-  validateFlags(flags, ["beneficiary", "payor", "default-page", "default-pixel"], "manage meta accounts update");
+  validateFlags(flags, ["beneficiary", "payor", "default-page", "default-instagram-user", "default-pixel"], "manage meta accounts update");
   const beneficiary = typeof flags.beneficiary === "string" ? flags.beneficiary : void 0;
   const payor = typeof flags.payor === "string" ? flags.payor : void 0;
   const defaultPageId = typeof flags["default-page"] === "string" ? flags["default-page"] : void 0;
+  const defaultInstagramUserId = typeof flags["default-instagram-user"] === "string" ? flags["default-instagram-user"] : void 0;
   const defaultPixelId = typeof flags["default-pixel"] === "string" ? flags["default-pixel"] : void 0;
   const body = {};
   if (beneficiary) body.dsaDefaults = { beneficiary, payor };
   if (defaultPageId) body.defaultPageId = defaultPageId;
+  if (defaultInstagramUserId) body.defaultInstagramUserId = defaultInstagramUserId;
   if (defaultPixelId) body.defaultPixelId = defaultPixelId;
-  if (!beneficiary && !defaultPageId && !defaultPixelId) throw new CliError("MISSING_FLAG", "Nothing to update", "Pass --beneficiary, --default-page, or --default-pixel");
+  if (!beneficiary && !defaultPageId && !defaultInstagramUserId && !defaultPixelId) throw new CliError("MISSING_FLAG", "Nothing to update", "Pass --beneficiary, --default-page, --default-instagram-user, or --default-pixel");
   return client.patch(`/manage/meta/accounts/${id}`, body);
 }
 async function listPages(client, args, _flags) {
@@ -1254,12 +1256,13 @@ async function listPixels(client, args, _flags) {
   return client.get(`/manage/meta/accounts/${id}/pixels`);
 }
 async function listMetaLeadForms(client, _args, flags) {
-  validateFlags(flags, ["page", "fields", "raw"], "manage meta lead-forms list");
+  validateFlags(flags, ["account", "page", "fields", "raw"], "manage meta lead-forms list");
+  const accountId = typeof flags.account === "string" ? flags.account : void 0;
   const pageId = typeof flags.page === "string" ? flags.page : void 0;
   if (!pageId) throw new CliError("MISSING_FLAG", "Missing required flag: `--page`", "Run: adkit manage meta lead-forms list --page <page-id>");
   const fields = typeof flags.fields === "string" ? flags.fields : void 0;
   const raw = flags.raw === true ? "true" : void 0;
-  const qs = queryString({ pageId, fields, raw });
+  const qs = queryString({ accountId, pageId, fields, raw });
   return client.get(`/manage/meta/lead-forms${qs}`);
 }
 function buildCampaignPayload(flags) {
@@ -4512,6 +4515,80 @@ function isFeedbackResponse(value) {
   return value !== null && typeof value === "object";
 }
 
+// src/commands/help.ts
+var HELP_SEARCH_USAGE = `Usage: adkit help --search "<query>" [--json]
+
+Search AdKit help by keyword and return the closest CLI help commands.
+
+Options:
+  --search <query>   Capability or topic to find, such as "keyword planner"
+  --json             Output structured results with CLI command paths
+
+Example:
+  adkit help --search "keyword planner"`;
+var CLI_HELP_OVERRIDES = {
+  "manage media request_upload_url": {
+    path: "manage meta media upload",
+    description: "The CLI uploads local files directly. Open a platform media command and pass --file, --url, or --adkit-media."
+  },
+  "manage google keywords create": { path: "manage google keywords add", description: "" },
+  "manage google keywords delete": { path: "manage google keywords remove", description: "" },
+  "manage google keywords list-negatives": { path: "manage google keywords negatives list", description: "" },
+  "manage google keywords add-negative": { path: "manage google keywords negatives add", description: "" },
+  "manage google keywords remove-negative": { path: "manage google keywords negatives remove", description: "" },
+  "studio ads generate": { path: "studio generate", description: "" },
+  "studio ads media_list": { path: "studio media list", description: "" },
+  "studio ads share": { path: "studio share", description: "" },
+  "studio media request_upload_url": {
+    path: "studio media upload",
+    description: "The CLI uploads local Studio media directly from a file."
+  }
+};
+async function searchHelpTopics(client, query) {
+  return client.get(`/manage/help/search?q=${encodeURIComponent(query)}`);
+}
+function helpSearchToCliResponse(data) {
+  if (!isHelpSearchResponse(data)) return data;
+  const results = [];
+  const seenPaths = /* @__PURE__ */ new Set();
+  for (const result of data.results) {
+    const cliResult = serverHelpPointerToCli(result);
+    if (seenPaths.has(cliResult.path)) continue;
+    seenPaths.add(cliResult.path);
+    results.push(cliResult);
+  }
+  return {
+    results,
+    note: "Each result.path is a CLI command path. Run: adkit <path> --help"
+  };
+}
+function formatHelpSearch(data) {
+  const cliData = helpSearchToCliResponse(data);
+  if (!isHelpSearchResponse(cliData) || cliData.results.length === 0) return "No help topics matched. Drill down instead: adkit manage --help, adkit library --help, or adkit studio --help.";
+  const lines = [];
+  for (const result of cliData.results) {
+    lines.push(`adkit ${result.path} --help`);
+    if (result.description) lines.push(`  ${result.description}`);
+  }
+  lines.push("", "Each command above opens the matching CLI help.");
+  return lines.join("\n");
+}
+function serverHelpPointerToCli(result) {
+  const override = CLI_HELP_OVERRIDES[result.path];
+  if (override) return { path: override.path, description: override.description || result.description };
+  const negativeListPrefix = "manage google negative-list ";
+  if (result.path.startsWith(negativeListPrefix)) {
+    const action = result.path.slice(negativeListPrefix.length);
+    return { path: `manage google keywords negative-lists ${action}`, description: result.description };
+  }
+  if (result.path.startsWith("manage platform-api-request ")) return { path: "manage platform-api-requests", description: result.description };
+  return result;
+}
+function isHelpSearchResponse(value) {
+  if (!value || typeof value !== "object" || !("results" in value)) return false;
+  return Array.isArray(value.results);
+}
+
 // src/cli.ts
 var require2 = createRequire(import.meta.url);
 var CLI_VERSION = require2("../package.json").version;
@@ -4525,6 +4602,7 @@ Usage: adkit <command> [options]
 
 Commands:
   status        Show project context and connected accounts
+  help          Search help topics by keyword (--search "<query>")
   feedback      Report feedback or bugs to AdKit
   setup         Set up AdKit (opens browser)
   library       Browse ads and advertisers
@@ -5074,16 +5152,17 @@ Examples:
   adkit manage meta creatives delete cr_abc`;
 var LEAD_FORM_HELP = `adkit manage meta lead-forms \u2014 Meta Instant Forms
 
-  list                Temporarily unavailable pending Meta pages_manage_ads approval
+  list                List existing Instant Forms owned by a Facebook Page
 
 Flags:
+  --account <id>      Connected Meta ad account (required when multiple are connected)
   --page <id>         Facebook Page ID (required)
-  --fields <list>     id,name,status,createdTime
+  --fields <list>     platformId,name,status,createdTime
   --raw               Return raw Meta API fields
 
 Notes:
-  For now, copy the form ID from https://business.facebook.com/latest/instant_forms/forms/
-  and pass it as --lead-form when creating lead ads.
+  Existing Meta logins must reconnect once after this update and accept all permissions.
+  The Facebook Page must accept Meta Lead Generation Terms before lead ads can publish.
   In product/help grouping, lead forms are supporting Meta assets; the command entity stays lead-forms.
 
 Examples:
@@ -5879,7 +5958,7 @@ var HELP = {
   list                List connected ad accounts
   connect <id>        Connect an ad account
   disconnect <id>     Disconnect an ad account
-  <id> update         Update account settings (DSA defaults, default page/pixel)
+  <id> update         Update account settings (DSA defaults and resource IDs)
   <id> pages          List Facebook Pages for an account
   <id> pixels         List Meta Pixels for an account
 
@@ -5887,12 +5966,16 @@ Update flags:
   --beneficiary <name>   DSA: person or organization being promoted (required for EU ads)
   --payor <name>         DSA: person or organization paying (defaults to beneficiary)
   --default-page <id>    Default Facebook Page for ad creation
+  --default-instagram-user <id>  Saved account-level Instagram user ID
   --default-pixel <id>   Default Meta Pixel for conversion tracking
 
+Don't know the Instagram user ID? Read an existing Meta ad that uses the profile and copy creative.instagramUserId from its details.
+
 Examples:
   adkit manage meta accounts list
   adkit manage meta accounts connect act_123456789
   adkit manage meta accounts act_123456789 update --beneficiary "Acme Inc"
+  adkit manage meta accounts act_123456789 update --default-instagram-user 17841400000000000
   adkit manage meta accounts act_123456789 pages
   adkit manage meta accounts disconnect act_123456789`.trim(),
   "meta campaigns": CAMPAIGN_HELP,
@@ -7533,6 +7616,23 @@ async function main() {
       await submitFeedback({ args: args.slice(1), client, flags, json: wantsJson(flags) });
       return;
     }
+    if (args[0] === "help") {
+      if (flags.help) {
+        printHelp(HELP_SEARCH_USAGE);
+        return;
+      }
+      const query = typeof flags.search === "string" ? flags.search.trim() : "";
+      if (!query) throw new CliError("MISSING_FLAG", "Missing required flag: `--search`", 'Run: adkit help --search "<query>"');
+      const client = requireClient(flags);
+      const data = await searchHelpTopics(client, query);
+      const cliData = helpSearchToCliResponse(data);
+      if (wantsJson(flags)) printResult(cliData, flags);
+      else {
+        const output = formatHelpSearch(data);
+        console.log(output);
+      }
+      return;
+    }
     if (args[0] === "manage") {
       const manageTarget = args[1];
       if (flags.help && !manageTarget) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adkit/cli",
-  "version": "1.13.9",
+  "version": "1.13.11",
   "description": "The Ads CLI for AI agents — manage Meta & Google ad campaigns, browse the ad library, and generate creatives from your terminal.",
   "keywords": [
     "ads cli",