cli-meta-ads 0.1.0

package/REQUIREMENTS.md

@@ -0,0 +1,148 @@
+# CLI-meta-ads Requirements Snapshot
+
+This file is a compact product and scope snapshot for the CLI. It is intentionally shorter than the README and more stable than day-to-day implementation notes.
+
+## Product intent
+
+- Tool: Meta Ads CLI for Facebook and Instagram surfaces
+- API: Meta Marketing API
+- Runtime: Node.js CLI
+- Primary human auth model: Facebook Login for Business user token stored in local config
+- Primary automation auth model: pre-generated Meta access token, typically a system-user token
+- Safety model: read-first, draft-first, approval-gated for sensitive writes
+
+## Target users
+
+| User or agent | Typical mode | Typical use cases |
+| --- | --- | --- |
+| Ad operations | write | Performance review, budget changes, launch execution, creative diagnostics |
+| Designers or creative teams | read | Creative performance and fatigue visibility |
+| Client-facing reporting users | read | Account, campaign, and report visibility |
+| Tracking / QA owners | read | Pixel and best-effort CAPI checks |
+
+## Current command scope
+
+### Read flows
+
+```bash
+meta performance --account <ad-account-id> --last 7d
+meta performance --account <ad-account-id> --campaign "Retargeting" --last 30d
+meta performance --account all --last 7d
+meta performance --account <id> --breakdown age,gender --last 30d
+
+meta campaigns list --account <id>
+meta campaigns get <campaign-id>
+
+meta ads list --campaign <id>
+meta ads performance --campaign <id> --last 30d --sort ctr
+meta ads fatigue --campaign <id> --last 30d
+meta ads preview <ad-id>
+
+meta anomalies --account <id> --threshold 20
+meta anomalies --account all --threshold 30
+
+meta pixel status --account <id>
+meta pixel events --account <id> --last 24h
+meta capi status --account <id>
+meta capi events --account <id> --last 24h
+
+meta audiences list --account <id>
+meta audiences size --audience <id>
+
+meta report daily --account <id>
+meta report weekly --account <id>
+meta report monthly --account <id>
+
+meta auth login
+meta auth status
+meta auth logout
+meta whoami
+meta doctor --account <id>
+meta verify-api --account <id>
+```
+
+### Create, upload, and launch flows
+
+```bash
+meta assets images upload --account <id> --file ./hero.png
+meta assets videos upload --account <id> --file ./spot.mp4 --wait
+
+meta campaigns create --account <id> --spec ./campaign.json
+meta adsets create --account <id> --spec ./adset.json
+meta creatives create --account <id> --spec ./creative.json
+meta ads create --account <id> --spec ./ad.json
+
+meta launch validate --account <id> --spec ./launch.json
+meta launch plan --account <id> --spec ./launch.json
+meta launch apply --account <id> --spec ./launch.json
+meta launch resume --receipt ./.meta-launch/<execution-id>.json
+```
+
+### Approval-gated changes
+
+```bash
+meta campaigns pause <campaign-id>
+meta campaigns enable <campaign-id>
+meta campaigns budget <campaign-id> --daily 50
+```
+
+## Permission model
+
+```yaml
+modes:
+  read:
+    - performance
+    - campaigns list/get
+    - ads list/performance/fatigue/preview
+    - anomalies
+    - pixel/capi status/events
+    - audiences list/size
+    - reports
+    - launch validate/plan
+
+  write:
+    - everything in read
+    - assets upload
+    - campaigns/adsets/creatives/ads create
+    - launch apply/resume
+    - campaigns budget direct write only when the change is <= 20%
+
+  admin:
+    - reserved for future expansion
+    - not intended as the default agent mode
+```
+
+## Multi-account behavior
+
+The CLI supports multiple Meta ad accounts through Business Manager discovery:
+
+```bash
+meta accounts list
+meta accounts set-default <ad-account-id>
+meta performance --account all
+```
+
+Only explicit multi-account read surfaces support `--account all`. Single-account commands reject it.
+
+## Environment variables
+
+```bash
+META_ACCESS_TOKEN=
+META_APP_ID=
+META_AUTH_CONFIG_ID=
+META_AUTH_REDIRECT_URI=https://www.facebook.com/connect/login_success.html
+META_APP_SECRET=
+META_CLI_MODE=read
+META_APPROVAL_WEBHOOK=
+META_API_VERSION=v25.0
+META_DEFAULT_ACCOUNT_ID=
+META_OUTPUT_FORMAT=text
+```
+
+## Delivery constraints
+
+- No live credentials are stored in the repository.
+- No hidden host-local env files should be auto-loaded.
+- Approval webhooks must remain HTTPS-only.
+- Draft mode must remain the default for mutations.
+- The npm artifact should stay free of repo-local artifacts and accidental internal files.

package/dist/auth/constants.d.ts

@@ -0,0 +1 @@
+export declare const DEFAULT_AUTH_REDIRECT_URI = "https://www.facebook.com/connect/login_success.html";

package/dist/auth/constants.js

@@ -0,0 +1 @@
+export const DEFAULT_AUTH_REDIRECT_URI = "https://www.facebook.com/connect/login_success.html";

package/dist/auth/guards.d.ts

@@ -0,0 +1,5 @@
+import type { PermissionMode } from "../types.js";
+import type { ResolvedConfig } from "../config/types.js";
+export declare function hasPermission(current: PermissionMode, required: PermissionMode): boolean;
+export declare function requirePermission(config: ResolvedConfig, required: PermissionMode, operation: string): void;
+export declare function requireAccessToken(config: ResolvedConfig): string;

package/dist/auth/guards.js

@@ -0,0 +1,16 @@
+import { AppError, ExitCode } from "../utils/errors.js";
+const PERMISSION_ORDER = ["read", "write", "admin"];
+export function hasPermission(current, required) {
+    return PERMISSION_ORDER.indexOf(current) >= PERMISSION_ORDER.indexOf(required);
+}
+export function requirePermission(config, required, operation) {
+    if (!hasPermission(config.permissionMode, required)) {
+        throw new AppError(`${operation} requires ${required} mode. Current mode is ${config.permissionMode}.`, ExitCode.Permission);
+    }
+}
+export function requireAccessToken(config) {
+    if (!config.accessToken) {
+        throw new AppError("A Meta access token is required for Meta API operations. Set META_ACCESS_TOKEN or run auth login.", ExitCode.Auth);
+    }
+    return config.accessToken;
+}

package/dist/auth/login.d.ts

@@ -0,0 +1,28 @@
+import { type FetchLike } from "../client/meta-api-client.js";
+import type { ResolvedConfig } from "../config/types.js";
+export interface InteractiveAuthLoginOptions {
+    appId?: string | undefined;
+    configId?: string | undefined;
+    openBrowser?: boolean | undefined;
+    redirectUri?: string | undefined;
+}
+export interface InteractiveAuthLoginResult {
+    accessToken: string;
+    accessTokenExpiresAt?: string | undefined;
+    appId: string;
+    authConfigId: string;
+    authRedirectUri: string;
+    browserOpened: boolean;
+    codeExchangeUsed: boolean;
+    loginUrl: string;
+}
+export interface AuthLoginDeps {
+    fetchImpl?: FetchLike | undefined;
+    now?: (() => Date) | undefined;
+    openUrl?: ((url: string) => Promise<boolean>) | undefined;
+    promptForCallback?: ((loginUrl: string) => Promise<string>) | undefined;
+    randomBytes?: ((size: number) => Buffer) | undefined;
+}
+export declare function defaultPromptForCallback(loginUrl: string): Promise<string>;
+export declare function openExternalBrowser(url: string): Promise<boolean>;
+export declare function runInteractiveAuthLogin(config: ResolvedConfig, options?: InteractiveAuthLoginOptions, deps?: AuthLoginDeps): Promise<InteractiveAuthLoginResult>;

package/dist/auth/login.js

@@ -0,0 +1,222 @@
+import { execFile } from "node:child_process";
+import { randomBytes as defaultRandomBytes } from "node:crypto";
+import { createInterface } from "node:readline/promises";
+import process from "node:process";
+import { promisify } from "node:util";
+import { AppError, ExitCode } from "../utils/errors.js";
+import { normalizeAuthRedirectUri } from "../utils/security.js";
+import { DEFAULT_AUTH_REDIRECT_URI } from "./constants.js";
+const execFileAsync = promisify(execFile);
+function normalizeOptionalString(value) {
+    if (value === undefined) {
+        return undefined;
+    }
+    const normalized = value.trim();
+    return normalized.length > 0 ? normalized : undefined;
+}
+function resolveLoginOptions(config, options) {
+    const appId = normalizeOptionalString(options.appId) ?? normalizeOptionalString(config.appId);
+    if (!appId) {
+        throw new AppError("auth login requires a Meta app ID. Set META_APP_ID, store appId in config, or pass --app-id.", ExitCode.Config);
+    }
+    const authConfigId = normalizeOptionalString(options.configId) ?? normalizeOptionalString(config.authConfigId);
+    if (!authConfigId) {
+        throw new AppError("auth login requires a Facebook Login for Business configuration ID. Set META_AUTH_CONFIG_ID, store authConfigId in config, or pass --config-id.", ExitCode.Config);
+    }
+    const authRedirectUri = normalizeOptionalString(options.redirectUri)
+        ? normalizeAuthRedirectUri(options.redirectUri ?? "", "--redirect-uri")
+        : normalizeOptionalString(config.authRedirectUri)
+            ?? DEFAULT_AUTH_REDIRECT_URI;
+    return {
+        appId,
+        authConfigId,
+        authRedirectUri
+    };
+}
+function buildLoginUrl(config, options, state) {
+    const url = new URL(`https://www.facebook.com/${config.apiVersion}/dialog/oauth`);
+    url.searchParams.set("client_id", options.appId);
+    url.searchParams.set("redirect_uri", options.authRedirectUri);
+    url.searchParams.set("state", state);
+    url.searchParams.set("config_id", options.authConfigId);
+    return url.toString();
+}
+function promptLabel(loginUrl) {
+    return [
+        "",
+        "Complete the Meta login in your browser.",
+        "After the flow finishes, copy the final redirect URL from the browser address bar and paste it below.",
+        "",
+        `Login URL: ${loginUrl}`,
+        "",
+        "Paste final redirect URL: "
+    ].join("\n");
+}
+export async function defaultPromptForCallback(loginUrl) {
+    if (!process.stdin.isTTY) {
+        throw new AppError("auth login requires interactive stdin so the browser callback URL can be pasted back into the CLI.", ExitCode.Auth);
+    }
+    const prompt = createInterface({
+        input: process.stdin,
+        output: process.stderr
+    });
+    try {
+        const response = await prompt.question(promptLabel(loginUrl));
+        return response.trim();
+    }
+    finally {
+        prompt.close();
+    }
+}
+export async function openExternalBrowser(url) {
+    try {
+        if (process.platform === "darwin") {
+            await execFileAsync("open", [url]);
+            return true;
+        }
+        if (process.platform === "win32") {
+            await execFileAsync("rundll32", ["url.dll,FileProtocolHandler", url]);
+            return true;
+        }
+        await execFileAsync("xdg-open", [url]);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function readResponseParams(callbackUrl) {
+    if (callbackUrl.hash.startsWith("#")) {
+        return new URLSearchParams(callbackUrl.hash.slice(1));
+    }
+    return callbackUrl.searchParams;
+}
+function parsePositiveInteger(value) {
+    if (!value) {
+        return undefined;
+    }
+    const parsed = Number.parseInt(value, 10);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : undefined;
+}
+function parseCallbackUrl(rawValue) {
+    const trimmed = rawValue.trim();
+    try {
+        return new URL(trimmed);
+    }
+    catch {
+        throw new AppError("Could not parse the login callback. Paste the full final redirect URL from the browser address bar.", ExitCode.Auth);
+    }
+}
+function hasExpectedQueryParams(callbackUrl, expectedRedirectUrl) {
+    for (const [key, expectedValue] of expectedRedirectUrl.searchParams.entries()) {
+        const callbackValues = callbackUrl.searchParams.getAll(key);
+        if (!callbackValues.includes(expectedValue)) {
+            return false;
+        }
+    }
+    return true;
+}
+function assertCallbackMatchesRedirectUri(callbackUrl, expectedRedirectUri) {
+    const expectedRedirectUrl = new URL(expectedRedirectUri);
+    const matchesTarget = callbackUrl.origin === expectedRedirectUrl.origin
+        && callbackUrl.pathname === expectedRedirectUrl.pathname
+        && callbackUrl.username === expectedRedirectUrl.username
+        && callbackUrl.password === expectedRedirectUrl.password
+        && hasExpectedQueryParams(callbackUrl, expectedRedirectUrl);
+    if (!matchesTarget) {
+        throw new AppError(`The pasted callback URL did not match the configured redirect URI (${expectedRedirectUri}).`, ExitCode.Auth);
+    }
+}
+function parseAuthCallback(rawValue, expectedState, expectedRedirectUri) {
+    const callbackUrl = parseCallbackUrl(rawValue);
+    assertCallbackMatchesRedirectUri(callbackUrl, expectedRedirectUri);
+    const responseParams = readResponseParams(callbackUrl);
+    const queryParams = callbackUrl.searchParams;
+    const returnedState = responseParams.get("state") ?? queryParams.get("state");
+    if (!returnedState || returnedState !== expectedState) {
+        throw new AppError("The login callback state did not match. Cancel the flow and run auth login again.", ExitCode.Auth);
+    }
+    const errorReason = responseParams.get("error_reason") ?? queryParams.get("error_reason");
+    const errorDescription = responseParams.get("error_description") ?? queryParams.get("error_description");
+    if (errorReason || errorDescription) {
+        throw new AppError(`Meta login failed: ${errorDescription ?? errorReason ?? "unknown error"}.`, ExitCode.Auth);
+    }
+    const accessToken = responseParams.get("access_token") ?? queryParams.get("access_token");
+    if (accessToken) {
+        return {
+            accessToken,
+            expiresInSeconds: parsePositiveInteger(responseParams.get("expires_in") ?? queryParams.get("expires_in"))
+        };
+    }
+    const code = queryParams.get("code") ?? responseParams.get("code");
+    if (code) {
+        return {
+            code
+        };
+    }
+    throw new AppError("Meta login did not return an access token or authorization code. Paste the full final redirect URL from the browser.", ExitCode.Auth);
+}
+async function exchangeAuthorizationCode(config, options, code, fetchImpl) {
+    const appSecret = normalizeOptionalString(config.appSecret);
+    if (!appSecret) {
+        throw new AppError("This login flow returned an authorization code. Configure META_APP_SECRET to exchange it, or switch the Meta login configuration back to the default user-token response flow.", ExitCode.Auth);
+    }
+    const exchangeUrl = new URL(`https://graph.facebook.com/${config.apiVersion}/oauth/access_token`);
+    exchangeUrl.searchParams.set("client_id", options.appId);
+    exchangeUrl.searchParams.set("redirect_uri", options.authRedirectUri);
+    exchangeUrl.searchParams.set("client_secret", appSecret);
+    exchangeUrl.searchParams.set("code", code);
+    const response = await fetchImpl(exchangeUrl.toString(), {
+        method: "GET"
+    });
+    const body = await response.json().catch(() => null);
+    if (!response.ok) {
+        const providerMessage = body && "error" in body ? body.error?.message : undefined;
+        throw new AppError(providerMessage
+            ? `Meta auth code exchange failed: ${providerMessage}`
+            : `Meta auth code exchange failed with HTTP ${response.status}.`, ExitCode.Auth);
+    }
+    if (!body || !("access_token" in body) || !body.access_token) {
+        throw new AppError("Meta auth code exchange completed without returning an access token.", ExitCode.Auth);
+    }
+    return {
+        accessToken: body.access_token,
+        expiresInSeconds: typeof body.expires_in === "number" ? body.expires_in : undefined
+    };
+}
+function toExpiresAt(now, expiresInSeconds) {
+    if (!expiresInSeconds) {
+        return undefined;
+    }
+    return new Date(now.getTime() + (expiresInSeconds * 1000)).toISOString();
+}
+export async function runInteractiveAuthLogin(config, options = {}, deps = {}) {
+    const resolvedOptions = resolveLoginOptions(config, options);
+    const randomBytes = deps.randomBytes ?? defaultRandomBytes;
+    const state = randomBytes(16).toString("hex");
+    const loginUrl = buildLoginUrl(config, resolvedOptions, state);
+    const openBrowser = options.openBrowser ?? true;
+    const browserOpened = openBrowser
+        ? await (deps.openUrl ?? openExternalBrowser)(loginUrl)
+        : false;
+    const callbackValue = await (deps.promptForCallback ?? defaultPromptForCallback)(loginUrl);
+    let authCallback = parseAuthCallback(callbackValue, state, resolvedOptions.authRedirectUri);
+    const usedAuthorizationCode = Boolean(authCallback.code);
+    if (authCallback.code) {
+        authCallback = await exchangeAuthorizationCode(config, resolvedOptions, authCallback.code, deps.fetchImpl ?? fetch);
+    }
+    if (!authCallback.accessToken) {
+        throw new AppError("Meta login did not return an access token.", ExitCode.Auth);
+    }
+    const now = deps.now ? deps.now() : new Date();
+    return {
+        accessToken: authCallback.accessToken,
+        accessTokenExpiresAt: toExpiresAt(now, authCallback.expiresInSeconds),
+        appId: resolvedOptions.appId,
+        authConfigId: resolvedOptions.authConfigId,
+        authRedirectUri: resolvedOptions.authRedirectUri,
+        browserOpened,
+        codeExchangeUsed: usedAuthorizationCode,
+        loginUrl
+    };
+}

package/dist/cli/action.d.ts

@@ -0,0 +1,11 @@
+import type { Command } from "commander";
+import { createCommandContext, type CliDeps } from "./context.js";
+import type { CommandResult } from "../types.js";
+export interface CliRuntimeState {
+    argv: string[];
+    exitCode: number;
+    preferJson: boolean;
+}
+type ActionHandler<TArgs extends unknown[]> = (context: Awaited<ReturnType<typeof createCommandContext>>, ...args: TArgs) => Promise<CommandResult<unknown>>;
+export declare function createAction<TArgs extends unknown[]>(commandName: string, deps: CliDeps, state: CliRuntimeState, handler: ActionHandler<TArgs>): (...actionArgs: [...TArgs, Command]) => Promise<void>;
+export {};

package/dist/cli/action.js

@@ -0,0 +1,77 @@
+import { createCommandContext } from "./context.js";
+import { renderFailure, renderSuccess } from "../output/render.js";
+import { ExitCode, isAppError, toFailureShape } from "../utils/errors.js";
+import { sanitizeArgvForLogs } from "../utils/security.js";
+function buildDebugPayload(commandName, state, context) {
+    return {
+        apply: context.apply,
+        argv: sanitizeArgvForLogs(state.argv),
+        command: commandName,
+        config: {
+            accessTokenPresent: Boolean(context.config.accessToken),
+            apiVersion: context.config.apiVersion,
+            approvalWebhookPresent: Boolean(context.config.approvalWebhook),
+            configPath: context.config.configPath,
+            defaultAccountId: context.config.defaultAccountId,
+            outputFormat: context.config.outputFormat,
+            permissionMode: context.config.permissionMode
+        },
+        json: context.json
+    };
+}
+function renderDebugMessage(payload) {
+    return [
+        "debug:",
+        `  command: ${payload.command}`,
+        `  argv: ${payload.argv.join(" ")}`,
+        `  apply: ${payload.apply}`,
+        `  json: ${payload.json}`,
+        `  apiVersion: ${payload.config.apiVersion}`,
+        `  permissionMode: ${payload.config.permissionMode}`,
+        `  outputFormat: ${payload.config.outputFormat}`,
+        `  defaultAccountId: ${payload.config.defaultAccountId ?? "-"}`,
+        `  configPath: ${payload.config.configPath}`,
+        `  accessTokenPresent: ${payload.config.accessTokenPresent}`,
+        `  approvalWebhookPresent: ${payload.config.approvalWebhookPresent}`
+    ].join("\n") + "\n";
+}
+export function createAction(commandName, deps, state, handler) {
+    return async (...actionArgs) => {
+        const command = actionArgs[actionArgs.length - 1];
+        const args = actionArgs.slice(0, -1);
+        const options = command.optsWithGlobals();
+        let asJson = Boolean(options.json);
+        let debugPayload;
+        try {
+            const context = await createCommandContext(options, deps);
+            asJson = context.json;
+            if (context.config.debug) {
+                debugPayload = buildDebugPayload(commandName, state, context);
+                if (!context.json) {
+                    deps.io.stderr.write(renderDebugMessage(debugPayload));
+                }
+            }
+            const result = await handler(context, ...args);
+            const success = context.json && debugPayload
+                ? {
+                    ...result,
+                    meta: {
+                        ...(result.meta ?? {}),
+                        debug: debugPayload
+                    }
+                }
+                : result;
+            deps.io.stdout.write(renderSuccess(success, context.json));
+            const requestedExitCode = typeof result.meta?.exitCode === "number"
+                ? Number(result.meta.exitCode)
+                : undefined;
+            state.exitCode = requestedExitCode
+                ?? (result.partialFailures?.length ? ExitCode.PartialFailure : ExitCode.Ok);
+        }
+        catch (error) {
+            const failure = toFailureShape(error, commandName, asJson && debugPayload ? { debug: debugPayload } : undefined);
+            deps.io.stderr.write(renderFailure(failure, asJson));
+            state.exitCode = isAppError(error) ? error.exitCode : 1;
+        }
+    };
+}

package/dist/cli/build-cli.d.ts

@@ -0,0 +1,2 @@
+import type { CliDeps } from "./context.js";
+export declare function runCli(argv: string[], deps: CliDeps): Promise<number>;

package/dist/cli/build-cli.js

@@ -0,0 +1,110 @@
+import { Command, CommanderError } from "commander";
+import { detectConfiguredOutputFormat } from "../config/file-config.js";
+import { registerAccountsCommands } from "../commands/accounts.js";
+import { registerAdSetCommands } from "../commands/adsets.js";
+import { registerAdsCommands } from "../commands/ads.js";
+import { registerAnomaliesCommand } from "../commands/anomalies.js";
+import { registerAuthCommands } from "../commands/auth.js";
+import { registerAssetCommands } from "../commands/assets.js";
+import { registerAudienceCommands } from "../commands/audiences.js";
+import { registerCampaignCommands } from "../commands/campaigns.js";
+import { registerCapiCommands } from "../commands/capi.js";
+import { registerCreativeCommands } from "../commands/creatives.js";
+import { registerDiagnosticCommands } from "../commands/diagnostics.js";
+import { registerLaunchCommands } from "../commands/launch.js";
+import { registerPerformanceCommand } from "../commands/performance.js";
+import { registerPixelCommands } from "../commands/pixel.js";
+import { registerReportCommands } from "../commands/report.js";
+import { renderFailure } from "../output/render.js";
+import { AppError, ExitCode } from "../utils/errors.js";
+import { toFailureShape } from "../utils/errors.js";
+function readOptionValue(argv, optionName) {
+    for (let index = 0; index < argv.length; index += 1) {
+        const entry = argv[index];
+        if (!entry) {
+            continue;
+        }
+        if (entry === optionName) {
+            return argv[index + 1];
+        }
+        if (entry.startsWith(`${optionName}=`)) {
+            return entry.slice(optionName.length + 1);
+        }
+    }
+    return undefined;
+}
+async function resolveJsonPreference(argv) {
+    if (argv.includes("--json")) {
+        return true;
+    }
+    if (process.env.META_OUTPUT_FORMAT) {
+        return process.env.META_OUTPUT_FORMAT === "json";
+    }
+    const configuredOutputFormat = await detectConfiguredOutputFormat(readOptionValue(argv, "--config"));
+    return configuredOutputFormat === "json";
+}
+function buildProgram(deps, state) {
+    const program = new Command();
+    program
+        .name("meta")
+        .description("Agent-ready CLI for Meta Ads reads, drafts and approval-gated writes.")
+        .showHelpAfterError()
+        .exitOverride()
+        .configureOutput({
+        writeErr: (message) => {
+            if (!state.preferJson) {
+                deps.io.stderr.write(message);
+            }
+        },
+        writeOut: (message) => {
+            deps.io.stdout.write(message);
+        }
+    })
+        .allowExcessArguments(false)
+        .option("--json", "Render machine-readable JSON output.")
+        .option("--config <path>", "Override the local CLI config path.")
+        .option("--api-version <version>", "Override the Graph/Marketing API version, e.g. v25.0.")
+        .option("--mode <mode>", "Override permission mode: read, write or admin.")
+        .option("--apply", "Apply a write. Without this flag, mutation commands stay in draft mode.")
+        .option("--debug", "Enable debug-oriented config resolution.");
+    registerAccountsCommands(program, deps, state);
+    registerAuthCommands(program, deps, state);
+    registerAssetCommands(program, deps, state);
+    registerPerformanceCommand(program, deps, state);
+    registerCampaignCommands(program, deps, state);
+    registerAdSetCommands(program, deps, state);
+    registerCreativeCommands(program, deps, state);
+    registerAdsCommands(program, deps, state);
+    registerAnomaliesCommand(program, deps, state);
+    registerPixelCommands(program, deps, state);
+    registerCapiCommands(program, deps, state);
+    registerAudienceCommands(program, deps, state);
+    registerReportCommands(program, deps, state);
+    registerLaunchCommands(program, deps, state);
+    registerDiagnosticCommands(program, deps, state);
+    return program;
+}
+export async function runCli(argv, deps) {
+    const state = {
+        argv: [...argv],
+        exitCode: 0,
+        preferJson: await resolveJsonPreference(argv)
+    };
+    const program = buildProgram(deps, state);
+    try {
+        await program.parseAsync(argv, { from: "user" });
+    }
+    catch (error) {
+        if (error instanceof CommanderError) {
+            state.exitCode = error.code === "commander.helpDisplayed" ? ExitCode.Ok : ExitCode.Usage;
+            if (state.preferJson && state.exitCode !== ExitCode.Ok) {
+                deps.io.stderr.write(renderFailure(toFailureShape(new AppError(error.message, state.exitCode), "meta"), true));
+            }
+        }
+        else {
+            deps.io.stderr.write(renderFailure(toFailureShape(error, "meta"), state.preferJson));
+            state.exitCode = 1;
+        }
+    }
+    return state.exitCode;
+}

package/dist/cli/context.d.ts

@@ -0,0 +1,24 @@
+import type { ResolvedConfig } from "../config/types.js";
+import { MetaApiClient, type FetchLike } from "../client/meta-api-client.js";
+import type { GlobalOptions } from "../types.js";
+export interface IoLike {
+    stderr: {
+        write(message: string): void;
+    };
+    stdout: {
+        write(message: string): void;
+    };
+}
+export interface CliDeps {
+    fetchImpl?: FetchLike | undefined;
+    io: IoLike;
+}
+export interface CommandContext {
+    apply: boolean;
+    client: MetaApiClient;
+    config: ResolvedConfig;
+    fetchImpl?: FetchLike | undefined;
+    io: IoLike;
+    json: boolean;
+}
+export declare function createCommandContext(options: GlobalOptions, deps: CliDeps): Promise<CommandContext>;

package/dist/cli/context.js

@@ -0,0 +1,19 @@
+import { loadResolvedConfig } from "../config/file-config.js";
+import { MetaApiClient } from "../client/meta-api-client.js";
+export async function createCommandContext(options, deps) {
+    const config = await loadResolvedConfig({
+        apiVersion: options.apiVersion,
+        configPath: options.config,
+        debug: options.debug,
+        outputFormat: options.json ? "json" : undefined,
+        permissionMode: options.mode
+    });
+    return {
+        apply: Boolean(options.apply),
+        client: new MetaApiClient(config, deps.fetchImpl),
+        config,
+        fetchImpl: deps.fetchImpl,
+        io: deps.io,
+        json: options.json ?? config.outputFormat === "json"
+    };
+}