@adkit/cli 1.12.4 → 1.12.9

package/dist/cli.js

@@ -1,12 +1,5 @@
 #!/usr/bin/env node
 
-// ../shared/dist/utils/service-status.js
-var ADKIT_STATUS_NOTICE = null;
-function getAdKitStatusNotice() {
-  const statusNotice = ADKIT_STATUS_NOTICE?.trim();
-  return statusNotice ? `Active AdKit status notice: ${statusNotice}` : void 0;
-}
-
 // src/config.ts
 import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
 import { join } from "node:path";
@@ -72,6 +65,15 @@ function readLegacyProjectApiKey(config, selectedProject) {
   return config.projects?.[selectedProject]?.apiKey ?? null;
 }
 
+// ../shared/dist/errors.js
+function describeRetryDelay(retryAfterSeconds) {
+  if (!retryAfterSeconds || retryAfterSeconds <= 300)
+    return "in a few minutes";
+  if (retryAfterSeconds <= 3600)
+    return "within the hour";
+  return "in a few hours";
+}
+
 // src/errors.ts
 var CliError = class extends Error {
   code;
@@ -86,6 +88,19 @@ var CliError = class extends Error {
 };
 
 // src/client.ts
+var noticePrinted = false;
+function printServerNotice(response) {
+  if (noticePrinted) return;
+  const encoded = response.headers.get("x-adkit-notice");
+  if (!encoded) return;
+  noticePrinted = true;
+  const text = decodeURIComponent(encoded);
+  const dim = "\x1B[2m";
+  const yellow = "\x1B[33m";
+  const reset = "\x1B[0m";
+  process.stderr.write(`${yellow}${dim}[AdKit notice] ${text}${reset}
+`);
+}
 function isErrorResponse(value) {
   return value != null && typeof value === "object";
 }
@@ -135,12 +150,18 @@ function appendErrorDetail(message, detail) {
 }
 function buildRetrySuggestion(retryable, retryAfterSeconds) {
   if (retryable !== true) return void 0;
-  if (typeof retryAfterSeconds === "number") return `Wait ${String(retryAfterSeconds)} seconds before retrying`;
+  if (typeof retryAfterSeconds === "number" && retryAfterSeconds <= 300) return `Wait ${String(retryAfterSeconds)} seconds before retrying`;
+  if (typeof retryAfterSeconds === "number") return `Try again ${describeRetryDelay(retryAfterSeconds)}`;
   return "Retry in a few seconds";
 }
-var AUTH_CODES = /* @__PURE__ */ new Set(["not_connected", "token_expired", "refresh_token_expired"]);
+function buildMetaDsaSuggestion(code) {
+  if (code !== "meta_dsa_identity_required") return void 0;
+  return 'Run: adkit manage meta accounts <account-id> update --beneficiary "<promoted person/org>" --payor "<payer>"';
+}
+var AUTH_CODES = /* @__PURE__ */ new Set(["invalid_grant", "auth_error", "auth_expired", "not_connected", "token_expired", "refresh_token_expired"]);
 function buildAuthSuggestion(code) {
-  if (!AUTH_CODES.has(code)) return void 0;
+  const normalizedCode = code.toLowerCase();
+  if (!AUTH_CODES.has(normalizedCode)) return void 0;
   return "Run: adkit setup manage";
 }
 var AdkitClient = class {
@@ -178,6 +199,7 @@ var AdkitClient = class {
       const detail = code ?? (err instanceof Error ? err.message : String(err));
       throw new CliError("NETWORK_ERROR", `Cannot reach ${target} (${detail})`, "Verify your network connection");
     }
+    printServerNotice(response);
     if (response.status === 204) return void 0;
     if (!response.ok) {
       let serverMessage = "";
@@ -201,7 +223,7 @@ var AdkitClient = class {
       if (structured) {
         const fallbackMsg = response.status >= 500 ? `Server error (HTTP ${String(response.status)})` : `Request failed (HTTP ${String(response.status)})`;
         const errorMsg = appendErrorDetail(dataMessage || serverMessage || fallbackMsg, batchSummary);
-        const suggestion2 = buildRetrySuggestion(retryable, retryAfterSeconds) ?? buildAuthSuggestion(structured.code);
+        const suggestion2 = buildMetaDsaSuggestion(structured.code) ?? buildRetrySuggestion(retryable, retryAfterSeconds) ?? buildAuthSuggestion(structured.code);
         const error = new CliError(structured.code, errorMsg, suggestion2);
         error.instructions = structured.instructions;
         error.actionUrl = structured.actionUrl;
@@ -2656,12 +2678,12 @@ var PLATFORM_OVERRIDE_FLAG = "platform-overrides";
 var CAMPAIGN_CREATE_FLAGS = ["name", "objective", "status", "budget-daily", "budget-lifetime", PLATFORM_OVERRIDE_FLAG];
 var CAMPAIGN_UPDATE_FLAGS = ["name", "status", "budget-daily", "budget-lifetime", PLATFORM_OVERRIDE_FLAG];
 var AD_GROUP_LIST_FLAGS2 = ["campaign-ids", "fields", "limit", "offset"];
-var AD_GROUP_CREATE_FLAGS = ["campaign", "name", "status", "budget-daily", "budget-lifetime", "billing-event", "bid-strategy", "optimization", "schedule-start-time", "schedule-end-time", "schedule-type", "pacing", "bid-amount", "event-type", "pixel", "placement", PLATFORM_OVERRIDE_FLAG];
-var AD_GROUP_UPDATE_FLAGS = ["name", "status", "budget-daily", "budget-lifetime", "billing-event", "optimization", "schedule-start-time", "schedule-end-time", "schedule-type", "pacing", "bid-amount", "event-type", "pixel", PLATFORM_OVERRIDE_FLAG];
+var AD_GROUP_CREATE_FLAGS = ["campaign", "name", "status", "budget-daily", "budget-lifetime", "billing-event", "bid-strategy", "optimization", "start-date", "end-date", "pacing", "bid-amount", "event-type", "pixel", "placement", PLATFORM_OVERRIDE_FLAG];
+var AD_GROUP_UPDATE_FLAGS = ["name", "status", "budget-daily", "budget-lifetime", "billing-event", "optimization", "start-date", "end-date", "pacing", "bid-amount", "event-type", "pixel", PLATFORM_OVERRIDE_FLAG];
 var AD_LIST_FLAGS2 = ["ad-group-ids", "campaign-ids", "fields", "limit", "offset"];
 var AD_CREATE_FLAGS = ["ad-group", "name", "status", "media-id", "ad-text", "url", "cta", "display-name", "identity-id", "identity-type", "tracking-pixel", PLATFORM_OVERRIDE_FLAG];
 var AD_UPDATE_FLAGS = ["ad-group", "name", "status", "media-id", "ad-text", "url", "cta", "display-name", "identity-id", "identity-type", "tracking-pixel", PLATFORM_OVERRIDE_FLAG];
-var RESULTS_FLAGS = ["level", "dimensions", "metrics", "from", "to", "order-field", "order-type", "limit", "offset"];
+var RESULTS_FLAGS = ["level", "fields", "breakdowns", "from", "to", "sort", "sort-direction", "limit", "offset"];
 function readSingleFlagValue2(flags, key, duplicateHint) {
   const value = flags[key];
   if (Array.isArray(value)) {
@@ -2800,19 +2822,15 @@ function buildTikTokAdGroupPayload(flags, mode) {
   if (mode === "create") {
     payload.campaignId = requireFlag(flags, "campaign", 'Run: adkit manage tiktok ad-groups create --campaign <campaign-id> --name "US Broad"');
     payload.name = requireFlag(flags, "name", 'Run: adkit manage tiktok ad-groups create --name "US Broad"');
-    payload.scheduleStartTime = requireFlag(flags, "schedule-start-time", "Use YYYY-MM-DD HH:mm:ss, or pass a full JSON body with --data");
-  } else {
-    if (typeof flags.name === "string") payload.name = flags.name;
-    if (typeof flags["schedule-start-time"] === "string") payload.scheduleStartTime = flags["schedule-start-time"];
-  }
+  } else if (typeof flags.name === "string") payload.name = flags.name;
   const budget = buildTikTokBudget(flags);
   if (budget) payload.budget = budget;
   if (typeof flags.status === "string") payload.status = flags.status;
   if (typeof flags["billing-event"] === "string") payload.billingEvent = flags["billing-event"];
   if (mode === "create" && typeof flags["bid-strategy"] === "string") payload.bidStrategy = flags["bid-strategy"];
   if (typeof flags.optimization === "string") payload.optimization = flags.optimization;
-  if (typeof flags["schedule-end-time"] === "string") payload.scheduleEndTime = flags["schedule-end-time"];
-  if (typeof flags["schedule-type"] === "string") payload.scheduleType = flags["schedule-type"];
+  if (typeof flags["start-date"] === "string") payload.startDate = flags["start-date"];
+  if (typeof flags["end-date"] === "string") payload.endDate = flags["end-date"];
   if (typeof flags.pacing === "string") payload.pacing = flags.pacing;
   const bidAmount = readNumberFlag(flags, "bid-amount");
   if (bidAmount !== void 0) payload.bidAmount = bidAmount;
@@ -2986,14 +3004,14 @@ async function listTikTokResults(client, _args, flags) {
   const accountId = typeof flags.account === "string" ? flags.account : void 0;
   const query = queryString({
     accountId,
-    dimensions: typeof flags.dimensions === "string" ? flags.dimensions : void 0,
+    breakdowns: typeof flags.breakdowns === "string" ? flags.breakdowns : void 0,
+    fields: typeof flags.fields === "string" ? flags.fields : void 0,
     from: typeof flags.from === "string" ? flags.from : void 0,
     level: typeof flags.level === "string" ? flags.level : void 0,
     limit: typeof flags.limit === "string" ? flags.limit : void 0,
-    metrics: typeof flags.metrics === "string" ? flags.metrics : void 0,
     offset: typeof flags.offset === "string" ? flags.offset : void 0,
-    orderField: typeof flags["order-field"] === "string" ? flags["order-field"] : void 0,
-    orderType: typeof flags["order-type"] === "string" ? flags["order-type"] : void 0,
+    sort: typeof flags.sort === "string" ? flags.sort : void 0,
+    sortDirection: typeof flags["sort-direction"] === "string" ? flags["sort-direction"] : void 0,
     to: typeof flags.to === "string" ? flags.to : void 0
   });
   return client.get(`/manage/tiktok/results${query}`);
@@ -4089,13 +4107,15 @@ Rules:
 Note:
   list returns ad set configuration only (targeting, budget, optimization).
   AdKit hides deleted and archived ad sets by default. Use --status to include them.
-  Geo targeting lives in targeting.geoLocations. Use type=country for country targeting.
-  Advanced geo examples: adkit manage meta adsets --help full
+  Geo targeting lives in targeting.geoLocations. Use type=country or type=radius with latitude/longitude coordinates.
+  Native city/place/zip examples: adkit manage meta adsets --help full
   For spend/clicks/conversions: adkit manage meta results
 
 Examples:
   # Conversion-optimized ad set targeting the US
   adkit manage meta adsets create --data '{"campaignId":"cmp_abc","name":"US Broad","optimization":"conversions","eventType":"purchase","budget":{"daily":20},"targeting":{"geoLocations":{"include":[{"type":"country","country":"US"}]}}}' --publish
+  # Radius targeting around coordinates
+  adkit manage meta adsets create --data '{"campaignId":"cmp_abc","name":"Strijen 30km","optimization":"link_clicks","budget":{"daily":20},"targeting":{"geoLocations":{"include":[{"type":"radius","latitude":51.745,"longitude":4.55,"radius":30,"radiusUnit":"km"}]}}}' --publish
   # Target specific interests
   adkit manage meta adsets create --data '{"campaignId":"cmp_abc","name":"US SaaS","optimization":"conversions","eventType":"purchase","budget":{"daily":20},"targeting":{"geoLocations":{"include":[{"type":"country","country":"US"}]},"interests":["6003344765839","6003127206524"]}}' --publish
   # Engagement-optimized ad set
@@ -4155,7 +4175,7 @@ Advanced flags:
   promotedObject.customEventType       (string) Custom conversion event
   promotedObject.pageId                (string) Facebook Page ID
   targeting.age                        (object) {"min":25,"max":55}
-  targeting.geoLocations               (object) {"include":[{"type":"country","country":"US"}]} or {"include":[{"type":"platformLocation","platform":"meta","value":{"custom_locations":[...]}}]}
+  targeting.geoLocations               (object) {"include":[{"type":"country","country":"US"}]} or {"include":[{"type":"radius","latitude":51.745,"longitude":4.55,"radius":30,"radiusUnit":"km"}]}
   targeting.publisherPlatforms         (string[]) facebook, instagram, audience_network, messenger
   targeting.devicePlatforms            (string[]) mobile, desktop
   targeting.interests                  (string[]) Interest IDs
@@ -4172,15 +4192,16 @@ Advanced flags:
 Note:
   list returns ad set configuration only (targeting, budget, optimization).
   AdKit hides deleted and archived ad sets by default. Use --status to include them.
-  Geo targeting lives in targeting.geoLocations. Use type=country for simple countries, or type=platformLocation for raw Meta geo like custom_locations.
-  With platformLocation, pass the exact Meta geo object to send; AdKit does not look up or convert city names or addresses.
+  Geo targeting lives in targeting.geoLocations. Use type=country for simple countries or type=radius for coordinate-radius targeting.
+  Radius targeting requires latitude/longitude coordinates; AdKit does not geocode addresses yet.
+  With platformLocation, pass the exact Meta geo object to send for native city/place/zip IDs and unsupported geo fields.
   For spend/clicks/conversions: adkit manage meta results
 
 Examples:
   # Conversion-optimized ad set targeting the US
   adkit manage meta adsets create --data '{"campaignId":"cmp_abc","name":"US Broad","optimization":"conversions","eventType":"purchase","budget":{"daily":20},"targeting":{"geoLocations":{"include":[{"type":"country","country":"US"}]}}}' --publish
-  # Radius targeting through raw Meta geo
-  adkit manage meta adsets create --data '{"campaignId":"cmp_abc","name":"SF 5mi","optimization":"link_clicks","budget":{"daily":20},"targeting":{"geoLocations":{"include":[{"type":"platformLocation","platform":"meta","value":{"custom_locations":[{"latitude":37.7749,"longitude":-122.4194,"radius":5,"distance_unit":"mile"}]}}]}}}' --publish
+  # Radius targeting around coordinates
+  adkit manage meta adsets create --data '{"campaignId":"cmp_abc","name":"Strijen 30km","optimization":"link_clicks","budget":{"daily":20},"targeting":{"geoLocations":{"include":[{"type":"radius","latitude":51.745,"longitude":4.55,"radius":30,"radiusUnit":"km"}]}}}' --publish
   # Target specific interests
   adkit manage meta adsets create --data '{"campaignId":"cmp_abc","name":"US SaaS","optimization":"conversions","eventType":"purchase","budget":{"daily":20},"targeting":{"geoLocations":{"include":[{"type":"country","country":"US"}]},"interests":["6003344765839","6003127206524"]}}' --publish
   # Full JSON payload with custom targeting and age range
@@ -4205,7 +4226,7 @@ var ADS_HELP = `adkit manage meta ads \u2014 Meta ads
 
 Flags (create \u2014 new creative from media):
   --adset <id>        Ad set ID (required)
-  --media <path|url>  Media file or URL (repeatable). Handles upload + processing automatically
+  --media <path|url>  Media file or URL (repeatable). Handles upload + processing automatically for single-image/video ads
   --primary-text <t>  Ad body text (repeatable)
   --headline <text>   Headline text (repeatable)
   --description <t>   Description text (repeatable, optional)
@@ -4232,6 +4253,7 @@ Note:
   update is partial. If --data sends an array field, it replaces that whole array; omitted arrays stay unchanged.
   list returns ad configuration only (creative, status, adset).
   AdKit hides deleted and archived ads by default. Use --status to include them.
+  Single-image/video ads use --media. Carousel ads use --data with carouselCards.
 
 Examples:
   # Create an ad with a local video file
@@ -4254,7 +4276,7 @@ Examples:
 Tip: to share engagement (likes/comments) across ads, reuse the creative ID
 from your first ad: --creative <id>
 
-Run --help full for all fields including per-placement creative (--media-format).`;
+Run --help full for all fields including carouselCards and per-placement creative (--media-format).`;
 var ADS_HELP_FULL = `adkit manage meta ads \u2014 Meta ads
 
   list                List ads
@@ -4265,7 +4287,7 @@ var ADS_HELP_FULL = `adkit manage meta ads \u2014 Meta ads
 
 Flags (create \u2014 new creative from media):
   --adset <id>        Ad set ID (required)
-  --media <path|url>  Media file or URL (repeatable). Handles upload + processing automatically
+  --media <path|url>  Media file or URL (repeatable). Handles upload + processing automatically for single-image/video ads
   --media-format <f>  Optional format for each --media: default, square, vertical, horizontal
   --primary-text <t>  Ad body text (repeatable)
   --headline <text>   Headline text (repeatable)
@@ -4293,6 +4315,7 @@ Note:
   update is partial. If --data sends an array field, it replaces that whole array; omitted arrays stay unchanged.
   list returns ad configuration only (creative, status, adset).
   AdKit hides deleted and archived ads by default. Use --status to include them.
+  Single-image/video ads use --media. Carousel ads use --data with carouselCards.
 
 --data JSON fields:
   adsetId             (required) Parent ad set ID
@@ -4303,6 +4326,17 @@ Note:
                       Keeps its likes/comments/shares. Cannot combine with media/creative fields.
   media               [{ id: "imageHashOrVideoId" }, { id: "...", format: "vertical" }]
                       Normal media works on all placements. Add format only to replace a specific placement group with different media: square (Feed), vertical (Stories/Reels), horizontal (Right Column).
+                      Do not use top-level media for carousel ads.
+  carouselCards
+                      Card list for carousel ads. Each card needs headline and media.
+  carouselCards[].headline
+                      Required card title.
+  carouselCards[].description
+                      Optional card text.
+  carouselCards[].linkUrl
+                      Optional card destination. Defaults to url when omitted.
+  carouselCards[].media
+                      Required card media: [{ role: "image"|"video", id }]. Use uploaded image hashes or video IDs.
   leadFormId          Existing Meta Instant Form ID; requires media + url
   platformOverrides   Raw Meta API fields merged onto the payload
 
@@ -4323,6 +4357,17 @@ Examples:
   adkit manage meta ads create --adset as_789 \\
     --media ./feed.jpg --media ./story.mp4 --media-format default --media-format vertical \\
     --primary-text "Try it free" --headline "Get started" --url https://example.com --publish
+  # Create a carousel ad with existing uploaded media IDs
+  adkit manage meta ads create --data '{
+    "ads":[{
+      "adsetId":"as_789","name":"Carousel v1","pageId":"pg_123",
+      "primaryTexts":["Shop the collection"],"url":"https://example.com","cta":"shop_now",
+      "carouselCards":[
+        {"headline":"Product 1","media":[{"role":"image","id":"abc123hash"}]},
+        {"headline":"Product 2","media":[{"role":"video","id":"120..."}]}
+      ]
+    }]
+  }' --publish
   # Create an ad from an existing creative (shares engagement)
   adkit manage meta ads create --adset as_789 --creative cr_abc --name "Hero v1" --publish
   # Use an existing Facebook post as the ad
@@ -4471,7 +4516,7 @@ var GOOGLE_ASSET_HELP = `adkit manage google assets \u2014 Reusable Google manua
 Flags (list):
   --type <type>       callout, sitelink, structured-snippet
   --scope <scope>     account, campaign, ad-group
-  --scope-id <id>     Campaign/ad-group ID for scoped filtering
+  --scope-id <id>     Google campaign/ad group ID (platformId); required for campaign/ad-group scope
 
 Flags (create/update):
   --type <type>       callout, sitelink, structured-snippet
@@ -4483,7 +4528,7 @@ Flags (create/update):
 Flags (attach/detach):
   --type <type>       callout, sitelink, structured-snippet, image
   --scope <scope>     account, campaign, ad-group
-  --scope-id <id>     Required for campaign/ad-group scope
+  --scope-id <id>     Google campaign/ad group ID (platformId); required for campaign/ad-group scope
 
 Examples:
   adkit manage google assets list --type callout --account 1234567890
@@ -4510,7 +4555,7 @@ var GOOGLE_ASSET_HELP_FULL = `adkit manage google assets \u2014 Reusable Google
 Flags (list):
   --type <type>       callout, sitelink, structured-snippet
   --scope <scope>     account, campaign, ad-group
-  --scope-id <id>     Campaign/ad-group ID for scoped filtering
+  --scope-id <id>     Google campaign/ad group ID (platformId); required for campaign/ad-group scope
 ${FLAG.account}
 
 Flags (create/update):
@@ -4532,7 +4577,7 @@ ${FLAG.data}
 Flags (attach/detach):
   --type <type>       callout, sitelink, structured-snippet, image
   --scope <scope>     account, campaign, ad-group
-  --scope-id <id>     Required for campaign/ad-group scope
+  --scope-id <id>     Google campaign/ad group ID (platformId); required for campaign/ad-group scope
   --status <s>        enabled, paused, removed
 ${FLAG.account}
 ${FLAG.publish}
@@ -4550,9 +4595,9 @@ var GOOGLE_CAMPAIGN_HELP = `adkit manage google campaigns \u2014 Google Ads camp
 
   list                List campaigns
   create              Create a campaign
-  update <id>         Update a campaign
-  delete <id>         Delete a campaign
-  <id>                View campaign details
+  update <id>         Update by Google campaign ID (platformId)
+  delete <id>         Delete by Google campaign ID (platformId)
+  <id>                View by Google campaign ID (platformId)
 
 Flags (create):
   --name <name>       Campaign name (required)
@@ -4578,6 +4623,7 @@ Note:
   Advanced geo examples: adkit manage google campaigns --help full
   Display creation starts here: campaigns create --campaign-type display, then create Display ad groups and responsive_display ads.
   Performance Max: campaignType "performance_max" with asset groups \u2014 build it with --data. See --help full.
+  View a Performance Max campaign by ID to read back its assetGroups from Google.
   For spend/clicks/conversions: adkit manage google results
 
 Examples:
@@ -4592,9 +4638,9 @@ var GOOGLE_CAMPAIGN_HELP_FULL = `adkit manage google campaigns \u2014 Google Ads
 
   list                List campaigns
   create              Create a campaign
-  update <id>         Update a campaign
-  delete <id>         Delete a campaign
-  <id>                View campaign details
+  update <id>         Update by Google campaign ID (platformId)
+  delete <id>         Delete by Google campaign ID (platformId)
+  <id>                View by Google campaign ID (platformId)
 
 Flags (create):
   --name <name>       Campaign name (required)
@@ -4628,6 +4674,7 @@ Notes:
   Google excludes support location geo target constants, not proximity radius exclusions.
   Display campaign creation uses campaignType:"display" or --campaign-type display. Videos are not supported for Display media in v1.
   Performance Max: campaignType "performance_max" with exactly one assetGroups[] entry. Text assets inline ({role,text}); image assets are uploaded via google media first, then referenced by id/resourceName. Needs an enabled conversion action (publish is blocked without one). Non-retail only. Build it with --data.
+  View a Performance Max campaign by ID to read back assetGroups from Google. There is no separate google asset-groups command.
   For spend/clicks/conversions: adkit manage google results
 
 Examples:
@@ -4643,18 +4690,18 @@ var GOOGLE_AD_GROUP_HELP = `adkit manage google ad-groups \u2014 Google Ads ad g
 
   list                List ad groups
   create              Create an ad group
-  update <id>         Update an ad group
-  delete <id>         Delete an ad group
-  <id>                View ad group details
+  update <id>         Update by Google ad group ID (platformId)
+  delete <id>         Delete by Google ad group ID (platformId)
+  <id>                View by Google ad group ID (platformId)
 
 Flags (create/update):
-  --campaign <id>     Parent campaign ID
+  --campaign <id>     Google campaign ID (platformId)
   --name <name>       Ad group name
   --status <s>        enabled, paused, removed
   --cpc-bid <n>       CPC bid in account currency
 
 Flags (list):
-  --campaign <id>     Filter by campaign ID
+  --campaign <id>     Filter by Google campaign ID (platformId)
   --status <s>        Filter by ad group status (default: enabled,paused; use all for every status)
   --limit <n>         Max results
   --offset <n>        Pagination offset
@@ -4679,12 +4726,12 @@ var GOOGLE_AD_GROUP_HELP_FULL = `adkit manage google ad-groups \u2014 Google Ads
 
   list                List ad groups
   create              Create an ad group
-  update <id>         Update an ad group
-  delete <id>         Delete an ad group
-  <id>                View ad group details
+  update <id>         Update by Google ad group ID (platformId)
+  delete <id>         Delete by Google ad group ID (platformId)
+  <id>                View by Google ad group ID (platformId)
 
 Flags (create/update):
-  --campaign <id>     Parent campaign ID
+  --campaign <id>     Google campaign ID (platformId)
   --name <name>       Ad group name
   --status <s>        enabled, paused, removed
   --cpc-bid <n>       CPC bid in account currency
@@ -4693,7 +4740,7 @@ ${FLAG.publish}
 ${FLAG.data}
 
 Flags (list):
-  --campaign <id>     Filter by campaign ID
+  --campaign <id>     Filter by Google campaign ID (platformId)
   --status <s>        Filter by ad group status (default: enabled,paused; use all for every status)
   --limit <n>         Max results
   --offset <n>        Pagination offset
@@ -4720,12 +4767,12 @@ var GOOGLE_AD_HELP = `adkit manage google ads \u2014 Google ads
 
   list                List ads
   create              Create an ad
-  update <id>         Update an ad
-  delete <id>         Delete an ad
-  <id>                View ad details
+  update <id>         Update by Google ad ID (platformId)
+  delete <id>         Delete by Google ad ID (platformId)
+  <id>                View by Google ad ID (platformId)
 
 Flags (create/update):
-  --ad-group <id>        Parent ad group ID
+  --ad-group <id>        Google ad group ID (platformId)
   --headline <text>      Search RSA headline (repeatable, max 30 chars each). Use --headline-1/2/3 to pin to position 1\u20133.
   --description <text>   Search RSA description (repeatable, max 90 chars each). Use --description-1/2 to pin to position 1\u20132.
   --callout <value>      Repeatable. Use asset:<id> or raw callout text
@@ -4735,7 +4782,7 @@ Flags (create/update):
   --status <s>           enabled, paused, removed
 
 Flags (list):
-  --ad-group <id>        Filter by ad group ID
+  --ad-group <id>        Filter by Google ad group ID (platformId)
   --status <s>           Filter by ad status (default: enabled,paused; use all for every status)
   --limit <n>            Max results
   --offset <n>           Pagination offset
@@ -4767,12 +4814,12 @@ var GOOGLE_AD_HELP_FULL = `adkit manage google ads \u2014 Google ads
 
   list                List ads
   create              Create an ad
-  update <id>         Update an ad
-  delete <id>         Delete an ad
-  <id>                View ad details
+  update <id>         Update by Google ad ID (platformId)
+  delete <id>         Delete by Google ad ID (platformId)
+  <id>                View by Google ad ID (platformId)
 
 Flags (create/update):
-  --ad-group <id>        Parent ad group ID
+  --ad-group <id>        Google ad group ID (platformId)
   --headline <text>      Search RSA headline (repeatable, unpinned, max 30 chars each). Up to 15 per ad.
   --headline-1/2/3 <t>   Search RSA headline pinned to position 1, 2, or 3 (repeatable, max 30 chars each).
   --description <text>   Search RSA description (repeatable, unpinned, max 90 chars each). Up to 4 per ad.
@@ -4787,7 +4834,7 @@ ${FLAG.publish}
 ${FLAG.data}
 
 Flags (list):
-  --ad-group <id>        Filter by ad group ID
+  --ad-group <id>        Filter by Google ad group ID (platformId)
   --status <s>           Filter by ad status (default: enabled,paused; use all for every status)
   --limit <n>            Max results
   --offset <n>           Pagination offset
@@ -4823,22 +4870,22 @@ var GOOGLE_KEYWORD_HELP = `adkit manage google keywords \u2014 Google Ads keywor
   negatives           Manage negative keywords
   negative-lists      Manage reusable shared negative lists
   add                 Add a keyword
-  update <id>         Update a keyword
-  remove <id>         Remove a keyword
-  <id>                View keyword details
+  update <id>         Update by Google keyword ID (platformId)
+  remove <id>         Remove by Google keyword ID (platformId)
+  <id>                View by Google keyword ID (platformId)
 
 Flags (add):
-  --ad-group <id>      Parent ad group ID
+  --ad-group <id>      Google ad group ID (platformId)
   --text <keyword>     Keyword text
   --match-type <type>  exact, phrase, broad
 
 Flags (update):
-  --ad-group <id>      Parent ad group ID
+  --ad-group <id>      Google ad group ID (platformId)
   --cpc-bid <n>        CPC bid in account currency
   --status <s>         enabled, paused, removed
 
 Flags (list):
-  --ad-group <id>      Filter by ad group ID
+  --ad-group <id>      Filter by Google ad group ID (platformId)
   --status <s>         Filter by keyword status (default: enabled,paused; use all for every status)
   --limit <n>          Max results
   --offset <n>         Pagination offset
@@ -4861,17 +4908,17 @@ var GOOGLE_KEYWORD_HELP_FULL = `adkit manage google keywords \u2014 Google Ads k
   negatives           Manage negative keywords
   negative-lists      Manage reusable shared negative lists
   add                 Add a keyword
-  update <id>         Update a keyword
-  remove <id>         Remove a keyword
-  <id>                View keyword details
+  update <id>         Update by Google keyword ID (platformId)
+  remove <id>         Remove by Google keyword ID (platformId)
+  <id>                View by Google keyword ID (platformId)
 
 Flags (add):
-  --ad-group <id>      Parent ad group ID
+  --ad-group <id>      Google ad group ID (platformId)
   --text <keyword>     Keyword text
   --match-type <type>  exact, phrase, broad
 
 Flags (update):
-  --ad-group <id>      Parent ad group ID
+  --ad-group <id>      Google ad group ID (platformId)
   --cpc-bid <n>        CPC bid in account currency
   --status <s>         enabled, paused, removed
 ${FLAG.account}
@@ -4879,7 +4926,7 @@ ${FLAG.publish}
 ${FLAG.data}
 
 Flags (list):
-  --ad-group <id>      Filter by ad group ID
+  --ad-group <id>      Filter by Google ad group ID (platformId)
   --status <s>         Filter by keyword status (default: enabled,paused; use all for every status)
   --limit <n>          Max results
   --offset <n>         Pagination offset
@@ -4902,17 +4949,17 @@ var GOOGLE_KEYWORD_NEGATIVES_HELP = `adkit manage google keywords negatives \u20
   remove <id>         Remove a negative keyword
 
 Flags (list):
-  --campaign <id>      Filter by campaign
-  --ad-group <id>      Filter by ad group
-  --negative-keyword-list <id>  Filter by shared negative list
+  --campaign <id>      Filter by Google campaign ID (platformId)
+  --ad-group <id>      Filter by Google ad group ID (platformId)
+  --negative-keyword-list <id>  Filter by Google negative keyword list ID (platformId)
   --limit <n>          Max results
 
 Flags (add):
   --text <keyword>     Keyword text (repeatable; supports bracket shorthand: [exact], "phrase", broad)
   --match-type <type>  Explicit match type (repeat once or once per --text)
-  --campaign <id>      Add at campaign scope
-  --ad-group <id>      Add at ad group scope
-  --negative-keyword-list <id>  Add to a shared negative list
+  --campaign <id>      Google campaign ID (platformId)
+  --ad-group <id>      Google ad group ID (platformId)
+  --negative-keyword-list <id>  Google negative keyword list ID (platformId)
 ${FLAG.publish}
 ${FLAG.data}
 
@@ -4943,7 +4990,7 @@ ${FLAG.publish}
 ${FLAG.data}
 
 Flags (attach/detach):
-  --campaign <id>     Campaign ID
+  --campaign <id>     Google campaign ID (platformId)
 ${FLAG.publish}
 
 Examples:
@@ -4965,8 +5012,8 @@ var GOOGLE_RESULTS_HELP = `adkit manage google results \u2014 Google Ads perform
   search-terms        Search terms that triggered your ads
 
 Flags:
-  --campaign <id>     Filter by campaign ID
-  --ad-group <id>     Filter by ad group ID
+  --campaign <id>     Filter by Google campaign ID (platformId)
+  --ad-group <id>     Filter by Google ad group ID (platformId)
   --period <period>   Date range (30d, 90d, this_month, last_year, maximum, etc. Default: 30d)
   --from <date>       Start date (YYYY-MM-DD, requires --to)
   --to <date>         End date (YYYY-MM-DD, requires --from)
@@ -5001,8 +5048,8 @@ var GOOGLE_RESULTS_PLACEMENTS_HELP = `adkit manage google results placements \u2
 
 Flags:
   --account <id>      Optional if one Google Ads account is connected
-  --campaign <id>     Filter by campaign
-  --ad-group <id>     Filter by ad group
+  --campaign <id>     Filter by Google campaign ID (platformId)
+  --ad-group <id>     Filter by Google ad group ID (platformId)
   --period <preset>   Date range: 30d, 90d, this_month, last_year, maximum, etc. (default: 30d)
   --from <date>       Custom start date (YYYY-MM-DD, requires --to)
   --to <date>         Custom end date (YYYY-MM-DD, requires --from)
@@ -5019,8 +5066,8 @@ var GOOGLE_KEYWORD_SEARCH_TERMS_HELP = `adkit manage google results search-terms
 
 Flags:
   --account <id>          Optional if one Google Ads account is connected
-  --campaign <id>         Filter by campaign
-  --ad-group <id>         Filter by ad group
+  --campaign <id>         Filter by Google campaign ID (platformId)
+  --ad-group <id>         Filter by Google ad group ID (platformId)
   --keyword <text>        Filter by matched keyword text
   --keyword-match-type    Filter by matched keyword match type: exact, phrase, broad
   --period <preset>       Date range: 30d, 90d, this_month, last_year, maximum, etc. (default: maximum)
@@ -5048,8 +5095,8 @@ var GOOGLE_RESULTS_KEYWORDS_HELP = `adkit manage google results keywords \u2014
 
 Flags:
   --account <id>      Optional if one Google Ads account is connected
-  --campaign <id>     Filter by campaign
-  --ad-group <id>     Filter by ad group
+  --campaign <id>     Filter by Google campaign ID (platformId)
+  --ad-group <id>     Filter by Google ad group ID (platformId)
   --period <preset>   Date range: 30d, 90d, this_month, last_year, maximum, etc. (default: 30d)
   --from <date>       Custom start date (YYYY-MM-DD, requires --to)
   --to <date>         Custom end date (YYYY-MM-DD, requires --from)
@@ -5266,8 +5313,8 @@ ${FLAG.data}
   --status <s>        active, paused
   --budget-daily <n>  Daily budget in account currency
   --budget-lifetime <n> Lifetime budget in account currency
-  --schedule-start-time <value> Required for create, e.g. "2026-05-15 12:00:00"
-  --schedule-end-time <value> Optional end time
+  --start-date <value> Optional TikTok schedule datetime; omit to start now
+  --end-date <value>   Optional TikTok schedule datetime; required with lifetime budget
   --billing-event <s> cpc, cpm, ocpm
   --bid-strategy <s>  bid_type_no_bid, bid_type_custom, bid_type_max_conversion
   --optimization <s>  click, convert, lead_generation, video_view, reach
@@ -5277,8 +5324,8 @@ ${FLAG.data}
   --placement <ids>   Override TikTok placement IDs (publish default: PLACEMENT_TIKTOK)
 
 Examples:
-  adkit manage tiktok ad-groups create --campaign 1770 --name "US Broad" --budget-daily 50 --schedule-start-time "2026-05-15 12:00:00" --billing-event cpc --optimization click
-  adkit manage tiktok ad-groups create --data '{"adGroups":[{"campaignId":"1770","name":"Purchase","budget":{"daily":50},"scheduleStartTime":"2026-05-15 12:00:00","bidAmount":80,"conversion":{"eventType":"purchase"},"targeting":{"geoLocations":{"include":[{"type":"country","country":"US"}]}}}]}'`.trim(),
+  adkit manage tiktok ad-groups create --campaign 1770 --name "US Broad" --budget-daily 50 --billing-event cpc --optimization click
+  adkit manage tiktok ad-groups create --data '{"adGroups":[{"campaignId":"1770","name":"Purchase","budget":{"daily":50},"startDate":"2026-05-15 12:00:00","bidAmount":80,"conversion":{"eventType":"purchase"},"targeting":{"geoLocations":{"include":[{"type":"country","country":"US"}]}}}]}'`.trim(),
   "tiktok ads": `adkit manage tiktok ads \u2014 TikTok video ads
 
   list                List ads
@@ -5314,19 +5361,19 @@ Examples:
 Flags:
 ${FLAG.account}
   --level <level>     account, campaigns, ad-groups, ads (default: campaigns)
-  --dimensions <csv>  TikTok reporting dimensions, e.g. campaign_id
-  --metrics <csv>     TikTok reporting metrics, e.g. spend,impressions,clicks
+  --fields <csv>      Normalized fields, e.g. spend,impressions,clicks,conversions
+  --breakdowns <csv>  Row breakdowns, e.g. day
   --from <date>       YYYY-MM-DD
   --to <date>         YYYY-MM-DD
-  --order-field <f>   Optional sort metric/field
-  --order-type <t>    asc or desc
+  --sort <field>      Optional normalized sort field, e.g. spend
+  --sort-direction <t> asc or desc
   --limit <n>         Max rows
 
 Note:
-  Results MVP passes TikTok report dimension/metric names through to the TikTok reporting API.
+  For raw TikTok report dimensions/metrics outside this normalized contract, use platform-api-request with TikTok report/integrated/get.
 
 Example:
-  adkit manage tiktok results --level campaigns --dimensions campaign_id --metrics spend,impressions,clicks --from 2026-05-01 --to 2026-05-15`.trim(),
+  adkit manage tiktok results --level campaigns --fields spend,impressions,clicks --breakdowns day --from 2026-05-01 --to 2026-05-15`.trim(),
   "reddit accounts": `adkit manage reddit accounts \u2014 Reddit Ads accounts
 
   list                List connected Reddit ad accounts
@@ -6027,7 +6074,7 @@ function printSingleEntity(e, entity) {
   } else {
     const ad = e;
     const createdAt = shortDate(ad.createdAt);
-    lines.push(`  Ad:           ${formatForTTY(ad.name)}`, `  ID:           ${formatForTTY(ad.id)}`, `  Ad Set:       ${formatForTTY(ad.adsetId)}`, `  Campaign:     ${formatForTTY(ad.campaignId)}`, `  Status:       ${formatForTTY(ad.status)}`);
+    lines.push(`  Ad:           ${formatForTTY(ad.name)}`, `  ID:           ${formatForTTY(ad.platformId)}`, `  Ad Set:       ${formatForTTY(ad.adsetId)}`, `  Campaign:     ${formatForTTY(ad.campaignId)}`, `  Status:       ${formatForTTY(ad.status)}`);
     const creative = ad.creative;
     if (creative) {
       lines.push("", "  Creative", "");
@@ -6442,11 +6489,7 @@ function showHelp(key, full = false) {
   return false;
 }
 function printHelp(text) {
-  const statusNotice = getAdKitStatusNotice();
-  const helpText = statusNotice ? `${statusNotice}
-
-${text}` : text;
-  console.log(helpText);
+  console.log(text);
 }
 async function selfUpdate(currentVersion) {
   const { execSync } = await import("node:child_process");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adkit/cli",
-  "version": "1.12.4",
+  "version": "1.12.9",
   "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",
@@ -34,6 +34,9 @@
     "build": "esbuild src/cli.ts --bundle --format=esm --platform=node --target=node18 --outfile=dist/cli.js --banner:js='#!/usr/bin/env node'",
     "release": "cd ../shared && npm run build && cd ../cli && npm version patch && npm run build && npm publish --access public"
   },
+  "dependencies": {
+    "open": "^10.2.0"
+  },
   "devDependencies": {
     "@adkit/shared": "*",
     "@types/node": "^20.10.0",