@adkit.so/cli 1.0.0

package/dist/cli.js

@@ -0,0 +1,841 @@
+#!/usr/bin/env node
+import { resolveConfig, readConfig } from './config.js';
+import { AdkitClient } from './client.js';
+import { formatOutput } from './output.js';
+import { login, logout } from './commands/auth.js';
+import { listProjects, useProject, currentProject } from './commands/projects.js';
+import { listAccounts, connectAccount, disconnectAccount, listPages, listPixels, listCampaigns, createCampaign, updateCampaign, deleteCampaign, listAdSets, createAdSet, updateAdSet, deleteAdSet, listAds, createAd, updateAd, deleteAd, createCreative, updateCreative, deleteCreative, uploadMedia, listMedia, deleteMedia, searchInterests } from './commands/meta.js';
+import { status } from './commands/status.js';
+import { listDrafts, getDraft, publishDraft, deleteDraft } from './commands/drafts.js';
+import { parseArgs, unwrapList } from './cli-utils.js';
+import { CliError } from './errors.js';
+const DEFAULT_BASE_URL = 'https://app.adkit.so/api/v1';
+const USAGE = `
+Usage: adkit <command> [options]
+
+Commands:
+  status              Show project context and connected accounts
+  setup [area...]     Set up AdKit (opens browser)
+  manage <platform> <entity> <action>   Manage ad platforms (meta, google, etc.)
+  manage drafts <action>                Manage drafts (list, get, publish, delete)
+  projects <action>   Manage projects (list, use, current)
+
+Advanced:
+  logout              Remove stored API key
+
+Global flags:
+  --json             Force JSON output (default when not a TTY)
+  --project <id>     Use a specific project (overrides default)
+  --fields <list>    Comma-separated fields to show (for list commands)
+  --help             Show help (--help full = complete field reference, but more verbose)
+
+Run \`adkit <command> --help\` for details.
+`.trim();
+// ---------------------------------------------------------------------------
+// Shared flag descriptions (DRY building blocks for help text)
+// ---------------------------------------------------------------------------
+const FLAG = {
+    account: '  --account <id>      Ad account ID (auto-resolved if only one)',
+    publish: '  --publish           Publish immediately (default: draft)',
+    overrides: '  --platform-overrides <json>  Raw Meta API fields merged onto payload',
+    data: '  --data <json>       Full JSON body — bypasses named flags',
+    status: '  --status <s>        active, paused, archived',
+    budgetDaily: '  --budget-daily <n>  Daily budget in account currency',
+    cta: '  --cta <type>        sign_up, learn_more, shop_now, download, get_offer, contact_us, subscribe, get_quote, book_now, apply_now',
+};
+// ---------------------------------------------------------------------------
+// Entity-specific help text
+// ---------------------------------------------------------------------------
+// --- Campaigns ---
+const CAMPAIGN_HELP = `adkit manage meta campaigns — Meta ad campaigns
+
+  list                List campaigns
+  create              Create a campaign
+  update <id>         Update a campaign
+  delete <id>         Delete a campaign
+
+Flags (create/update):
+  --name <name>       Campaign name (required for create)
+  --objective <type>  traffic, awareness, engagement, leads, sales, app_promotion
+${FLAG.status}
+${FLAG.budgetDaily}
+
+Examples:
+  adkit manage meta campaigns create --name "Spring Sale" --objective sales --budget-daily 50 --publish
+  adkit manage meta campaigns update cmp_abc --status paused
+  adkit manage meta campaigns delete cmp_abc
+
+Run --help full for all fields and advanced options.`;
+const CAMPAIGN_HELP_FULL = `adkit manage meta campaigns — Meta ad campaigns
+
+  list                List campaigns
+  create              Create a campaign
+  update <id>         Update a campaign
+  delete <id>         Delete a campaign
+
+Flags (create/update):
+  --name <name>       Campaign name (required for create)
+  --objective <type>  traffic, awareness, engagement, leads, sales, app_promotion
+${FLAG.status}
+${FLAG.budgetDaily}
+
+Advanced flags:
+  --bid-strategy <s>  lowest_cost (default), cost_cap, bid_cap, min_roas
+  --abo               Adset budget optimization (disables campaign-level budget)
+
+--data JSON fields:
+  budget.lifetime      (number) Lifetime budget in account currency
+  spendCap             (number) Total spend cap
+  specialAdCategories  (string[]) credit, housing, employment, social_issues
+  startDate            (string) ISO date, e.g. "2026-04-01T00:00:00+0000"
+  endDate              (string|null) ISO date or null for no end
+
+Examples:
+  adkit manage meta campaigns list --account act_123456789
+  adkit manage meta campaigns create --name "Spring Sale" --objective sales --budget-daily 50 --publish
+  adkit manage meta campaigns update cmp_abc --status paused
+  adkit manage meta campaigns update cmp_abc --budget-daily 100
+  adkit manage meta campaigns delete cmp_abc
+  adkit manage meta campaigns create --data '{
+    "name":"Housing Leads","objective":"leads",
+    "budget":{"lifetime":500},"specialAdCategories":["housing"],
+    "startDate":"2026-04-01T00:00:00+0000","endDate":"2026-04-30T23:59:59+0000"
+  }' --publish`;
+// --- Ad Sets ---
+const ADSET_HELP = `adkit manage meta adsets — Meta ad sets
+
+  list                List ad sets
+  create              Create an ad set
+  update <id>         Update an ad set
+  delete <id>         Delete an ad set
+
+Flags (create/update):
+  --campaign <id>     Parent campaign ID (required for create)
+  --name <name>       Ad set name (required for create)
+${FLAG.status}
+${FLAG.budgetDaily}
+  --optimization <t>  link_clicks, impressions, reach, conversions, landing_page_views, lead_generation
+  --event-type <t>    purchase, lead, complete_registration, add_to_cart, subscribe, start_trial, contact, content_view, other
+  --pixel <id>        Pixel ID (falls back to account default)
+  --countries <codes> Comma-separated ISO codes, e.g. US,CA
+  --interest <id>     Interest ID (repeatable). Find IDs: adkit manage meta interests search <query>
+
+Rules:
+  - objective=sales → event-type: purchase, add_to_cart, complete_registration, subscribe, start_trial, content_view
+  - objective=leads → event-type: lead, contact, complete_registration, subscribe, other
+
+Examples:
+  adkit manage meta adsets create --campaign cmp_abc --name "US Broad" \\
+    --optimization conversions --event-type purchase --countries US --budget-daily 20 --publish
+  adkit manage meta adsets create --campaign cmp_abc --name "US SaaS" \\
+    --optimization conversions --event-type purchase --countries US \\
+    --interest "6003344765839" --interest "6003127206524" --budget-daily 20 --publish
+  adkit manage meta adsets update as_xyz --budget-daily 50
+  adkit manage meta adsets delete as_xyz
+
+Run --help full for all fields and advanced options.`;
+const ADSET_HELP_FULL = `adkit manage meta adsets — Meta ad sets
+
+  list                List ad sets
+  create              Create an ad set
+  update <id>         Update an ad set
+  delete <id>         Delete an ad set
+
+Flags (create/update):
+  --campaign <id>     Parent campaign ID (required for create)
+  --name <name>       Ad set name (required for create)
+${FLAG.status}
+${FLAG.budgetDaily}
+  --optimization <t>  link_clicks, impressions, reach, conversions, landing_page_views, lead_generation
+  --event-type <t>    purchase, lead, complete_registration, add_to_cart, subscribe, start_trial, contact, content_view, other
+  --pixel <id>        Pixel ID (falls back to account default)
+  --countries <codes> Comma-separated ISO codes, e.g. US,CA
+  --interest <id>     Interest ID (repeatable). Find IDs: adkit manage meta interests search <query>
+
+Rules:
+  - objective=sales → event-type: purchase, add_to_cart, complete_registration, subscribe, start_trial, content_view
+  - objective=leads → event-type: lead, contact, complete_registration, subscribe, other
+
+Advanced flags:
+  --targeting <json>  Complex targeting JSON, merged with simple flags (JSON keys take precedence)
+  --genders <list>    male, female
+
+--data JSON fields:
+  budget.lifetime                      (number) Lifetime budget
+  bidAmount                            (number) Bid amount in account currency
+  destinationType                      (string) website, app, messenger, instagram, whatsapp
+  startTime                            (string) ISO date
+  endTime                              (string) ISO date
+  isDynamicCreative                    (boolean) Enable dynamic creative
+  promotedObject.pixelId               (string) Meta Pixel ID
+  promotedObject.customEventType       (string) Custom conversion event
+  promotedObject.pageId                (string) Facebook Page ID
+  targeting.age                        (object) {"min":25,"max":55}
+  targeting.publisherPlatforms         (string[]) facebook, instagram, audience_network, messenger
+  targeting.devicePlatforms            (string[]) mobile, desktop
+  targeting.interests                  (string[]) Interest IDs
+  targeting.behaviors                  (string[]) Behavior IDs
+  targeting.customAudiences            (string[]) Custom audience IDs
+  targeting.excludedCustomAudiences    (string[]) Excluded audience IDs
+  targeting.expand                     (object) Advantage+ audience controls
+
+  Note: Meta defaults to Advantage+ audience (AI-driven targeting).
+  With Advantage+, age.min cannot exceed 25 and age.max cannot be below 65.
+  To use exact age ranges, disable Advantage+ for age:
+    --data '{"targeting":{"age":{"min":25,"max":55},"expand":{"age":false}}}'
+
+Examples:
+  adkit manage meta adsets create --campaign cmp_abc --name "US Broad" \\
+    --optimization conversions --event-type purchase --countries US --budget-daily 20 --publish
+  adkit manage meta adsets create --campaign cmp_abc --name "US SaaS" \\
+    --optimization conversions --event-type purchase --countries US \\
+    --interest "6003344765839" --interest "6003127206524" --budget-daily 20 --publish
+  adkit manage meta adsets create --data '{
+    "campaignId":"cmp_abc","name":"US SaaS 25-55",
+    "budget":{"daily":30},"optimization":"conversions",
+    "promotedObject":{"pixelId":"px_123","customEventType":"PURCHASE"},
+    "targeting":{"countries":["US"],"age":{"min":25,"max":55},
+      "expand":{"age":false},"interests":["6003279598823"]}
+  }' --publish
+  adkit manage meta adsets update as_xyz --budget-daily 50
+  adkit manage meta adsets delete as_xyz`;
+// --- Ads ---
+const ADS_HELP = `adkit manage meta ads — Meta ads
+
+  list                List ads
+  create              Create an ad
+  update <id>         Update an ad
+  delete <id>         Delete an ad
+
+Flags (create — new creative from media):
+  --adset <id>        Ad set ID (required)
+  --media <path|url>  Media file or URL (repeatable). Handles upload + processing automatically
+  --primary-text <t>  Ad body text (repeatable)
+  --headline <text>   Headline text (repeatable)
+  --description <t>   Description text (repeatable, optional)
+${FLAG.cta}
+  --name <name>       Ad name
+  --url <url>         Landing page URL
+  --page <id>         Facebook Page ID (auto-resolved from account defaults)
+
+Flags (create — existing creative):
+  --adset <id>        Ad set ID (required)
+  --creative <id>     Existing creative ID
+  --name <name>       Ad name
+
+Flags (list):
+  --adset <id>        Filter by ad set ID
+
+Examples:
+  adkit manage meta ads create --adset as_789 \\
+    --media ./hero.mp4 --primary-text "Try it free" --headline "Get started" \\
+    --cta sign_up --url https://example.com --publish
+  adkit manage meta ads create --adset as_789 --creative cr_abc --name "Hero v1" --publish
+  adkit manage meta ads list --adset as_xyz
+  adkit manage meta ads update ad_123 --data '{"status":"paused"}'
+  adkit manage meta ads delete ad_123
+
+Run --help full for all fields and advanced options.`;
+const ADS_HELP_FULL = `adkit manage meta ads — Meta ads
+
+  list                List ads
+  create              Create an ad
+  update <id>         Update an ad
+  delete <id>         Delete an ad
+
+Flags (create — new creative from media):
+  --adset <id>        Ad set ID (required)
+  --media <path|url>  Media file or URL (repeatable). Handles upload + processing automatically
+  --primary-text <t>  Ad body text (repeatable)
+  --headline <text>   Headline text (repeatable)
+  --description <t>   Description text (repeatable, optional)
+${FLAG.cta}
+  --name <name>       Ad name
+  --url <url>         Landing page URL
+  --page <id>         Facebook Page ID (auto-resolved from account defaults)
+
+Flags (create — existing creative):
+  --adset <id>        Ad set ID (required)
+  --creative <id>     Existing creative ID
+  --name <name>       Ad name
+
+Flags (list):
+  --adset <id>        Filter by ad set ID
+
+--data JSON fields:
+  adsetId             (required) Parent ad set ID
+  name                (required) Ad name
+  status              active, paused, archived, deleted
+  creative            { creativeId: "cr_..." } — reference existing creative
+  platformOverrides   Raw Meta API fields merged onto the payload
+
+Examples:
+  adkit manage meta ads create --adset as_789 \\
+    --media ./hero.mp4 --primary-text "Try it free" --headline "Get started" \\
+    --cta sign_up --url https://example.com --publish
+  adkit manage meta ads create --adset as_789 --creative cr_abc --name "Hero v1" --publish
+  adkit manage meta ads create --data '{"adsetId":"as_xyz","creative":{"creativeId":"cr_abc"},"name":"Hero v1"}' --publish
+  adkit manage meta ads list --adset as_xyz
+  adkit manage meta ads update ad_123 --data '{"status":"paused"}'
+  adkit manage meta ads delete ad_123`;
+// --- Creatives ---
+const CREATIVE_HELP = `adkit manage meta creatives — Meta ad creatives
+
+Prefer using "ads create --media" which handles creative creation automatically.
+
+  create              Create an ad creative
+  update <id>         Update an ad creative
+  delete <id>         Delete an ad creative
+
+Flags (create/update):
+  --page-id <id>      Facebook Page ID (required for create)
+  --headline <text>   Ad headline (required for create)
+  --primary-text <t>  Ad body text (required for create, repeatable)
+  --link-url <url>    Destination URL (required for create)
+${FLAG.cta}
+  --name <name>       Creative name
+  --image-hash <hash> Image hash from media upload
+  --image-url <url>   Image URL
+  --video-id <id>     Video ID from media upload
+
+Examples:
+  adkit manage meta creatives create --page-id pg_123 --headline "Get Started" \\
+    --primary-text "Try it free" --link-url https://example.com \\
+    --cta sign_up --image-hash abc123 --publish
+  adkit manage meta creatives update cr_abc --primary-text "Start free trial"
+  adkit manage meta creatives delete cr_abc
+
+Run --help full for all fields and advanced options.`;
+const CREATIVE_HELP_FULL = `adkit manage meta creatives — Meta ad creatives
+
+Prefer using "ads create --media" which handles creative creation automatically.
+
+  create              Create an ad creative
+  update <id>         Update an ad creative
+  delete <id>         Delete an ad creative
+
+Flags (create/update):
+  --page-id <id>      Facebook Page ID (required for create)
+  --headline <text>   Ad headline (required for create)
+  --primary-text <t>  Ad body text (required for create, repeatable)
+  --link-url <url>    Destination URL (required for create)
+${FLAG.cta}
+  --name <name>       Creative name
+  --link-description <t> Link description (repeatable, optional)
+  --image-hash <hash> Image hash from media upload
+  --image-url <url>   Image URL
+  --video-id <id>     Video ID from media upload
+
+--data JSON fields:
+  thumbnailUrl         (string) Video thumbnail URL
+  pixelId              (string) Pixel ID for conversion tracking
+  variants             Multi-variant creative:
+                       images (string[]), videos (string[]), texts (string[]),
+                       headlines (string[]), descriptions (string[]),
+                       ctas (string[]), linkUrls (string[])
+
+Examples:
+  adkit manage meta creatives create --page-id pg_123 --headline "Get Started" \\
+    --primary-text "Try it free" --link-url https://example.com \\
+    --cta sign_up --image-hash abc123 --publish
+  adkit manage meta creatives create --data '{
+    "pageId":"pg_123","name":"Multi-variant test",
+    "headline":"Get Started","primaryText":"Try it free",
+    "linkUrl":"https://example.com","cta":"sign_up",
+    "imageHash":"abc123","pixelId":"px_456"
+  }' --publish
+  adkit manage meta creatives update cr_abc --primary-text "Start free trial"
+  adkit manage meta creatives delete cr_abc`;
+// ---------------------------------------------------------------------------
+// Composed HELP and HELP_FULL
+// ---------------------------------------------------------------------------
+const HELP = {
+    'meta accounts': `adkit manage meta accounts — Meta ad accounts
+
+  list                List connected ad accounts
+  connect <id>        Connect an ad account
+  disconnect <id>     Disconnect an ad account
+  <id> pages          List Facebook Pages for an account
+  <id> pixels         List Meta Pixels for an account
+
+Examples:
+  adkit manage meta accounts list
+  adkit manage meta accounts connect act_123456789
+  adkit manage meta accounts act_123456789 pages
+  adkit manage meta accounts disconnect act_123456789`.trim(),
+    'meta campaigns': CAMPAIGN_HELP,
+    'meta adsets': ADSET_HELP,
+    'meta ads': ADS_HELP,
+    'meta creatives': CREATIVE_HELP,
+    'meta media': `adkit manage meta media — Upload media to Meta
+
+  upload              Upload an image or video
+
+Flags:
+  --file <path>       Local file to upload
+  --url <url>         Image URL to upload
+
+Examples:
+  adkit manage meta media upload --file ./hero-video.mp4
+  adkit manage meta media upload --url https://example.com/hero.png`.trim(),
+    'meta interests': `adkit manage meta interests — Search targeting interests
+
+  search <query>      Search for interests (multiple queries supported)
+
+Output: Returns id and name for each interest. Use the id with --interest flag.
+
+Examples:
+  adkit manage meta interests search "yoga"
+  adkit manage meta interests search "saas" "marketing" "digital ads"`.trim(),
+    manage: `adkit manage — Ad platform management
+
+Platforms:
+  meta                Meta (Facebook/Instagram) ads
+  drafts              Manage drafts across platforms
+
+Run adkit manage <platform> --help for details.`.trim(),
+    meta: `adkit manage meta — Meta Ads management
+
+Entity groups:
+  accounts            List connected ad accounts
+  campaigns           Manage campaigns
+  adsets              Manage ad sets
+  ads                 Manage ads
+  creatives           Manage ad creatives (prefer using ads --media directly)
+  interests           Search targeting interests
+
+General flags (all create/update commands):
+${FLAG.account}
+${FLAG.publish}
+${FLAG.data}
+
+Mutations are draft-first by default. Use --publish to publish immediately.
+Run adkit manage meta <group> --help for details.`.trim(),
+    drafts: `adkit manage drafts — Manage drafts
+
+  list                List all drafts
+  get <id>            Get a draft by ID
+  publish <id>        Publish a draft
+  delete <id>         Delete a draft
+
+Flags (list):
+  --platform <name>   Filter by platform
+  --limit <n>         Max results
+  --offset <n>        Pagination offset
+
+Examples:
+  adkit manage drafts list --platform meta --limit 10
+  adkit manage drafts publish dft_abc123
+  adkit manage drafts delete dft_abc123`.trim(),
+    status: `adkit status — Show project context and connected accounts
+
+Displays project name, connected platforms, and ad accounts with defaults.
+AI agents should call this first to understand the context.
+
+Examples:
+  adkit status
+  adkit status --json`.trim(),
+    projects: `adkit projects — Manage projects
+
+  list                List all configured projects
+  use <id>            Switch active project
+  current             Show active project
+
+Examples:
+  adkit projects list
+  adkit projects use proj_abc123`.trim(),
+};
+const HELP_FULL = {
+    'meta campaigns': CAMPAIGN_HELP_FULL,
+    'meta adsets': ADSET_HELP_FULL,
+    'meta ads': ADS_HELP_FULL,
+    'meta creatives': CREATIVE_HELP_FULL,
+};
+function getBaseUrl() {
+    return process.env.ADKIT_BASE_URL || DEFAULT_BASE_URL;
+}
+function wantsJson(flags) {
+    return flags.json === true || !(process.stdout.isTTY ?? false);
+}
+function requireClient(flags) {
+    const projectFlag = typeof flags.project === 'string' ? flags.project : undefined;
+    const { apiKey } = resolveConfig({ project: projectFlag });
+    if (!apiKey)
+        throw new CliError('NOT_AUTHENTICATED', 'No API key found', 'Run: adkit setup');
+    return new AdkitClient({ apiKey, baseUrl: getBaseUrl() });
+}
+function printList(data, flags, emptyHint = 'No results.') {
+    const rows = unwrapList(data);
+    const fields = typeof flags.fields === 'string' ? flags.fields.split(',') : undefined;
+    const output = formatOutput(rows, { fields, json: wantsJson(flags) });
+    if (output)
+        console.log(output);
+    else
+        console.log(emptyHint);
+}
+function hasArrayValues(v) {
+    return v !== null && typeof v === 'object' && !Array.isArray(v) && Object.values(v).some(Array.isArray);
+}
+function printResult(data, flags, emptyHint) {
+    if (data === undefined) {
+        console.log('Done.');
+        return;
+    }
+    if (wantsJson(flags))
+        console.log(JSON.stringify(data));
+    else if (Array.isArray(data) || hasArrayValues(data))
+        printList(data, flags, emptyHint);
+    else
+        console.log(JSON.stringify(data, null, 2));
+}
+function showHelp(key, full = false) {
+    const text = full ? HELP_FULL[key] || HELP[key] : HELP[key];
+    if (text) {
+        console.log(text);
+        return true;
+    }
+    return false;
+}
+async function main() {
+    const { args, flags } = parseArgs(process.argv.slice(2), {
+        multi: ['media', 'primary-text', 'headline', 'description', 'link-description', 'interest'],
+    });
+    if (args.length === 0) {
+        console.log(USAGE);
+        process.exit(0);
+    }
+    // Top-level --help with no command
+    if (flags.help && args.length === 0) {
+        console.log(USAGE);
+        process.exit(0);
+    }
+    try {
+        // --- status ---
+        if (args[0] === 'status') {
+            const client = requireClient(flags);
+            await status(client, wantsJson(flags));
+            return;
+        }
+        // --- manage commands (platform management) ---
+        if (args[0] === 'manage') {
+            const manageTarget = args[1];
+            if (flags.help && !manageTarget) {
+                showHelp('manage', flags.help === 'full');
+                process.exit(0);
+            }
+            if (!manageTarget) {
+                showHelp('manage', flags.help === 'full');
+                process.exit(0);
+            }
+            // --- manage drafts ---
+            if (manageTarget === 'drafts') {
+                const action = args[2];
+                const restArgs = args.slice(3);
+                if (flags.help) {
+                    showHelp('drafts', flags.help === 'full');
+                    process.exit(0);
+                }
+                const client = requireClient(flags);
+                let data;
+                let emptyHint;
+                switch (action) {
+                    case 'list':
+                    case undefined:
+                        data = await listDrafts(client, restArgs, flags);
+                        emptyHint = 'No drafts found. Drafts are created automatically when you create or update ads without `--publish`.';
+                        break;
+                    case 'get':
+                        data = await getDraft(client, restArgs, flags);
+                        break;
+                    case 'publish':
+                        data = await publishDraft(client, restArgs, flags);
+                        break;
+                    case 'delete':
+                        data = await deleteDraft(client, restArgs, flags);
+                        break;
+                    default:
+                        throw new CliError('UNKNOWN_COMMAND', `Unknown action: manage drafts ${action}`, 'Available: list, get, publish, delete');
+                }
+                printResult(data, flags, emptyHint);
+                return;
+            }
+            // --- manage <platform> (meta, google, etc.) ---
+            const platform = manageTarget;
+            if (platform !== 'meta')
+                throw new CliError('UNKNOWN_COMMAND', `Unknown platform: ${platform}`, 'Available: meta');
+            const entity = args[2];
+            const action = args[3];
+            const restArgs = args.slice(4);
+            // Help routing
+            if (flags.help) {
+                const helpKey = entity ? `meta ${entity}` : 'meta';
+                if (showHelp(helpKey, flags.help === 'full'))
+                    process.exit(0);
+                console.log(USAGE);
+                process.exit(0);
+            }
+            if (!entity) {
+                showHelp('meta', flags.help === 'full');
+                process.exit(0);
+            }
+            const client = requireClient(flags);
+            let data;
+            let emptyHint;
+            switch (entity) {
+                case 'accounts': {
+                    // Special case: meta accounts <id> pages/pixels
+                    if (action && action !== 'list' && action !== 'connect' && action !== 'disconnect') {
+                        const accountId = action;
+                        const sub = args[4];
+                        if (sub === 'pages') {
+                            data = await listPages(client, [accountId], flags);
+                            emptyHint = 'No Facebook Pages found for this account.';
+                        }
+                        else if (sub === 'pixels') {
+                            data = await listPixels(client, [accountId], flags);
+                            emptyHint = 'No Meta Pixels found for this account.';
+                        }
+                        else
+                            throw new CliError('UNKNOWN_COMMAND', `Unknown subcommand: meta accounts ${accountId} ${sub ?? ''}`, 'Expected: pages or pixels');
+                        break;
+                    }
+                    switch (action) {
+                        case 'list':
+                        case undefined:
+                            data = await listAccounts(client, restArgs, flags);
+                            emptyHint = 'No Meta ad accounts connected. Run `adkit setup manage` or connect via https://app.adkit.so/settings/integrations';
+                            break;
+                        case 'connect':
+                            data = await connectAccount(client, restArgs, flags);
+                            break;
+                        case 'disconnect':
+                            data = await disconnectAccount(client, restArgs, flags);
+                            break;
+                        default:
+                            throw new CliError('UNKNOWN_COMMAND', `Unknown action: meta accounts ${action}`, 'Run: adkit manage meta accounts --help');
+                    }
+                    break;
+                }
+                case 'campaigns': {
+                    if (!action) {
+                        showHelp('meta campaigns', flags.help === 'full');
+                        process.exit(0);
+                    }
+                    switch (action) {
+                        case 'list':
+                            data = await listCampaigns(client, restArgs, flags);
+                            emptyHint = 'No campaigns found. Create one with `adkit manage meta campaigns create --name "My Campaign" --objective sales --publish`.';
+                            break;
+                        case 'create':
+                            data = await createCampaign(client, restArgs, flags);
+                            break;
+                        case 'update':
+                            data = await updateCampaign(client, restArgs, flags);
+                            break;
+                        case 'delete':
+                            data = await deleteCampaign(client, restArgs, flags);
+                            break;
+                        default:
+                            throw new CliError('UNKNOWN_COMMAND', `Unknown action: meta campaigns ${action}`, 'Run: adkit manage meta campaigns --help');
+                    }
+                    break;
+                }
+                case 'adsets': {
+                    if (!action) {
+                        showHelp('meta adsets', flags.help === 'full');
+                        process.exit(0);
+                    }
+                    switch (action) {
+                        case 'list':
+                            data = await listAdSets(client, restArgs, flags);
+                            emptyHint = 'No ad sets found. Create one with `adkit manage meta adsets create --campaign cmp_123 --name "My AdSet" --publish`.';
+                            break;
+                        case 'create':
+                            data = await createAdSet(client, restArgs, flags);
+                            break;
+                        case 'update':
+                            data = await updateAdSet(client, restArgs, flags);
+                            break;
+                        case 'delete':
+                            data = await deleteAdSet(client, restArgs, flags);
+                            break;
+                        default:
+                            throw new CliError('UNKNOWN_COMMAND', `Unknown action: meta adsets ${action}`, 'Run: adkit manage meta adsets --help');
+                    }
+                    break;
+                }
+                case 'ads': {
+                    if (!action) {
+                        showHelp('meta ads', flags.help === 'full');
+                        process.exit(0);
+                    }
+                    switch (action) {
+                        case 'list':
+                            data = await listAds(client, restArgs, flags);
+                            emptyHint = 'No ads found. Create one with `adkit manage meta ads create --data \'{"adsetId":"as_123","creativeId":"cr_123","name":"My Ad"}\'`.';
+                            break;
+                        case 'create':
+                            data = await createAd(client, restArgs, flags);
+                            break;
+                        case 'update':
+                            data = await updateAd(client, restArgs, flags);
+                            break;
+                        case 'delete':
+                            data = await deleteAd(client, restArgs, flags);
+                            break;
+                        default:
+                            throw new CliError('UNKNOWN_COMMAND', `Unknown action: meta ads ${action}`, 'Run: adkit manage meta ads --help');
+                    }
+                    break;
+                }
+                case 'creatives': {
+                    switch (action) {
+                        case 'create':
+                            data = await createCreative(client, restArgs, flags);
+                            break;
+                        case 'update':
+                            data = await updateCreative(client, restArgs, flags);
+                            break;
+                        case 'delete':
+                            data = await deleteCreative(client, restArgs, flags);
+                            break;
+                        default:
+                            throw new CliError('UNKNOWN_COMMAND', `Unknown action: meta creatives ${action ?? 'list'}`, 'Available: create, update, delete');
+                    }
+                    break;
+                }
+                case 'media': {
+                    switch (action) {
+                        case 'upload':
+                            data = await uploadMedia(client, restArgs, flags);
+                            break;
+                        case 'list':
+                            data = await listMedia(client, restArgs, flags);
+                            emptyHint = 'No media found for this account.';
+                            break;
+                        case 'delete':
+                            data = await deleteMedia(client, restArgs, flags);
+                            break;
+                        default:
+                            throw new CliError('UNKNOWN_COMMAND', `Unknown action: meta media ${action ?? ''}`, 'Available: upload, list, delete');
+                    }
+                    break;
+                }
+                case 'interests': {
+                    switch (action) {
+                        case 'search':
+                            data = await searchInterests(client, restArgs, flags);
+                            emptyHint = 'No interests found for that query.';
+                            break;
+                        default:
+                            throw new CliError('UNKNOWN_COMMAND', `Unknown action: meta interests ${action ?? ''}`, 'Available: search');
+                    }
+                    break;
+                }
+                default:
+                    throw new CliError('UNKNOWN_COMMAND', `Unknown entity: meta ${entity}`, 'Available: accounts, campaigns, adsets, ads, creatives, media, interests');
+            }
+            printResult(data, flags, emptyHint);
+            return;
+        }
+        // --- projects commands ---
+        if (args[0] === 'projects') {
+            const action = args[1];
+            if (flags.help) {
+                showHelp('projects', flags.help === 'full');
+                process.exit(0);
+            }
+            switch (action) {
+                case 'list':
+                case undefined: {
+                    const config = readConfig() ?? {};
+                    const projects = listProjects(config);
+                    if (projects.length === 0)
+                        console.log('No projects configured. Run `adkit setup` to set up your first project.');
+                    else {
+                        for (const p of projects) {
+                            const marker = p.current ? '* ' : '  ';
+                            console.log(`${marker}${p.name} (${p.id})`);
+                        }
+                    }
+                    break;
+                }
+                case 'current': {
+                    const config = readConfig() ?? {};
+                    const project = currentProject(config);
+                    if (!project)
+                        console.log('No project selected. Run `adkit projects use <id>`.');
+                    else
+                        console.log(`Active project: ${project.name} (${project.id})`);
+                    break;
+                }
+                case 'use': {
+                    const projectId = args[2];
+                    if (!projectId)
+                        throw new CliError('MISSING_ARGUMENT', 'Missing required argument: `<project-id>`', 'Run: adkit projects use <project-id>');
+                    useProject(projectId);
+                    console.log(`Switched to project: ${projectId}`);
+                    break;
+                }
+                default:
+                    throw new CliError('UNKNOWN_COMMAND', `Unknown action: projects ${action}`, 'Available: list, use, current');
+            }
+            return;
+        }
+        // --- logout ---
+        if (args[0] === 'logout') {
+            logout();
+            return;
+        }
+        // --- setup (auth + onboarding) ---
+        if (args[0] === 'setup') {
+            const scope = args.slice(1); // e.g. ['manage'], ['manage', 'studio'], or []
+            await login({ baseUrl: getBaseUrl(), scope });
+            return;
+        }
+        // --- fallback ---
+        throw new CliError('UNKNOWN_COMMAND', `Unknown command: ${args.join(' ')}`, 'Run: adkit --help');
+    }
+    catch (err) {
+        const jsonErrors = wantsJson(flags);
+        if (err instanceof CliError) {
+            if (!jsonErrors) {
+                console.error(`Error: ${err.message}`);
+                if (err.suggestion)
+                    console.error(`Suggestion: ${err.suggestion}`);
+            }
+            else {
+                console.error(JSON.stringify({
+                    error: true,
+                    code: err.code,
+                    message: err.message,
+                    ...(err.suggestion && { suggestion: err.suggestion }),
+                }));
+            }
+        }
+        else {
+            const message = err instanceof Error ? err.message : String(err);
+            if (!jsonErrors)
+                console.error(`Error: ${message}`);
+            else {
+                console.error(JSON.stringify({
+                    error: true,
+                    code: 'UNKNOWN',
+                    message,
+                }));
+            }
+        }
+        const EXIT_CODES = {
+            MISSING_ARGUMENT: 2,
+            MISSING_FLAG: 2,
+            INVALID_VALUE: 2,
+            UNKNOWN_COMMAND: 2,
+            UNKNOWN_FLAG: 2,
+            NOT_FOUND: 3,
+            INVALID_API_KEY: 4,
+            NOT_AUTHENTICATED: 4,
+        };
+        process.exit(err instanceof CliError ? (EXIT_CODES[err.code] ?? 1) : 1);
+    }
+}
+void main();