@wrangled/cli 0.2.0

package/dist/main.js

@@ -0,0 +1,2151 @@
+#!/usr/bin/env node
+import { spawn } from "node:child_process";
+import { mkdir, readFile, stat } from "node:fs/promises";
+import { homedir } from "node:os";
+import { basename, dirname, extname, join, resolve } from "node:path";
+import { parseArgs } from "node:util";
+import { api, ApiError, apiDownload, apiText, apiUpload, CliError, exitCodes, getSigned, IMPORT_LIMITS, IMPORT_NAME_PATTERN, putSigned, readCredentials, removeCredentials, resolveApiUrl, resolveConnection, UnreadableCredentialsError, writeCredentials, } from "./api.js";
+import { brand, envPrefix } from "./brand.js";
+import { firstSymlink, inRunFolder, writeFileAtomic } from "./files.js";
+import { guide, skill } from "./guide.js";
+import { PULL_STATE_FILE, pullContent } from "./pull.js";
+import { AGENTS_MD_MARKER, META_ADS_SKILL_NAME, metaAdsAgentsMd, metaAdsPlaybook, metaAdsSkill, P3_REFRESH_SKILL_NAME, p3RefreshPlaybook, p3RefreshSkill, } from "./playbooks.js";
+import { AGENT_ENV, HARNESS_COMMAND_ENV, RUNNER_TOKEN_ENV, runLoop, runOnce } from "./runner/run.js";
+import { SKILL_NAME_PATTERN } from "./skill-zip.js";
+import { installSkillFolder, operatorConnection, packSkill, parseSkillRef, readSkillFolder, unpackSkill, } from "./skills.js";
+const DEFAULT_WAIT_SECONDS = 300;
+const SERVER_WAIT_CAP = 50;
+const commands = {
+    login: {
+        usage: `login   (paste the key when asked, pipe it on stdin, or set ${envPrefix}_API_KEY)`,
+        async run(args, options) {
+            if (args.length > 0) {
+                throw new CliError(`login takes no arguments. Pipe the key on stdin or set ${envPrefix}_API_KEY.`, exitCodes.usage);
+            }
+            const apiKey = await readKeyFromUser();
+            const stored = await readCredentials().catch((error) => {
+                if (error instanceof UnreadableCredentialsError)
+                    return null;
+                throw error;
+            });
+            const apiUrl = resolveApiUrl(options.apiUrl, stored);
+            const me = await api({ apiUrl, apiKey }, "/api/v1/me");
+            const path = await writeCredentials({ apiKey, apiUrl });
+            if (options.format === "json")
+                return printJson(me);
+            console.log(`Logged in to ${me.workspace.name} (${me.workspace.slug}) at ${apiUrl}.`);
+            console.log(`Saved credentials to ${path}.`);
+        },
+    },
+    logout: {
+        usage: "logout",
+        async run() {
+            await removeCredentials();
+            console.log("Logged out.");
+        },
+    },
+    whoami: {
+        usage: "whoami",
+        async run(_args, options) {
+            const me = await api(await resolveConnection(options.apiUrl), "/api/v1/me");
+            if (options.format === "json")
+                return printJson(me);
+            const { name, slug, id } = me.workspace;
+            console.log(renderTable(["workspace", "slug", "id"], [{ workspace: name, slug, id }]));
+        },
+    },
+    "warehouse schema": {
+        usage: "warehouse schema [--summary] [--table <name> ...] [--search <words>]",
+        async run(args, options) {
+            if (args.length !== 0)
+                throw new CliError("Usage: warehouse schema [--summary] [--table <name> ...] [--search <words>]", exitCodes.usage);
+            const query = new URLSearchParams();
+            if (options.summary)
+                query.set("summary", "1");
+            if (options.tables.length > 0)
+                query.set("tables", options.tables.join(","));
+            if (options.search !== undefined)
+                query.set("search", options.search);
+            const path = `/api/v1/warehouse/schema${query.size > 0 ? `?${query}` : ""}`;
+            const connection = await resolveConnection(options.apiUrl);
+            if (options.summary) {
+                const summary = await api(connection, path);
+                if (options.format === "json")
+                    return printJson(summary);
+                if (summary.tables.length === 0)
+                    return console.log("No tables yet.");
+                return console.log(renderTable(["table", "kind", "source", "columns", "summary"], summary.tables.map((t) => ({ table: t.name, kind: t.kind, source: t.source ?? "", columns: t.columns, summary: t.summary ?? "" }))));
+            }
+            const schema = await api(connection, path);
+            if (options.format === "json")
+                return printJson(schema);
+            if (schema.missing?.length)
+                console.error(`No such table: ${schema.missing.join(", ")}`);
+            if (schema.tables.length === 0) {
+                if (options.tables.length > 0)
+                    return;
+                return console.log(options.search === undefined ? "No tables yet." : "No tables match.");
+            }
+            const described = schema.tables.filter((t) => t.description !== null);
+            if (described.length > 0) {
+                console.log(renderTable(["table", "description"], described.map((t) => ({ table: t.name, description: t.description }))));
+                console.log("");
+            }
+            const rows = schema.tables.flatMap((table) => table.columns.map((c) => ({
+                table: table.name,
+                column: c.name,
+                type: c.type,
+                nullable: c.nullable ? "yes" : "no",
+                description: c.description ?? "",
+            })));
+            console.log(renderTable(["table", "column", "type", "nullable", "description"], rows));
+        },
+    },
+    "warehouse query": {
+        usage: 'warehouse query "<sql>" | --file <path> | < query.sql',
+        async run(args, options) {
+            const sql = await readSql(args, options.file);
+            const text = await apiText(await resolveConnection(options.apiUrl), "/api/v1/warehouse/query", { sql });
+            if (options.format === "json")
+                return console.log(text);
+            const result = JSON.parse(text);
+            const exact = JSON.parse(text, keepNumberDigits);
+            const rows = result.rows.map((row, i) => Object.fromEntries(Object.entries(row).map(([k, v]) => [k, typeof v === "number" ? exact.rows[i][k] : v])));
+            console.log(renderTable(result.columns.map((c) => c.name), rows));
+            console.log(`(${result.rows.length} ${result.rows.length === 1 ? "row" : "rows"})`);
+            if (result.truncated) {
+                console.error(`Results were cut off (${result.truncated}). Aggregate in SQL or add LIMIT.`);
+            }
+        },
+    },
+    funnel: {
+        usage: "funnel [--from <YYYY-MM-DD>] [--to <YYYY-MM-DD>] [--grain day|week|month]",
+        async run(args, options) {
+            if (args.length > 0)
+                throw new CliError("Usage: funnel [--from <date>] [--to <date>] [--grain day|week|month]", exitCodes.usage);
+            const query = reportQuery(options, { grain: options.grain });
+            const { funnel } = await api(await resolveConnection(options.apiUrl), `/api/v1/reports/funnel${query}`);
+            if (options.format === "json")
+                return printJson({ funnel });
+            printReport(`Funnel by ${funnel.grain}`, funnel, ["period", "currency"], FUNNEL_NUMBERS);
+        },
+    },
+    money: {
+        usage: "money [--from <YYYY-MM-DD>] [--to <YYYY-MM-DD>] [--grain day|week|month]",
+        async run(args, options) {
+            if (args.length > 0)
+                throw new CliError("Usage: money [--from <date>] [--to <date>] [--grain day|week|month]", exitCodes.usage);
+            const query = reportQuery(options, { grain: options.grain });
+            const { money } = await api(await resolveConnection(options.apiUrl), `/api/v1/reports/money${query}`);
+            if (options.format === "json")
+                return printJson({ money });
+            printReport(`Money by ${money.grain}`, money, ["period", "currency"], MONEY_NUMBERS);
+            if (money.by_source.length > 0)
+                console.log(`\nMoney in by payment source:\n${renderTable(["source", "currency", "gross", "refunds", "net", "orders"], money.by_source)}`);
+            if (money.refund_days.length > 0)
+                console.log(`\nBiggest refund days:\n${renderTable(["date", "currency", "refunds"], money.refund_days)}`);
+        },
+    },
+    campaigns: {
+        usage: "campaigns [--from <YYYY-MM-DD>] [--to <YYYY-MM-DD>] [--channel <channel>] [--limit <n>]",
+        async run(args, options) {
+            if (args.length > 0)
+                throw new CliError("Usage: campaigns [--from <date>] [--to <date>] [--channel <channel>] [--limit <n>]", exitCodes.usage);
+            const query = reportQuery(options, { channel: options.channel, limit: options.limit });
+            const { campaignResults } = await api(await resolveConnection(options.apiUrl), `/api/v1/reports/campaigns${query}`);
+            if (options.format === "json")
+                return printJson({ campaignResults });
+            const title = campaignResults.channel === null ? "Campaigns, best first" : `${campaignResults.channel} campaigns, best first`;
+            printReport(title, campaignResults, ["channel", "campaign_id", "campaign_name", "currency"], CAMPAIGN_NUMBERS);
+        },
+    },
+    "tools list": {
+        usage: "tools list",
+        async run(_args, options) {
+            const { tools } = await api(await resolveConnection(options.apiUrl), "/api/v1/tools");
+            if (options.format === "json")
+                return printJson({ tools });
+            console.log(renderTable(["id", "mode", "output", "title"], tools));
+        },
+    },
+    "tools run": {
+        usage: "tools run <tool> [--input '<json>' | --file <path> | < input.json] [--idempotency-key <key>] [--wait <seconds>]",
+        async run(args, options) {
+            const [tool, ...rest] = args;
+            if (!tool || rest.length > 0)
+                throw new CliError("Usage: tools run <tool> [--input '<json>']", exitCodes.usage);
+            const input = await readToolInput(options);
+            const connection = await resolveConnection(options.apiUrl);
+            const body = {
+                input,
+                ...(options.idempotencyKey ? { idempotencyKey: options.idempotencyKey } : {}),
+                waitSeconds: Math.min(options.wait, SERVER_WAIT_CAP),
+            };
+            const { run } = await api(connection, `/api/v1/tools/${encodeURIComponent(tool)}/runs`, body);
+            printRun(await waitForRun(connection, run, options.wait), options.format);
+        },
+    },
+    "tools get": {
+        usage: "tools get <run-id> [--wait <seconds>]",
+        async run(args, options) {
+            if (args.length !== 1)
+                throw new CliError("Usage: tools get <run-id>", exitCodes.usage);
+            const connection = await resolveConnection(options.apiUrl);
+            const { run } = await api(connection, `/api/v1/runs/${encodeURIComponent(args[0])}`);
+            printRun(await waitForRun(connection, run, options.wait), options.format);
+        },
+    },
+    "sources list": {
+        usage: "sources list",
+        async run(args, options) {
+            if (args.length > 0)
+                throw new CliError("Usage: sources list", exitCodes.usage);
+            const { sources } = await api(await resolveConnection(options.apiUrl), "/api/v1/sources");
+            if (options.format === "json")
+                return printJson({ sources });
+            if (sources.length === 0)
+                return console.log("No sources yet.");
+            const rows = sources.map((s) => ({
+                id: s.id,
+                name: sourceLabel(s),
+                key: s.name,
+                connector: s.connectorName ?? s.connector,
+                status: s.status,
+                "last synced": s.lastSyncedAt,
+                "next due": s.nextDueAt,
+                "last error": s.lastError && excerpt(s.lastError),
+                "missing access": (s.missingAccess ?? []).map((m) => m.part).join(", "),
+                retrying: retryingText(s),
+            }));
+            console.log(renderTable(["id", "name", "key", "connector", "status", "last synced", "next due", "last error", "missing access", "retrying"], rows));
+            for (const s of sources) {
+                for (const m of s.missingAccess ?? [])
+                    console.log(`${sourceLabel(s)}: ${m.message}`);
+            }
+        },
+    },
+    "sources show": {
+        usage: "sources show <id>",
+        async run(args, options) {
+            if (args.length !== 1)
+                throw new CliError("Usage: sources show <id>", exitCodes.usage);
+            const connection = await resolveConnection(options.apiUrl);
+            const path = `/api/v1/sources/${encodeURIComponent(args[0])}`;
+            const { source } = await api(connection, path);
+            const { runs } = await api(connection, `${path}/runs?limit=${SOURCE_RUNS_SHOWN}`);
+            if (options.format === "json")
+                return printJson({ source, runs });
+            const fields = [
+                { field: "id", value: source.id },
+                { field: "name", value: sourceLabel(source) },
+                { field: "key", value: source.name },
+                { field: "connector", value: source.connectorName ? `${source.connectorName} (${source.connector})` : source.connector },
+                { field: "connection", value: source.connectionId ?? "none" },
+                { field: "status", value: source.status },
+                { field: "last attempted", value: source.lastAttemptedAt ?? "never" },
+                { field: "last synced", value: source.lastSyncedAt ?? "never" },
+                { field: "next due", value: source.nextDueAt ?? "not scheduled" },
+                { field: "last error", value: source.lastError ?? "none" },
+                { field: "retrying since", value: source.retryingSince ?? "not retrying" },
+                { field: "retrying", value: retryingText(source) || "nothing" },
+                { field: "history", value: historyText(source.history) },
+                { field: "created", value: source.createdAt },
+            ];
+            console.log(renderTable(["field", "value"], fields));
+            const failing = source.failingParts ?? [];
+            if (failing.length > 0)
+                console.log(`\nRetrying:\n${failing.map((p) => `- ${p.part} since ${p.since}: ${excerpt(p.error)}`).join("\n")}`);
+            const missing = source.missingAccess ?? [];
+            if (missing.length > 0)
+                console.log(`\nMissing access:\n${missing.map((m) => `- ${m.message}`).join("\n")}`);
+            if (source.tables.length > 0)
+                console.log(`\n${renderTable(["name", "rows", "earliest", "latest"], source.tables)}`);
+            if (runs.length === 0)
+                return console.log("\nNo sync runs yet.");
+            const runRows = runs.map((r) => ({ ...r, error: r.error && excerpt(r.error) }));
+            console.log(`\n${renderTable(["startedAt", "finishedAt", "status", "rowsWritten", "apiCalls", "error"], runRows)}`);
+        },
+    },
+    "sources settings": {
+        usage: "sources settings <id> [<key>=<value> ...]",
+        async run(args, options) {
+            const [id, ...assignments] = args;
+            if (!id)
+                throw new CliError("Usage: sources settings <id> [<key>=<value> ...]", exitCodes.usage);
+            const connection = await resolveConnection(options.apiUrl);
+            const path = `/api/v1/sources/${encodeURIComponent(id)}/settings`;
+            let { settings } = await api(connection, path);
+            if (assignments.length > 0) {
+                const keys = settings.fields.map((f) => f.key);
+                const values = {};
+                for (const assignment of assignments) {
+                    const at = assignment.indexOf("=");
+                    const key = at < 0 ? assignment : assignment.slice(0, at);
+                    if (at < 0 || !keys.includes(key)) {
+                        throw new CliError(`Usage: sources settings <id> <key>=<value> ...; this source's settings are ${keys.join(", ")}`, exitCodes.usage);
+                    }
+                    values[key] = assignment.slice(at + 1);
+                }
+                ({ settings } = await api(connection, path, { values }, "PUT"));
+            }
+            if (options.format === "json")
+                return printJson({ settings });
+            console.log(renderTable(["key", "label", "value"], settings.fields.map((f) => ({ key: f.key, label: f.label, value: settings.values[f.key] ?? "" }))));
+        },
+    },
+    "intake list": {
+        usage: "intake list",
+        async run(args, options) {
+            if (args.length > 0)
+                throw new CliError("Usage: intake list", exitCodes.usage);
+            const { endpoints } = await api(await resolveConnection(options.apiUrl), INTAKE_PATH);
+            if (options.format === "json")
+                return printJson({ endpoints });
+            if (endpoints.length === 0)
+                return console.log("No webhook addresses yet.");
+            const rows = endpoints.map((e) => ({
+                id: e.id,
+                label: e.label,
+                state: e.disabled ? "off" : "on",
+                "kept (days)": e.retentionDays,
+                "events 24h": e.health.eventsLast24h,
+                "last event": e.health.lastEventAt ?? "never",
+                "rows held": e.health.rowsHeld,
+            }));
+            console.log(renderTable(["id", "label", "state", "kept (days)", "events 24h", "last event", "rows held"], rows));
+        },
+    },
+    "intake create": {
+        usage: "intake create <label> [--kind <kind>] [--retention-days <n>] [--signing-key-stdin]",
+        async run(args, options) {
+            if (args.length !== 1)
+                throw new CliError("Usage: intake create <label> [--kind <kind>] [--retention-days <n>] [--signing-key-stdin]", exitCodes.usage);
+            const retentionDays = options.retentionDays === undefined ? undefined : parseRetentionDays(options.retentionDays);
+            const signingKey = options.signingKeyStdin ? await readSigningKey() : undefined;
+            const body = {
+                label: args[0],
+                ...(options.kind === undefined ? {} : { kind: options.kind }),
+                ...(retentionDays === undefined ? {} : { retentionDays }),
+                ...(signingKey === undefined ? {} : { signingKey }),
+            };
+            printIntakeToken(await api(await resolveConnection(options.apiUrl), INTAKE_PATH, body), options.format);
+        },
+    },
+    "intake rotate": {
+        usage: "intake rotate <id>",
+        async run(args, options) {
+            if (args.length !== 1)
+                throw new CliError("Usage: intake rotate <id>", exitCodes.usage);
+            const path = `${intakePath(args[0])}/rotate`;
+            printIntakeToken(await api(await resolveConnection(options.apiUrl), path, {}), options.format);
+        },
+    },
+    "intake signing-key": {
+        usage: "intake signing-key <id> --signing-key-stdin",
+        async run(args, options) {
+            if (args.length !== 1 || !options.signingKeyStdin)
+                throw new CliError("Usage: intake signing-key <id> --signing-key-stdin", exitCodes.usage);
+            const signingKey = await readSigningKey();
+            const path = `${intakePath(args[0])}/signing-key`;
+            const { endpoint } = await api(await resolveConnection(options.apiUrl), path, { signingKey }, "PUT");
+            if (options.format === "json")
+                return printJson({ endpoint });
+            console.log(`Replaced the ${endpoint.kind} signing key. Every ${endpoint.kind} address in the workspace now checks against it.`);
+        },
+    },
+    "intake disable": {
+        usage: "intake disable <id>",
+        async run(args, options) {
+            if (args.length !== 1)
+                throw new CliError("Usage: intake disable <id>", exitCodes.usage);
+            await patchIntake(args[0], { disabled: true }, options, (e) => `Turned off ${e.label}. Senders now get 404 until you turn it on.`);
+        },
+    },
+    "intake enable": {
+        usage: "intake enable <id>",
+        async run(args, options) {
+            if (args.length !== 1)
+                throw new CliError("Usage: intake enable <id>", exitCodes.usage);
+            await patchIntake(args[0], { disabled: false }, options, (e) => `Turned on ${e.label}.`);
+        },
+    },
+    "intake rename": {
+        usage: "intake rename <id> <label>",
+        async run(args, options) {
+            if (args.length !== 2)
+                throw new CliError("Usage: intake rename <id> <label>", exitCodes.usage);
+            await patchIntake(args[0], { label: args[1] }, options, (e) => `Renamed to ${e.label}.`);
+        },
+    },
+    "intake retention": {
+        usage: "intake retention <id> <days>",
+        async run(args, options) {
+            if (args.length !== 2)
+                throw new CliError("Usage: intake retention <id> <days>", exitCodes.usage);
+            const retentionDays = parseRetentionDays(args[1]);
+            await patchIntake(args[0], { retentionDays }, options, (e) => `${e.label} now keeps events for ${e.retentionDays} days.`);
+        },
+    },
+    "intake delete": {
+        usage: "intake delete <id> --yes",
+        async run(args, options) {
+            if (args.length !== 1)
+                throw new CliError("Usage: intake delete <id> --yes", exitCodes.usage);
+            if (!options.yes) {
+                throw new CliError("This deletes the address and every event it has saved. Add --yes to confirm: intake delete <id> --yes", exitCodes.usage);
+            }
+            const result = await api(await resolveConnection(options.apiUrl), intakePath(args[0]), undefined, "DELETE");
+            if (options.format === "json")
+                return printJson(result);
+            console.log("Deleted the address and its saved events.");
+        },
+    },
+    "import csv": {
+        usage: "import csv <file> --table <name>",
+        async run(args, options) {
+            const usage = "Usage: import csv <file> --table <name>";
+            if (args.length !== 1 || !options.table)
+                throw new CliError(usage, exitCodes.usage);
+            const name = importName(options.table);
+            const file = await readImportFile(args[0]);
+            const connection = await resolveConnection(options.apiUrl);
+            const result = await uploadCsv(connection, name, file);
+            if (options.format === "json")
+                return printJson(result);
+            console.log(`Imported ${result.rows} ${result.rows === 1 ? "row" : "rows"} into ${result.table}.`);
+            console.log(renderTable(["column", "type", "header"], result.columns.map((c) => ({ column: c.name, type: c.type, header: c.sourceHeader }))));
+        },
+    },
+    "import remove": {
+        usage: "import remove --table <name> --yes",
+        async run(args, options) {
+            const usage = "Usage: import remove --table <name> --yes";
+            if (args.length !== 0 || !options.table)
+                throw new CliError(usage, exitCodes.usage);
+            const name = importName(options.table);
+            if (!options.yes) {
+                throw new CliError(`This drops the table import_${name} and all its rows. Add --yes to confirm: import remove --table ${name} --yes`, exitCodes.usage);
+            }
+            const path = `/api/v1/imports/csv?table=${encodeURIComponent(name)}`;
+            const result = await api(await resolveConnection(options.apiUrl), path, undefined, "DELETE");
+            if (options.format === "json")
+                return printJson(result);
+            console.log(`Removed ${result.table} and its rows.`);
+        },
+    },
+    "creatives list": {
+        usage: "creatives list [--status <status>] [--kind static|video|copy] [--limit <n>]",
+        async run(_args, options) {
+            const query = new URLSearchParams();
+            if (options.status)
+                query.set("status", options.status);
+            if (options.kind)
+                query.set("kind", options.kind);
+            if (options.limit)
+                query.set("limit", options.limit);
+            const path = `/api/v1/creatives${query.size ? `?${query}` : ""}`;
+            const { creatives } = await api(await resolveConnection(options.apiUrl), path);
+            if (options.format === "json")
+                return printJson({ creatives });
+            if (creatives.length === 0)
+                return console.log("No creatives yet.");
+            const rows = creatives.map((c) => ({ ...c, tool: c.spec.tool, output: c.assetUrl ?? excerpt(c.copyText ?? "") }));
+            console.log(renderTable(["sku", "kind", "status", "tool", "createdAt", "output"], rows));
+        },
+    },
+    "creatives show": {
+        usage: "creatives show <sku>",
+        async run(args, options) {
+            if (args.length !== 1)
+                throw new CliError("Usage: creatives show <sku>", exitCodes.usage);
+            const { creative } = await api(await resolveConnection(options.apiUrl), `/api/v1/creatives/${encodeURIComponent(args[0])}`);
+            if (options.format === "json")
+                return printJson({ creative });
+            const fields = {
+                ...creative,
+                tool: creative.spec.tool,
+                prompt: creative.spec.input?.prompt,
+            };
+            const shown = ["sku", "kind", "status", "tool", "prompt", "lineage", "assetUrl", "copyText", "metaAdId", "toolRunId", "createdAt"];
+            console.log(renderTable(["field", "value"], shown.filter((f) => fields[f] != null).map((f) => ({ field: f, value: fields[f] }))));
+        },
+    },
+    "creatives download": {
+        usage: "creatives download <sku | asset-path | asset-link> [--out <path>] [--open]",
+        async run(args, options) {
+            if (args.length !== 1)
+                throw new CliError("Usage: creatives download <sku | asset-path | asset-link> [--out <path>] [--open]", exitCodes.usage);
+            const connection = await resolveConnection(options.apiUrl);
+            const target = await downloadTarget(args[0], connection);
+            const { bytes, contentType } = await apiDownload(connection, `${ASSET_ROUTE}${target.assetPath.split("/").map(encodeURIComponent).join("/")}`);
+            const path = await savePath(options.out, extname(target.fileName) ? target.fileName : `${target.fileName}.${extensionFor(contentType)}`);
+            await writeFileAtomic(path, bytes, 0o644).catch((error) => {
+                if (error.code === "ENOENT")
+                    throw new CliError(`No folder at ${dirname(path)} to save into.`, exitCodes.usage);
+                throw error;
+            });
+            if (options.open)
+                openFile(resolve(path));
+            if (options.format === "json")
+                return printJson({ path: resolve(path), bytes: bytes.byteLength, contentType });
+            console.log(`Saved ${target.label} to ${path} (${fileSize(bytes.byteLength)}).`);
+        },
+    },
+    "creatives create": {
+        usage: "creatives create --run <tool-run-id> [--lineage '<json>' | @file.json]",
+        async run(args, options) {
+            if (args.length > 0 || !options.run)
+                throw new CliError("Usage: creatives create --run <tool-run-id> [--lineage '<json>' | @file.json]", exitCodes.usage);
+            const lineage = options.lineage === undefined ? undefined : await parseJson(options.lineage, "--lineage");
+            const { creatives } = await api(await resolveConnection(options.apiUrl), "/api/v1/creatives", {
+                runId: options.run,
+                ...(lineage === undefined ? {} : { lineage }),
+            });
+            if (options.format === "json")
+                return printJson({ creatives });
+            console.log(renderTable(["sku", "kind", "status", "assetUrl"], creatives));
+        },
+    },
+    "content create": {
+        usage: "content create --kind <kind> [--name <name>] [--subject <s>] [--preview <s>] [--headline <s>] [--body <text> | @file] [--html @file] [--fields '<json>' | @file.json] [--file <path> ...] [--tool-run <id> ...] [--run <agent-run-id>] [--note <why>] [--plan <plan-id> [--role <role>]]",
+        async run(args, options) {
+            if (args.length > 0 || !options.kind)
+                throw new CliError("Usage: content create --kind ad|email|sms|landing_page|video|social_post [...]", exitCodes.usage);
+            const connection = await resolveConnection(options.apiUrl);
+            const content = await api(connection, "/api/v1/content", {
+                kind: options.kind,
+                ...(await contentInput(options, connection)),
+                ...(options.plan === undefined ? {} : { launchPlanId: options.plan }),
+                ...(options.role === undefined ? {} : { launchPlanRole: options.role }),
+            });
+            printContent(content, options.format);
+        },
+    },
+    "content capture": {
+        usage: "content capture --kind <kind> --name <name> [--subject <s>] [--headline <s>] [--body <text> | @file] [--html @file] [--file <path> ...] [--transcript <text> | @file [--language <code>]] [--source <text>] [--url <url>] [--run <agent-run-id>]",
+        async run(args, options) {
+            if (args.length > 0 || !options.kind || !options.name) {
+                throw new CliError("Usage: content capture --kind ad|email|sms|landing_page|video|social_post --name <name> [...]", exitCodes.usage);
+            }
+            if (options.language !== undefined && options.transcript === undefined)
+                throw new CliError("--language goes with --transcript.", exitCodes.usage);
+            const connection = await resolveConnection(options.apiUrl);
+            const content = await api(connection, "/api/v1/content/captures", {
+                kind: options.kind,
+                ...(await contentInput(options, connection)),
+                transcript: options.transcript === undefined ? undefined : { text: await textOrFile(options.transcript), language: options.language },
+                source: options.source,
+                url: options.url,
+            });
+            printContent(content, options.format);
+        },
+    },
+    guide: {
+        usage: "guide   (what this workspace's data holds, how fresh it is, and what is missing: read it first)",
+        async run(args, options) {
+            if (args.length > 0)
+                throw new CliError("Usage: guide", exitCodes.usage);
+            const guide = await api(await resolveConnection(options.apiUrl), "/api/v1/guide");
+            if (options.format === "json")
+                return printJson(guide);
+            process.stdout.write(guide.text);
+        },
+    },
+    "content search": {
+        usage: "content search [--text <words>] [--mode word|meaning] [--kind <kind>] [--platform <platform>] [--origin discovered|made] [--from <YYYY-MM-DD>] [--to <YYYY-MM-DD>] [--sort recent|<scorecard column>] [--order desc|asc] [--limit <n>]",
+        async run(args, options) {
+            if (args.length > 0)
+                throw new CliError("Usage: content search [--text <words>] [--kind <kind>] [--sort <column>] [...]; put several words in quotes", exitCodes.usage);
+            const filters = { text: options.text, mode: options.mode, kind: options.kind, platform: options.platform, origin: options.origin, from: options.from, to: options.to, sort: options.sort, order: options.order, limit: options.limit };
+            const query = new URLSearchParams(Object.entries(filters).filter((entry) => entry[1] !== undefined));
+            const { results } = await api(await resolveConnection(options.apiUrl), `/api/v1/content${query.size ? `?${query}` : ""}`);
+            if (options.format === "json")
+                return printJson({ results });
+            if (results.length === 0)
+                return console.log("No content found.");
+            const sort = options.sort && results.some((r) => scoreCell(r.scorecards, options.sort) !== null) ? options.sort : null;
+            const meaning = results.some((r) => r.distance !== undefined);
+            const rows = results.map((r) => ({
+                ref: r.sku ?? r.id,
+                kind: r.kind,
+                platform: r.platform,
+                live: r.liveFrom === r.liveTo ? r.liveFrom : `${r.liveFrom} to ${r.liveTo}`,
+                ...(sort ? { [sort]: scoreCell(r.scorecards, sort) } : {}),
+                ...(meaning ? { distance: r.distance ?? null } : {}),
+                words: excerpt([r.version.subject ?? r.version.headline, r.version.snippet].filter(Boolean).join(": ")),
+                files: r.media.length || null,
+                transcript: r.hasTranscript ? "yes" : null,
+            }));
+            console.log(renderTable(["ref", "kind", "platform", "live", ...(sort ? [sort] : []), ...(meaning ? ["distance"] : []), "words", "files", "transcript"], rows));
+        },
+    },
+    "content show": {
+        usage: "content show <sku | item-id>",
+        async run(args, options) {
+            if (args.length !== 1)
+                throw new CliError("Usage: content show <sku | item-id>", exitCodes.usage);
+            const content = await api(await resolveConnection(options.apiUrl), `/api/v1/content/${encodeURIComponent(args[0])}`);
+            printContent(content, options.format);
+        },
+    },
+    "content pull": {
+        usage: "content pull <dir> [--kind <kind>] [--platform <platform>] [--origin discovered|made] [--media] [--full]",
+        async run(args, options) {
+            if (args.length !== 1)
+                throw new CliError("Usage: content pull <dir> [--kind <kind>] [--platform <platform>] [--origin discovered|made] [--media] [--full]", exitCodes.usage);
+            const filters = Object.fromEntries(Object.entries({ kind: options.kind, platform: options.platform, origin: options.origin }).filter((e) => e[1] !== undefined));
+            const report = await pullContent(await resolveConnection(options.apiUrl), args[0], filters, { media: options.media, full: options.full });
+            if (options.format === "json")
+                return printJson(report);
+            const media = options.media ? `, ${report.media} new media file${report.media === 1 ? "" : "s"}` : "";
+            console.log(`Pulled ${report.items} item${report.items === 1 ? "" : "s"} into ${report.dir}: ${report.written.length} written, ${report.unchanged} unchanged, ${report.removed} removed${media}.`);
+            for (const path of report.written)
+                console.log(`  ${path}`);
+            console.log(`The next pull fetches what changed since ${report.watermark} (kept in ${PULL_STATE_FILE}).`);
+        },
+    },
+    "content diff": {
+        usage: "content diff <sku | item-id> [--from <n>] [--to <n>]",
+        async run(args, options) {
+            if (args.length !== 1)
+                throw new CliError("Usage: content diff <sku | item-id> [--from <n>] [--to <n>]", exitCodes.usage);
+            const query = new URLSearchParams(Object.entries({ from: options.from, to: options.to }).filter((entry) => entry[1] !== undefined));
+            const diff = await api(await resolveConnection(options.apiUrl), `/api/v1/content/${encodeURIComponent(args[0])}/diff${query.size ? `?${query}` : ""}`);
+            if (options.format === "json")
+                return printJson(diff);
+            printContentDiff(diff);
+        },
+    },
+    "content edit": {
+        usage: "content edit <sku | item-id> [--name ...] [--subject ...] [--body ...] [--html @file] [--fields ...] [--file <path> ...] [--tool-run <id> ...] [--run <agent-run-id>] [--note <why>]",
+        async run(args, options) {
+            if (args.length !== 1)
+                throw new CliError("Usage: content edit <sku | item-id> [--body <text> | @file] [--note <why>] [...]", exitCodes.usage);
+            const connection = await resolveConnection(options.apiUrl);
+            const input = await contentInput(options, connection);
+            if (Object.keys(input).every((k) => k === "runId" || k === "note")) {
+                throw new CliError("content edit needs something to change, such as --body, --subject or --file.", exitCodes.usage);
+            }
+            const content = await api(connection, `/api/v1/content/${encodeURIComponent(args[0])}`, input, "PATCH");
+            printContent(content, options.format);
+        },
+    },
+    "content status": {
+        usage: "content status <sku | item-id> <status> [--platform <platform> --external-id <id>]",
+        async run(args, options) {
+            if (args.length !== 2)
+                throw new CliError("Usage: content status <sku | item-id> <status> [--platform <platform> --external-id <id>]", exitCodes.usage);
+            const content = await api(await resolveConnection(options.apiUrl), `/api/v1/content/${encodeURIComponent(args[0])}/status`, {
+                status: args[1],
+                ...(options.platform === undefined ? {} : { platform: options.platform }),
+                ...(options.externalId === undefined ? {} : { externalId: options.externalId }),
+            });
+            printContent(content, options.format);
+        },
+    },
+    "content publish": {
+        usage: "content publish <sku | item-id> --to <publisher> --target '<json>' --idempotency-key <key> [--plan <plan-id>] [--version <n>] [--run <run-id>]",
+        async run(args, options) {
+            if (args.length !== 1 || !options.to || options.target === undefined || !options.idempotencyKey) {
+                throw new CliError("Usage: content publish <sku | item-id> --to <publisher> --target '<json>' --idempotency-key <key> [--plan <plan-id>] [--version <n>] [--run <run-id>]", exitCodes.usage);
+            }
+            const version = options.version === undefined ? undefined : Number(options.version);
+            if (version !== undefined && !(Number.isInteger(version) && version >= 1))
+                throw new CliError("--version must be a whole number from 1.", exitCodes.usage);
+            const { publication } = await api(await resolveConnection(options.apiUrl), `/api/v1/content/${encodeURIComponent(args[0])}/publish`, {
+                publisher: options.to,
+                target: await parseJson(options.target, "--target"),
+                idempotencyKey: options.idempotencyKey,
+                ...(options.plan === undefined ? {} : { launchPlanId: options.plan }),
+                ...(version === undefined ? {} : { version }),
+                ...(options.run === undefined ? {} : { runId: options.run }),
+            });
+            printPublication(publication, options.format);
+        },
+    },
+    "content reconcile": {
+        usage: "content reconcile <publication-id>",
+        async run(args, options) {
+            if (args.length !== 1)
+                throw new CliError("Usage: content reconcile <publication-id>", exitCodes.usage);
+            const { publication } = await api(await resolveConnection(options.apiUrl), `/api/v1/publications/${encodeURIComponent(args[0])}/reconcile`, {});
+            printPublication(publication, options.format);
+        },
+    },
+    "content unpublish": {
+        usage: "content unpublish <deployment-id> [--force]",
+        async run(args, options) {
+            if (args.length !== 1)
+                throw new CliError("Usage: content unpublish <deployment-id> [--force]", exitCodes.usage);
+            const { deployment } = await api(await resolveConnection(options.apiUrl), `/api/v1/deployments/${encodeURIComponent(args[0])}/unpublish`, options.force ? { force: true } : {});
+            if (options.format === "json")
+                return printJson({ deployment });
+            printFields({
+                deployment: deployment.id,
+                url: deployment.url,
+                version: deployment.version,
+                status: deployment.status,
+                unpublished: deployment.unpublishedAt,
+                by: deployment.unpublishedBy,
+            });
+        },
+    },
+    "content publish-record": {
+        usage: "content publish-record <sku | item-id> [--input '<json>' | --file <path> | < publication.json]",
+        async run(args, options) {
+            if (args.length !== 1)
+                throw new CliError("Usage: content publish-record <sku | item-id> --file <publication.json>", exitCodes.usage);
+            const { publication } = await api(await resolveConnection(options.apiUrl), `/api/v1/content/${encodeURIComponent(args[0])}/publications`, await readToolInput(options));
+            printPublication(publication, options.format);
+        },
+    },
+    "content publish-finish": {
+        usage: "content publish-finish <publication-id> --status sending|published|failed|not_sent_practice [--input '<json>' | --file <path> | < outcome.json]",
+        async run(args, options) {
+            if (args.length !== 1 || !options.status) {
+                throw new CliError("Usage: content publish-finish <publication-id> --status sending|published|failed|not_sent_practice [--file <outcome.json>]", exitCodes.usage);
+            }
+            const outcome = await readToolInput(options);
+            const { publication } = await api(await resolveConnection(options.apiUrl), `/api/v1/publications/${encodeURIComponent(args[0])}`, { ...outcome, status: options.status }, "PATCH");
+            printPublication(publication, options.format);
+        },
+    },
+    "agent start": {
+        usage: "agent start",
+        async run(args, options) {
+            if (args.length > 0)
+                throw new CliError("Usage: agent start", exitCodes.usage);
+            const start = await api(await resolveConnection(options.apiUrl), `${agentPath(options)}/runs`, {});
+            if (options.format === "json")
+                return printJson(start);
+            const { run, quota, brandProfile } = start;
+            const rows = [
+                { field: "run", value: run.id },
+                { field: "resumed", value: start.resumed ? "yes" : "no" },
+                { field: "mode", value: start.agent.mode },
+                ...(start.result ? [{ field: "result", value: `${start.result.name} (${start.result.metaActionTypes.join(", ") || "no Meta source"})` }] : []),
+                ...(quota ? [{ field: "ideas today", value: `${quota.creativeProposalsToday} of ${quota.ideasPerDay} used, ${quota.remainingToday} left` }] : []),
+                { field: "brand profile", value: brandProfile ? `version ${brandProfile.version}, ${brandProfile.ageDays} days old` : "none yet" },
+                ...start.memory.map((note) => ({ field: `memory ${note.key}`, value: note.value ? `${note.value.length} characters` : "empty" })),
+            ];
+            console.log(renderTable(["field", "value"], rows));
+        },
+    },
+    "agent show": {
+        usage: "agent show <run-id>",
+        async run(args, options) {
+            if (args.length !== 1)
+                throw new CliError("Usage: agent show <run-id>", exitCodes.usage);
+            const shown = await api(await resolveConnection(options.apiUrl), `${agentPath(options)}/runs/${encodeURIComponent(args[0])}`);
+            if (options.format === "json")
+                return printJson(shown);
+            const { run, proposals } = shown;
+            console.log(renderTable(["run", "status", "startedAt", "finishedAt"], [{ ...run, run: run.id }]));
+            if (run.report)
+                console.log(`\n${run.report}`);
+            console.log(proposals.length ? `\n${renderTable(PROPOSAL_COLUMNS, proposals.map(proposalRow))}` : "\nNo proposals in this run.");
+        },
+    },
+    "agent runs": {
+        usage: "agent runs [--limit <n>]",
+        async run(_args, options) {
+            const query = options.limit ? `?limit=${encodeURIComponent(options.limit)}` : "";
+            const { runs } = await api(await resolveConnection(options.apiUrl), `${agentPath(options)}/runs${query}`);
+            if (options.format === "json")
+                return printJson({ runs });
+            if (runs.length === 0)
+                return console.log("No runs yet.");
+            console.log(renderTable(["id", "status", "startedAt", "finishedAt"], runs));
+        },
+    },
+    "agent finish": {
+        usage: "agent finish <run-id> --status succeeded|failed [--file report.md | < report.md]",
+        async run(args, options) {
+            if (args.length !== 1 || (options.status !== "succeeded" && options.status !== "failed")) {
+                throw new CliError("Usage: agent finish <run-id> --status succeeded|failed [--file report.md]", exitCodes.usage);
+            }
+            const report = await readText(options.file, "the report");
+            const { run } = await api(await resolveConnection(options.apiUrl), `${agentPath(options)}/runs/${encodeURIComponent(args[0])}/finish`, { status: options.status, report });
+            if (options.format === "json")
+                return printJson({ run });
+            console.log(`Finished run ${run.id} as ${run.status}.`);
+        },
+    },
+    "agent draft": {
+        usage: "agent draft --agent p3_refresh",
+        async run(args, options) {
+            if (args.length > 0)
+                throw new CliError("Usage: agent draft --agent p3_refresh", exitCodes.usage);
+            const body = await api(await resolveConnection(options.apiUrl), `${agentPath(options)}/draft`);
+            if (options.format === "json")
+                return printJson(body);
+            const { draft } = body;
+            const campaigns = (list) => list.map((c) => `${c.name} (${c.campaignId}, ${c.effectiveStatus})`).join("; ") || "none";
+            console.log(`Draft for ${draft.today}. Scan ${draft.scan.since} to ${draft.scan.until}${draft.scan.complete ? "" : " (incomplete)"}.`);
+            console.log(`P1 campaigns: ${campaigns(draft.campaigns.p1)}`);
+            console.log(`P3 campaigns: ${campaigns(draft.campaigns.p3)}`);
+            for (const flag of draft.flags)
+                console.log(`! ${flag}`);
+            const adsets = draft.adsets.map((a) => ({
+                rank: a.rank,
+                adset: a.adsetId,
+                name: a.name,
+                status: a.effectiveStatus,
+                "purchases 30d": a.d30.purchases,
+                "spend 30d": a.d30.spend,
+                "cpp 30d": a.d30.costPerPurchase,
+                "purchases 7d": a.d7.purchases,
+                today: a.today.purchases,
+                flags: [...(a.adsetId === draft.template?.adsetId ? ["template"] : []), ...a.flags].join(", "),
+            }));
+            console.log(`\n${adsets.length ? renderTable(Object.keys(adsets[0]), adsets) : "No ad sets in the purchase campaign."}`);
+            const candidate = (c) => ({
+                ad: c.sourceAdId,
+                name: excerpt(c.name, 40),
+                origin: c.origin,
+                disposition: c.disposition,
+                purchases: c.purchases,
+                spend: c.spend,
+                today: c.todayPurchases,
+                post: c.postId,
+                "in P3": c.p3Matches.map((m) => `${m.adId} ${m.status} by ${m.matchedBy}`).join("; "),
+            });
+            const rows = [...draft.candidates, ...draft.carriedForward].map(candidate);
+            console.log(`\n${rows.length ? renderTable(Object.keys(rows[0]), rows) : "No P1 winners."}`);
+        },
+    },
+    "memory get": {
+        usage: "memory get [baselines|watch_items|changes_log|gotchas]",
+        async run(args, options) {
+            if (args.length > 1)
+                throw new CliError("Usage: memory get [<note>]", exitCodes.usage);
+            const connection = await resolveConnection(options.apiUrl);
+            if (args[0]) {
+                const { note } = await api(connection, `${agentPath(options)}/memory/${encodeURIComponent(args[0])}`);
+                if (options.format === "json")
+                    return printJson({ note });
+                return void process.stdout.write(note.value ? `${note.value.replace(/\n?$/, "\n")}` : "");
+            }
+            const { memory } = await api(connection, `${agentPath(options)}/memory`);
+            if (options.format === "json")
+                return printJson({ memory });
+            console.log(memory.map((n) => `## ${n.key}${n.updatedAt ? ` (updated ${n.updatedAt})` : ""}\n\n${n.value || "(empty)"}`).join("\n\n"));
+        },
+    },
+    "memory set": {
+        usage: "memory set <note> [--file <path> | < note.md]",
+        async run(args, options) {
+            if (args.length !== 1)
+                throw new CliError("Usage: memory set <note> [--file <path>]", exitCodes.usage);
+            const value = await readText(options.file, "the note");
+            const { note } = await api(await resolveConnection(options.apiUrl), `${agentPath(options)}/memory/${encodeURIComponent(args[0])}`, { value }, "PUT");
+            if (options.format === "json")
+                return printJson({ note });
+            console.log(`Saved ${note.key} (${note.value.length} characters).`);
+        },
+    },
+    "brand get": {
+        usage: "brand get",
+        async run(_args, options) {
+            const { profile } = await api(await resolveConnection(options.apiUrl), "/api/v1/brand-profile");
+            if (options.format === "json")
+                return printJson({ profile });
+            if (!profile)
+                return console.log("No brand profile yet.");
+            console.error(`Brand profile version ${profile.version}, saved ${profile.createdAt}.`);
+            process.stdout.write(profile.markdown.replace(/\n?$/, "\n"));
+        },
+    },
+    "brand set": {
+        usage: "brand set [--file <path> | < profile.md] [--sources '<json>' | @file.json]",
+        async run(args, options) {
+            if (args.length > 0)
+                throw new CliError("Usage: brand set [--file <path>] [--sources '<json>' | @file.json]", exitCodes.usage);
+            const markdown = await readText(options.file, "the brand profile");
+            const sources = options.sources === undefined ? [] : await parseJson(options.sources, "--sources");
+            const { profile } = await api(await resolveConnection(options.apiUrl), "/api/v1/brand-profile", { markdown, sources }, "PUT");
+            if (options.format === "json")
+                return printJson({ profile });
+            console.log(`Saved brand profile version ${profile.version}.`);
+        },
+    },
+    "content add-page": {
+        usage: "content add-page <url>",
+        async run(args, options) {
+            if (args.length !== 1)
+                throw new CliError("Usage: content add-page <url>", exitCodes.usage);
+            const { page } = await api(await resolveConnection(options.apiUrl), "/api/v1/content/pages", { url: args[0] });
+            if (options.format === "json")
+                return printJson({ page });
+            console.log(renderTable(["key", "status", "version", "changed", "headline", "blocks"], [{ ...page, blocks: page.blockCount }]));
+            for (const line of [page.error, ...page.notes])
+                if (line)
+                    console.error(line);
+        },
+    },
+    "content track-link": {
+        usage: "content track-link <sku> <url> [--channel facebook|email|sms|web] [--campaign <id>]",
+        async run(args, options) {
+            if (args.length !== 2)
+                throw new CliError("Usage: content track-link <sku> <url> [--channel facebook|email|sms|web] [--campaign <id>]", exitCodes.usage);
+            const { url } = await api(await resolveConnection(options.apiUrl), "/api/v1/content/track-link", {
+                sku: args[0],
+                url: args[1],
+                channel: options.channel,
+                campaign: options.campaign,
+            });
+            if (options.format === "json")
+                return printJson({ url });
+            console.log(url);
+        },
+    },
+    trail: {
+        usage: "trail <plan-id | sku | item-id>",
+        async run(args, options) {
+            if (args.length !== 1)
+                throw new CliError("Usage: trail <plan-id | sku | item-id>", exitCodes.usage);
+            const connection = await resolveConnection(options.apiUrl);
+            const ref = args[0];
+            const trailOf = (query) => api(connection, `/api/v1/trail?${query}=${encodeURIComponent(ref)}`);
+            // Plans and items both have uuid ids: an id that names no plan is read as an item.
+            const { trail } = UUID.test(ref)
+                ? await trailOf("plan").catch((error) => {
+                    if (error instanceof ApiError && error.code === "launch_plan_not_found")
+                        return trailOf("item");
+                    throw error;
+                })
+                : await trailOf("item");
+            printTrail(trail, options.format);
+        },
+    },
+    "plans create": {
+        usage: "plans create --name <name> --goal <text> --channel meta|ghl|klaviyo|web [--target '<json>' | @file.json] [--landing <sku | item-id> | --landing-url <url>] [--run <agent-run-id>]",
+        async run(args, options) {
+            if (args.length > 0 || !options.name || !options.goal || !options.channel) {
+                throw new CliError("Usage: plans create --name <name> --goal <text> --channel meta|ghl|klaviyo|web [--target '<json>'] [--landing <sku> | --landing-url <url>]", exitCodes.usage);
+            }
+            const { plan } = await api(await resolveConnection(options.apiUrl), "/api/v1/launch-plans", {
+                name: options.name,
+                goal: await textOrFile(options.goal),
+                channel: options.channel,
+                ...(options.target === undefined ? {} : { target: await parseJson(options.target, "--target") }),
+                ...(options.landing === undefined ? {} : { landingItem: options.landing }),
+                ...(options.landingUrl === undefined ? {} : { landingUrl: options.landingUrl }),
+                ...(options.run === undefined ? {} : { runId: options.run }),
+            });
+            printPlan(plan, options.format);
+        },
+    },
+    "plans show": {
+        usage: "plans show <plan-id>",
+        async run(args, options) {
+            if (args.length !== 1)
+                throw new CliError("Usage: plans show <plan-id>", exitCodes.usage);
+            const { plan } = await api(await resolveConnection(options.apiUrl), planPath(args[0]));
+            printPlan(plan, options.format);
+        },
+    },
+    "plans add": {
+        usage: "plans add <plan-id> <sku | item-id> [--role <role>] [--position <n>]",
+        async run(args, options) {
+            if (args.length !== 2)
+                throw new CliError("Usage: plans add <plan-id> <sku | item-id> [--role <role>] [--position <n>]", exitCodes.usage);
+            const position = options.position === undefined ? undefined : Number(options.position);
+            if (position !== undefined && (!Number.isInteger(position) || position < 0))
+                throw new CliError("--position must be a whole number from 0.", exitCodes.usage);
+            const { plan } = await api(await resolveConnection(options.apiUrl), `${planPath(args[0])}/items`, {
+                item: args[1],
+                ...(options.role === undefined ? {} : { role: options.role }),
+                ...(position === undefined ? {} : { position }),
+            });
+            printPlan(plan, options.format);
+        },
+    },
+    "plans remove": {
+        usage: "plans remove <plan-id> <sku | item-id>",
+        async run(args, options) {
+            if (args.length !== 2)
+                throw new CliError("Usage: plans remove <plan-id> <sku | item-id>", exitCodes.usage);
+            const path = `${planPath(args[0])}/items?item=${encodeURIComponent(args[1])}`;
+            const { plan } = await api(await resolveConnection(options.apiUrl), path, undefined, "DELETE");
+            printPlan(plan, options.format);
+        },
+    },
+    "plans status": {
+        usage: "plans status <plan-id> <status>",
+        async run(args, options) {
+            if (args.length !== 2)
+                throw new CliError("Usage: plans status <plan-id> draft|ready|publishing|live|done|cancelled", exitCodes.usage);
+            const { plan } = await api(await resolveConnection(options.apiUrl), planPath(args[0]), { status: args[1] }, "PATCH");
+            printPlan(plan, options.format);
+        },
+    },
+    "proposals create": {
+        usage: "proposals create --input '<json>' | --file <path> | < proposal.json",
+        async run(args, options) {
+            if (args.length > 0)
+                throw new CliError("Usage: proposals create --input '<json>'", exitCodes.usage);
+            const { proposal } = await api(await resolveConnection(options.apiUrl), "/api/v1/proposals", await readToolInput(options));
+            if (options.format === "json")
+                return printJson({ proposal });
+            console.log(renderTable(PROPOSAL_COLUMNS, [proposalRow(proposal)]));
+        },
+    },
+    "proposals list": {
+        usage: "proposals list [--status pending|approved|rejected] [--kind <kind>] [--run <run-id>] [--limit <n>]",
+        async run(_args, options) {
+            const query = new URLSearchParams();
+            if (options.status)
+                query.set("status", options.status);
+            if (options.kind)
+                query.set("kind", options.kind);
+            if (options.run)
+                query.set("runId", options.run);
+            if (options.limit)
+                query.set("limit", options.limit);
+            const path = `/api/v1/proposals${query.size ? `?${query}` : ""}`;
+            const { proposals } = await api(await resolveConnection(options.apiUrl), path);
+            if (options.format === "json")
+                return printJson({ proposals });
+            if (proposals.length === 0)
+                return console.log("No proposals.");
+            console.log(renderTable(PROPOSAL_COLUMNS, proposals.map(proposalRow)));
+        },
+    },
+    "skill publish": {
+        usage: "skill publish <dir> [--notes <text>] [--harness claude,codex]",
+        async run(args, options) {
+            if (args.length !== 1)
+                throw new CliError("Usage: skill publish <dir> [--notes <text>] [--harness claude,codex]", exitCodes.usage);
+            const dir = resolve(args[0]);
+            const name = basename(dir);
+            if (!SKILL_NAME_PATTERN.test(name)) {
+                throw new CliError(`The folder's name is the skill's name, and '${name}' is not one: use 1 to 64 lowercase letters, digits and dashes.`, exitCodes.usage);
+            }
+            if (isPlaybook(name)) {
+                throw new CliError(`'${name}' is a built-in playbook's name, and \`${brand.slug} skill install ${name}\` always installs the built-in one. Rename the folder.`, exitCodes.usage);
+            }
+            const zip = packSkill(name, await readSkillFolder(dir));
+            const query = new URLSearchParams();
+            if (options.notes !== undefined)
+                query.set("notes", options.notes);
+            if (options.harness !== undefined)
+                query.set("harnesses", options.harness);
+            const path = `/api/operator/skills/${name}/versions${query.size ? `?${query}` : ""}`;
+            const published = await apiUpload(await operatorConnection(options.apiUrl), path, zip, "application/zip");
+            if (options.format === "json")
+                return printJson(published);
+            console.log(`${published.name} version ${published.version}`);
+            console.log(`sha256 ${published.sha256}`);
+        },
+    },
+    "skill list": {
+        usage: "skill list",
+        async run(args, options) {
+            if (args.length > 0)
+                throw new CliError("Usage: skill list", exitCodes.usage);
+            const { skills } = await api(await operatorConnection(options.apiUrl), "/api/operator/skills");
+            if (options.format === "json")
+                return printJson({ skills });
+            if (skills.length === 0)
+                return console.log("No skills in the library.");
+            const rows = skills.flatMap((s) => s.versions.map((v) => ({ skill: s.name, version: v.version, status: v.status, published: v.createdAt, sha256: v.sha256.slice(0, 12), notes: v.notes })));
+            console.log(renderTable(["skill", "version", "status", "published", "sha256", "notes"], rows));
+        },
+    },
+    "skill install": {
+        usage: "skill install [meta-ads|p3-refresh|<name>[@<version>]] [--project] [--codex]",
+        async run(args, options) {
+            const usage = "Usage: skill install [meta-ads|p3-refresh|<name>[@<version>]] [--project] [--codex]";
+            const [which] = args;
+            if (args.length > 1)
+                throw new CliError(usage, exitCodes.usage);
+            if (which !== undefined && !isPlaybook(which))
+                return installLibrarySkill(parseSkillRef(which), options);
+            const playbook = which === undefined ? null : playbooks[which];
+            if (options.codex) {
+                if (which === "meta-ads")
+                    return installAgentsMd(join(process.cwd(), "AGENTS.md"));
+                if (!playbook)
+                    throw new CliError("--codex installs a playbook: skill install meta-ads|p3-refresh --codex", exitCodes.usage);
+                if (options.project)
+                    throw new CliError(`--codex installs ${playbook.name} for every Codex run, under CODEX_HOME; drop --project`, exitCodes.usage);
+                const path = await writeSkill(codexSkillsDir(), playbook.name, playbook.skill, []);
+                return console.log(`Installed the ${playbook.name} skill for Codex to ${path}.`);
+            }
+            const [name, content] = playbook ? [playbook.name, playbook.skill] : [brand.slug, skill];
+            const { skillsDir, above } = claudeSkillsDir(options.project);
+            const path = await writeSkill(skillsDir, name, content, above);
+            console.log(`Installed the ${name} skill to ${path}.`);
+        },
+    },
+    "worker list": {
+        usage: "worker list",
+        async run(args, options) {
+            if (args.length > 0)
+                throw new CliError("Usage: worker list", exitCodes.usage);
+            const { workers } = await api(await resolveConnection(options.apiUrl), "/api/v1/workers");
+            if (options.format === "json")
+                return printJson({ workers });
+            if (workers.length === 0)
+                return console.log("No workers yet.");
+            const rows = workers.map((w) => ({
+                id: w.id,
+                skill: w.skill,
+                version: w.candidateVersion === null ? w.version : `${w.version} (trying ${w.candidateVersion})`,
+                schedule: `${w.schedule} ${w.timeZone}`,
+                mode: w.mode,
+                runner: w.runner,
+                enabled: w.enabled ? "yes" : "no",
+                "next run": w.nextRunAt,
+                "last run": w.lastRun ? `${w.lastRun.status}${w.lastRun.finishedAt ? ` ${w.lastRun.finishedAt}` : ""}` : "",
+            }));
+            console.log(renderTable(["id", "skill", "version", "schedule", "mode", "runner", "enabled", "next run", "last run"], rows));
+        },
+    },
+    "worker runs": {
+        usage: "worker runs <worker-id | skill> [--limit <n>]",
+        async run(args, options) {
+            if (args.length !== 1)
+                throw new CliError("Usage: worker runs <worker-id | skill> [--limit <n>]", exitCodes.usage);
+            const connection = await resolveConnection(options.apiUrl);
+            const id = await workerId(connection, args[0]);
+            const query = options.limit === undefined ? "" : `?limit=${encodeURIComponent(options.limit)}`;
+            const { runs } = await api(connection, `/api/v1/workers/${encodeURIComponent(id)}/runs${query}`);
+            if (options.format === "json")
+                return printJson({ runs });
+            if (runs.length === 0)
+                return console.log("No runs yet.");
+            console.log(renderTable(["id", "version", "status", "queued", "finished", "duration", "ai", "tools", "compute", "error", "report"], runs.map(workerRunRow)));
+        },
+    },
+    "worker run-now": {
+        usage: "worker run-now <worker-id | skill>",
+        async run(args, options) {
+            if (args.length !== 1)
+                throw new CliError("Usage: worker run-now <worker-id | skill>", exitCodes.usage);
+            const connection = await resolveConnection(options.apiUrl);
+            const id = await workerId(connection, args[0]);
+            const queued = await api(connection, `/api/v1/workers/${encodeURIComponent(id)}/run-now`, {});
+            if (options.format === "json")
+                return printJson(queued);
+            console.log(`Queued run ${queued.run.id} (version ${queued.run.version}).`);
+            if (queued.shadow)
+                console.log(`Queued shadow run ${queued.shadow.id} (version ${queued.shadow.version}, practice mode) beside it.`);
+        },
+    },
+    "worker promote": {
+        usage: "worker promote <skill> --workspace <slug>   (operator token)",
+        async run(args, options) {
+            const { promoted } = await changeCandidate("promote", args, options);
+            if (options.format === "json")
+                return printJson({ promoted });
+            console.log(`${promoted.skill} version ${promoted.version} is now in use on ${promoted.moved} worker${promoted.moved === 1 ? "" : "s"}.`);
+        },
+    },
+    "worker drop": {
+        usage: "worker drop <skill> --workspace <slug>   (operator token)",
+        async run(args, options) {
+            const { dropped } = await changeCandidate("drop", args, options);
+            if (options.format === "json")
+                return printJson({ dropped });
+            console.log(`Stopped trying ${dropped.skill} version ${dropped.version} on ${dropped.workspace}. Runs stay on version ${dropped.versionInUse}.`);
+        },
+    },
+    "runner once": {
+        usage: `runner once [--run <id>] [--max-seconds <n>]   (takes the runner token in ${RUNNER_TOKEN_ENV})`,
+        async run(args, options) {
+            if (args.length > 0)
+                throw new CliError("Usage: runner once [--run <id>] [--max-seconds <n>]", exitCodes.usage);
+            await withRunner(options, async (runner) => {
+                const outcome = await runOnce({ ...runner, runId: options.run });
+                if (outcome.kind === "idle")
+                    console.log("No run is queued.");
+                else if (outcome.status !== "succeeded")
+                    process.exitCode = exitCodes.error;
+            });
+        },
+    },
+    runner: {
+        usage: `runner [--max-seconds <n>]   (does queued runs one at a time until stopped)`,
+        async run(args, options) {
+            if (args.length > 0 || options.run !== undefined)
+                throw new CliError("Usage: runner [--max-seconds <n>]", exitCodes.usage);
+            await withRunner(options, runLoop);
+        },
+    },
+    docs: {
+        usage: "docs [meta-ads|p3-refresh]",
+        async run(args) {
+            const [which] = args;
+            if (args.length > 1 || (which !== undefined && !isPlaybook(which)))
+                throw new CliError("Usage: docs [meta-ads|p3-refresh]", exitCodes.usage);
+            process.stdout.write(which === undefined ? guide : playbooks[which].text);
+        },
+    },
+};
+/** Runs `work` with the runner's settings from the environment; SIGINT or SIGTERM stops the run in hand, reported failed. */
+async function withRunner(options, work) {
+    const token = process.env[RUNNER_TOKEN_ENV];
+    if (!token)
+        throw new CliError(`Set ${RUNNER_TOKEN_ENV} to this machine's runner token.`, exitCodes.auth);
+    const stop = new AbortController();
+    const onSignal = () => stop.abort();
+    process.on("SIGINT", onSignal);
+    process.on("SIGTERM", onSignal);
+    try {
+        await work({
+            apiUrl: resolveApiUrl(options.apiUrl, null),
+            token,
+            harnessCommand: process.env[HARNESS_COMMAND_ENV] || undefined,
+            maxSeconds: options.maxSeconds,
+            signal: stop.signal,
+            say: (line) => console.log(line),
+        });
+    }
+    finally {
+        process.off("SIGINT", onSignal);
+        process.off("SIGTERM", onSignal);
+    }
+}
+const playbooks = {
+    "meta-ads": { name: META_ADS_SKILL_NAME, skill: metaAdsSkill, text: metaAdsPlaybook },
+    "p3-refresh": { name: P3_REFRESH_SKILL_NAME, skill: p3RefreshSkill, text: p3RefreshPlaybook },
+};
+const isPlaybook = (name) => Object.hasOwn(playbooks, name);
+const codexSkillsDir = () => join(process.env.CODEX_HOME || join(homedir(), ".codex"), "skills");
+/** Claude Code's skills folder, in the user's home or (with --project) the current folder. */
+function claudeSkillsDir(project) {
+    const root = project ? process.cwd() : homedir();
+    // A cloned repository could point its .claude or .claude/skills elsewhere; the user's own home is trusted.
+    const above = project ? [join(root, ".claude"), join(root, ".claude", "skills")] : [];
+    return { skillsDir: join(root, ".claude", "skills"), above };
+}
+/** Downloads one version from the skill library, checks it, and makes it the installed copy. */
+async function installLibrarySkill(ref, options) {
+    if (options.codex && options.project)
+        throw new CliError("--codex installs a skill for every Codex run, under CODEX_HOME; drop --project", exitCodes.usage);
+    const query = ref.version === null ? "" : `?version=${ref.version}`;
+    const download = await api(await operatorConnection(options.apiUrl), `/api/operator/skills/${ref.name}/download${query}`);
+    const files = unpackSkill(download, await getSigned(download.url));
+    const { skillsDir, above } = options.codex ? { skillsDir: codexSkillsDir(), above: [] } : claudeSkillsDir(options.project);
+    const path = await installSkillFolder(skillsDir, download.name, files, above);
+    console.log(`installed ${download.name} version ${download.version} to ${path}`);
+}
+/** Writes <skillsDir>/<name>/SKILL.md, refusing to follow a symlink at any of `above` or the skill's own paths. */
+async function writeSkill(skillsDir, name, content, above) {
+    const path = await inRunFolder(join(skillsDir, name, "SKILL.md"));
+    const linked = await firstSymlink([...above, join(skillsDir, name), path]);
+    if (linked)
+        throw new CliError(`Refusing to write through the symlink at ${linked}. Remove it and try again.`, exitCodes.error);
+    await mkdir(dirname(path), { recursive: true });
+    await writeFileAtomic(path, content, 0o644);
+    return path;
+}
+const SOURCE_RUNS_SHOWN = 10;
+/** What the source is retrying: "the whole sync since <time>", and each failing part as "<part> since <time>". */
+/** The source's friendly name; a source the platform or AI has not named yet shows as its connector, never its "default" key. */
+function sourceLabel(source) {
+    return source.displayName ?? (source.name === "default" ? (source.connectorName ?? source.connector) : source.name);
+}
+function retryingText(source) {
+    const whole = source.failingSince ? [`the whole sync since ${source.failingSince}`] : [];
+    return [...whole, ...(source.failingParts ?? []).map((p) => `${p.part} since ${p.since}`)].join(", ");
+}
+function historyText(history) {
+    if (history === null)
+        return "nothing left to fetch";
+    const main = history.doneSince === null ? `not started, back to ${history.targetSince}` : `fetched back to ${history.doneSince}, of ${history.targetSince}`;
+    const catchingUp = Object.entries(history.catchUp ?? {}).map(([part, range]) => `; ${part} fetching again, ${range.until} back to ${range.since}`);
+    return main + catchingUp.join("");
+}
+const FUNNEL_NUMBERS = ["spend", "leads", "booked_calls", "calls_held", "sales_count", "revenue_net", "cost_per_lead", "cost_per_booked_call", "cost_per_sale", "roas"];
+const MONEY_NUMBERS = ["gross", "refunds", "net", "orders", "ad_spend", "affiliate_payouts", "left_after_ad_costs", "roas"];
+const CAMPAIGN_NUMBERS = [
+    "spend",
+    "leads_first_touch",
+    "leads_last_touch",
+    "booked_calls_first_touch",
+    "sales_first_touch",
+    "revenue_first_touch",
+    "revenue_last_touch",
+    "cost_per_lead_first_touch",
+    "roas_first_touch",
+    "roas_last_touch",
+];
+function reportQuery(options, extra) {
+    const query = new URLSearchParams();
+    for (const [name, value] of Object.entries({ from: options.from, to: options.to, ...extra }))
+        if (value !== undefined)
+            query.set(name, value);
+    return query.size ? `?${query}` : "";
+}
+/** The rows, then the totals, which are one row per currency. */
+function printReport(title, report, labels, numbers) {
+    if (report.rows.length === 0)
+        return console.log(`No numbers from ${report.from} to ${report.to}.`);
+    console.log(`${title}, ${report.from} to ${report.to}:`);
+    console.log(renderTable([...labels, ...numbers], report.rows));
+    console.log("\nTotals:");
+    console.log(renderTable(["currency", ...numbers], report.totals));
+}
+const agentPath = (options) => `/api/v1/agents/${encodeURIComponent(options.agent)}`;
+const PROPOSAL_COLUMNS = ["id", "kind", "status", "target", "change", "reason"];
+function proposalChange(p) {
+    if (p.kind === "creative")
+        return p.creative?.assetUrl ?? "";
+    if (p.kind === "p3_refresh_batch") {
+        const { retireAdsetId, snapshot } = p.payload;
+        return `${snapshot?.roster?.length ?? 0} ads, ${retireAdsetId ? `retire ${retireAdsetId}` : "retire none"}`;
+    }
+    return typeof p.payload.changePercent === "number" ? `${p.payload.changePercent}%` : "pause";
+}
+function proposalRow(p) {
+    return { id: p.id, kind: p.kind, status: p.status, target: p.creativeSku ?? Object.values(p.target).join(" "), change: proposalChange(p), reason: excerpt(p.reason, 80) };
+}
+// Codex reads AGENTS.md from the working directory; one this CLI did not write is never replaced.
+async function installAgentsMd(path) {
+    await inRunFolder(path);
+    const linked = await firstSymlink([path]);
+    if (linked)
+        throw new CliError(`Refusing to write through the symlink at ${linked}. Remove it and try again.`, exitCodes.error);
+    const existing = await readFile(path, "utf8").catch((error) => {
+        if (error.code === "ENOENT")
+            return null;
+        throw error;
+    });
+    if (existing !== null && !existing.startsWith(AGENTS_MD_MARKER)) {
+        throw new CliError(`${path} already exists and was not written by ${brand.slug}. Move it, or run Codex from another directory.`, exitCodes.error);
+    }
+    await writeFileAtomic(path, metaAdsAgentsMd, 0o644);
+    console.log(`Installed the meta-ads playbook for Codex to ${path}.`);
+}
+const help = `${brand.name} CLI: read-only SQL on your marketing data warehouse, generation tools, and the creative ledger.
+
+Usage:
+${Object.values(commands)
+    .map((c) => `  ${brand.slug} ${c.usage}`)
+    .join("\n")}
+
+Options:
+  --format table|json   output format (default: table)
+  --api-url <url>       API base URL
+  --wait <seconds>      how long tools run and tools get wait for a run (default: ${DEFAULT_WAIT_SECONDS}; 0 returns at once)
+  --agent <kind>        which agent the agent and memory commands use: meta_ads (default) or p3_refresh; in a worker run, skill
+                        (the run's skill's agent) is the default
+  --kind <kind>         what sends to a new intake address: generic (default), ghl_workflow, aloware, webinarfuel, stealth_seminar or mailgun
+  --retention-days <n>  how many days intake create keeps each event (default: 90)
+  --signing-key-stdin   read the sender's signing key for intake create or intake signing-key from stdin (mailgun needs one)
+  --table <name>        the table import csv loads the file into, or import remove drops, as import_<name>;
+                        for warehouse schema, a table to describe in full; repeat for several
+  --summary             warehouse schema: one short row per table (kind, source, column count, summary)
+  --search <words>      warehouse schema: describe in full the tables whose name, description or columns mention a word
+  --out <path>          the file, or existing folder, creatives download saves to (default: the current folder)
+  --open                open the file creatives download saved
+  --media               with content pull, also save each item's files and HTML under media/ in the folder
+  --full                with content pull, fetch every item, not only what changed since the last pull (brings new numbers)
+  --force               content unpublish: take the page down even while delivering Meta ads link to it
+  --yes                 confirm intake delete or import remove, which delete saved data for good
+  --from <YYYY-MM-DD>   first day funnel, campaigns and money cover (default: 29 days before --to)
+  --to <YYYY-MM-DD>     last day funnel, campaigns and money cover (default: today in the workspace reporting time zone)
+  --grain <grain>       how funnel and money group days: day (default), week (starting Monday) or month
+  --channel <channel>   only this channel's campaigns: meta, google, affiliate, a utm_source, or unknown;
+                        for content track-link, where the link goes: facebook, email, sms or web (default)
+  --campaign <id>       the campaign content track-link puts in utm_campaign
+  --body, --html <text | @file>   the words, or the full HTML, content create, capture and edit save
+  --file <path>         an image, video or audio file, up to 50 MB, content create, capture and edit save; repeat for several
+  --transcript <text | @file>   what is said in the first video or audio file content capture saves, so none is paid for
+  --language <code>     the spoken language of --transcript, such as en
+  --source <text>       where the content content capture saves came from, in words
+  --url <url>           the address of the content content capture saves
+  --tool-run <id>       a succeeded tool run content create and edit link; repeat for several
+  --run <id>            the agent run making the content (content), or the tool run to record (creatives create)
+  --platform, --external-id   where content status launched says it was published, and that platform's id for it
+  --notes <text>        what changed in the version skill publish adds
+  --harness <list>      which agents skill publish marks the skill for: claude, codex, or claude,codex (default)
+  --text <words>        words content search finds in a subject, headline, body or video transcript
+  --mode word|meaning   how content search matches --text: word (default, the words themselves) or meaning (close in meaning, nearest first; no --sort)
+  --kind, --platform, --origin   which content content search returns and content pull copies (ad, email, sms, ...; meta, ghl, ...; discovered or made)
+  --from, --to <YYYY-MM-DD>   with content search, only content live on those days
+  --from, --to <n>      with content diff, the two versions to compare (default: the one before the current one, and the current one)
+  --sort <column>       how content search sorts: recent (default) or a content_scorecard number, such as click_rate or roas
+  --order desc|asc      content search's sort direction (default: desc, best or newest first)
+  --limit <n>           how many results content search, creatives list and campaigns return
+  --max-seconds <n>     stop a runner's run after this many seconds, if that comes before its deadline
+  --workspace <slug>    the workspace whose worker worker promote and worker drop change
+  -h, --help            show this help
+
+skill publish, skill list and skill install <name> use the skill library, which takes the operator token in
+${envPrefix}_OPERATOR_TOKEN instead of an API key, as do worker promote and worker drop. worker promote makes the
+version a worker is trying the one in use, there and on every worker of the skill on an older version; worker drop
+stops trying it.
+
+runner and runner once take the runner token in ${RUNNER_TOKEN_ENV}. ${HARNESS_COMMAND_ENV}, if set, names a program
+the runner starts instead of Claude Code or Codex.
+
+Run \`${brand.slug} docs\` for the full guide.
+`;
+function parseOptions(argv) {
+    const { values, positionals } = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: {
+            format: { type: "string", default: "table" },
+            "api-url": { type: "string" },
+            file: { type: "string", multiple: true },
+            project: { type: "boolean", default: false },
+            input: { type: "string" },
+            "idempotency-key": { type: "string" },
+            wait: { type: "string", default: String(DEFAULT_WAIT_SECONDS) },
+            status: { type: "string" },
+            kind: { type: "string" },
+            limit: { type: "string" },
+            run: { type: "string" },
+            lineage: { type: "string" },
+            sources: { type: "string" },
+            codex: { type: "boolean", default: false },
+            agent: { type: "string" },
+            "retention-days": { type: "string" },
+            "signing-key-stdin": { type: "boolean", default: false },
+            table: { type: "string", multiple: true },
+            summary: { type: "boolean", default: false },
+            search: { type: "string" },
+            out: { type: "string" },
+            open: { type: "boolean", default: false },
+            media: { type: "boolean", default: false },
+            full: { type: "boolean", default: false },
+            force: { type: "boolean", default: false },
+            yes: { type: "boolean", default: false },
+            from: { type: "string" },
+            to: { type: "string" },
+            grain: { type: "string" },
+            channel: { type: "string" },
+            campaign: { type: "string" },
+            name: { type: "string" },
+            subject: { type: "string" },
+            preview: { type: "string" },
+            headline: { type: "string" },
+            body: { type: "string" },
+            html: { type: "string" },
+            fields: { type: "string" },
+            transcript: { type: "string" },
+            language: { type: "string" },
+            source: { type: "string" },
+            url: { type: "string" },
+            "tool-run": { type: "string", multiple: true },
+            note: { type: "string" },
+            notes: { type: "string" },
+            harness: { type: "string" },
+            platform: { type: "string" },
+            "external-id": { type: "string" },
+            origin: { type: "string" },
+            text: { type: "string" },
+            mode: { type: "string" },
+            sort: { type: "string" },
+            order: { type: "string" },
+            goal: { type: "string" },
+            target: { type: "string" },
+            landing: { type: "string" },
+            "landing-url": { type: "string" },
+            role: { type: "string" },
+            position: { type: "string" },
+            plan: { type: "string" },
+            version: { type: "string" },
+            workspace: { type: "string" },
+            "max-seconds": { type: "string" },
+            help: { type: "boolean", short: "h", default: false },
+        },
+    });
+    if (values.format !== "table" && values.format !== "json") {
+        throw new CliError('--format must be "table" or "json".', exitCodes.usage);
+    }
+    const wait = Number(values.wait);
+    if (!Number.isInteger(wait) || wait < 0)
+        throw new CliError("--wait must be a whole number of seconds.", exitCodes.usage);
+    const maxSeconds = values["max-seconds"] === undefined ? undefined : Number(values["max-seconds"]);
+    if (maxSeconds !== undefined && (!Number.isInteger(maxSeconds) || maxSeconds < 1)) {
+        throw new CliError("--max-seconds must be a whole number of seconds, at least 1.", exitCodes.usage);
+    }
+    return {
+        positionals,
+        help: values.help,
+        options: {
+            format: values.format,
+            apiUrl: values["api-url"],
+            file: values.file?.at(-1),
+            files: values.file ?? [],
+            project: values.project,
+            input: values.input,
+            idempotencyKey: values["idempotency-key"],
+            wait,
+            status: values.status,
+            kind: values.kind,
+            limit: values.limit,
+            run: values.run,
+            lineage: values.lineage,
+            sources: values.sources,
+            codex: values.codex,
+            agent: values.agent ?? (process.env[AGENT_ENV] || "meta_ads"),
+            retentionDays: values["retention-days"],
+            signingKeyStdin: values["signing-key-stdin"],
+            table: values.table?.at(-1),
+            tables: values.table ?? [],
+            summary: values.summary,
+            search: values.search,
+            out: values.out,
+            open: values.open,
+            media: values.media,
+            full: values.full,
+            force: values.force,
+            yes: values.yes,
+            from: values.from,
+            to: values.to,
+            grain: values.grain,
+            channel: values.channel,
+            campaign: values.campaign,
+            name: values.name,
+            subject: values.subject,
+            preview: values.preview,
+            headline: values.headline,
+            body: values.body,
+            html: values.html,
+            fields: values.fields,
+            transcript: values.transcript,
+            language: values.language,
+            source: values.source,
+            url: values.url,
+            toolRuns: values["tool-run"] ?? [],
+            note: values.note,
+            notes: values.notes,
+            harness: values.harness,
+            platform: values.platform,
+            externalId: values["external-id"],
+            origin: values.origin,
+            text: values.text,
+            mode: values.mode,
+            sort: values.sort,
+            order: values.order,
+            goal: values.goal,
+            target: values.target,
+            landing: values.landing,
+            landingUrl: values["landing-url"],
+            role: values.role,
+            position: values.position,
+            plan: values.plan,
+            version: values.version,
+            workspace: values.workspace,
+            maxSeconds,
+        },
+    };
+}
+/** Promotes or drops the candidate version of a workspace's worker for a skill, with the operator token. */
+async function changeCandidate(change, args, options) {
+    if (args.length !== 1 || !options.workspace)
+        throw new CliError(`Usage: worker ${change} <skill> --workspace <slug>`, exitCodes.usage);
+    return api(await operatorConnection(options.apiUrl), `/api/operator/workers/${change}`, { workspace: options.workspace, skill: args[0] });
+}
+function findCommand(positionals) {
+    const two = positionals.slice(0, 2).join(" ");
+    if (Object.hasOwn(commands, two))
+        return { command: commands[two], args: positionals.slice(2) };
+    const one = positionals[0] ?? "";
+    return Object.hasOwn(commands, one) ? { command: commands[one], args: positionals.slice(1) } : null;
+}
+async function readStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin)
+        chunks.push(chunk);
+    return Buffer.concat(chunks).toString("utf8");
+}
+async function readKeyFromUser() {
+    const fromEnv = process.env[`${envPrefix}_API_KEY`];
+    const key = (fromEnv || (process.stdin.isTTY ? await promptHidden("Paste your API key: ") : await readStdin())).trim();
+    if (!key)
+        throw new CliError(`No API key given. Paste it when asked, pipe it on stdin, or set ${envPrefix}_API_KEY.`, exitCodes.usage);
+    return key;
+}
+async function readSigningKey() {
+    const key = (process.stdin.isTTY ? await promptHidden("Paste the signing key: ") : await readStdin()).trim();
+    if (!key)
+        throw new CliError("No signing key given. Paste it when asked or pipe it on stdin.", exitCodes.usage);
+    return key;
+}
+function promptHidden(prompt) {
+    const stdin = process.stdin;
+    return new Promise((resolve, reject) => {
+        let value = "";
+        let escape = "none";
+        let settled = false;
+        const settle = (error) => {
+            if (settled)
+                return;
+            settled = true;
+            stdin.off("data", onData);
+            stdin.off("error", settle);
+            stdin.off("end", onEnd);
+            process.off("SIGINT", onSigint);
+            if (stdin.isRaw)
+                stdin.setRawMode(false);
+            stdin.pause();
+            process.stderr.write("\n");
+            if (error)
+                reject(error);
+            else
+                resolve(value);
+        };
+        const onSigint = () => settle(new CliError("Cancelled.", exitCodes.interrupted));
+        const onEnd = () => settle();
+        const onData = (chunk) => {
+            try {
+                for (const char of chunk) {
+                    if (escape === "start") {
+                        escape = char === "[" || char === "O" ? "sequence" : "none";
+                    }
+                    else if (escape === "sequence") {
+                        if (char >= "@" && char <= "~")
+                            escape = "none";
+                    }
+                    else if (char === "\u001b") {
+                        escape = "start";
+                    }
+                    else if (char === "\r" || char === "\n") {
+                        return settle();
+                    }
+                    else if (char === "\u0003") {
+                        return onSigint();
+                    }
+                    else if (char === "\u007f" || char === "\b") {
+                        value = value.slice(0, -1);
+                    }
+                    else if (char >= " ") {
+                        value += char;
+                    }
+                }
+            }
+            catch (error) {
+                settle(error);
+            }
+        };
+        process.once("SIGINT", onSigint);
+        stdin.on("error", settle);
+        stdin.once("end", onEnd);
+        try {
+            stdin.setRawMode(true);
+            stdin.setEncoding("utf8");
+            stdin.on("data", onData);
+            stdin.resume();
+        }
+        catch (error) {
+            return settle(error);
+        }
+        process.stderr.write(prompt);
+    });
+}
+async function readSql(args, file) {
+    if (args.length > 1) {
+        throw new CliError('Pass the SQL as one quoted argument: warehouse query "SELECT ..."', exitCodes.usage);
+    }
+    let sql;
+    if (file)
+        sql = await readFile(await inRunFolder(file), "utf8");
+    else if (args[0] !== undefined && args[0] !== "-")
+        sql = args[0];
+    else if (args[0] === "-" || !process.stdin.isTTY)
+        sql = await readStdin();
+    else
+        sql = "";
+    if (!sql.trim())
+        throw new CliError('No SQL given. Usage: warehouse query "<sql>" | --file <path> | < query.sql', exitCodes.usage);
+    return sql;
+}
+async function readText(file, what) {
+    const text = file ? await readFile(await inRunFolder(file), "utf8") : process.stdin.isTTY ? "" : await readStdin();
+    if (!text.trim())
+        throw new CliError(`No text given for ${what}. Pass --file <path> or pipe it on stdin.`, exitCodes.usage);
+    return text;
+}
+/** A JSON flag value, or `@path` to read the JSON from a file. */
+async function parseJson(value, flag) {
+    const text = value.startsWith("@") ? await readFile(await inRunFolder(value.slice(1)), "utf8") : value;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        throw new CliError(`${flag} is not valid JSON: ${excerpt(text)}`, exitCodes.usage);
+    }
+}
+/** A flag's text, or `@path` to read the text from a file. */
+async function textOrFile(value) {
+    return value.startsWith("@") ? readFile(await inRunFolder(value.slice(1)), "utf8") : value;
+}
+const FILE_TYPES = {
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".png": "image/png",
+    ".webp": "image/webp",
+    ".gif": "image/gif",
+    ".mp4": "video/mp4",
+    ".mov": "video/quicktime",
+    ".webm": "video/webm",
+    ".mp3": "audio/mpeg",
+    ".m4a": "audio/mp4",
+    ".wav": "audio/wav",
+};
+// The server takes at most this many bytes of base64 files and HTML in one request.
+const INLINE_CONTENT_BYTES = 3 * 1024 * 1024;
+/**
+ * The request body the content create and edit flags describe; flags not given are left out. Files go base64 while
+ * they and the HTML fit in one request; any other file goes to storage first and is named by its upload id.
+ */
+async function contentInput(options, connection) {
+    const html = options.html === undefined ? undefined : await textOrFile(options.html);
+    let inline = html === undefined ? 0 : Buffer.byteLength(html);
+    const files = [];
+    for (const path of options.files) {
+        const contentType = FILE_TYPES[extname(path).toLowerCase()];
+        if (!contentType)
+            throw new CliError(`${path}: --file takes ${Object.keys(FILE_TYPES).join(", ")} files.`, exitCodes.usage);
+        const data = await readFile(await inRunFolder(path));
+        if (inline + data.byteLength <= INLINE_CONTENT_BYTES) {
+            inline += data.byteLength;
+            files.push({ base64: data.toString("base64"), contentType });
+        }
+        else {
+            files.push({ uploadId: await uploadContentFile(connection, data, contentType) });
+        }
+    }
+    const input = {
+        name: options.name,
+        subject: options.subject,
+        previewText: options.preview,
+        headline: options.headline,
+        body: options.body === undefined ? undefined : await textOrFile(options.body),
+        html,
+        fields: options.fields === undefined ? undefined : await parseJson(options.fields, "--fields"),
+        files: files.length > 0 ? files : undefined,
+        toolRunIds: options.toolRuns.length > 0 ? options.toolRuns : undefined,
+        runId: options.run,
+        note: options.note,
+    };
+    return Object.fromEntries(Object.entries(input).filter(([, value]) => value !== undefined));
+}
+function deploymentLine(d) {
+    const line = `${d.url} v${d.version} ${d.status} (${d.id})`;
+    if (d.pageItemId === null)
+        return line;
+    return `${line}, read as ${d.pageItemId} v${d.currentPageVersion}, edited on the host ${d.editedOnHost} ${d.editedOnHost === 1 ? "time" : "times"} since it went live`;
+}
+async function uploadContentFile(connection, data, contentType) {
+    const upload = await api(connection, "/api/v1/content/uploads", { contentType, bytes: data.byteLength });
+    await putSigned(upload.url, data, contentType);
+    return upload.uploadId;
+}
+function printContent(content, format) {
+    if (format === "json")
+        return printJson(content);
+    const { item, version } = content;
+    const rows = {
+        sku: item.sku,
+        id: item.id,
+        kind: item.kind,
+        status: item.status,
+        name: item.name,
+        version: content.created === false ? `${version.version} (unchanged)` : version.version,
+        subject: version.subject,
+        preview: version.previewText,
+        headline: version.headline,
+        body: version.body ? excerpt(version.body) : null,
+        html: version.htmlUrl,
+        files: version.media.length ? version.media.map((m) => m.url).join(" ") : null,
+        links: item.links.length
+            ? item.links.map((l) => `${l.platform} ${l.objectType} ${l.externalId}${l.removedAt ? ` (no longer on ${l.platform})` : ""}`).join(", ")
+            : null,
+        by: version.capturedBy,
+        note: version.note,
+        publications: content.publications?.length
+            ? content.publications.map((p) => [p.platform, p.objectType, p.externalId, p.status].filter(Boolean).join(" ")).join(", ")
+            : null,
+        "live copy of": item.liveCopyOf ? `${item.liveCopyOf.sku ?? item.liveCopyOf.itemId} (deployment ${item.liveCopyOf.deploymentId})` : null,
+        deployments: content.deployments?.length ? content.deployments.map(deploymentLine).join(", ") : null,
+        versions: content.versions && content.versions.length > 1 ? content.versions.length : null,
+        transcript: content.transcripts?.map((t) => (t.text ? excerpt(t.text, 80) : t.status)).join(" | ") || null,
+        ...scoreFields(content.scorecards ?? []),
+    };
+    printFields(rows);
+}
+function printContentDiff(diff) {
+    const stamp = (sign, v) => `${sign} version ${v.version}, ${v.capturedAt} by ${v.capturedBy}${v.note ? `: ${v.note}` : ""}`;
+    const value = (v) => (typeof v === "string" ? v : JSON.stringify(v));
+    const lines = [`${diff.item.sku ?? diff.item.id} (${diff.item.kind}${diff.item.name ? `, ${diff.item.name}` : ""})`, stamp("---", diff.from), stamp("+++", diff.to)];
+    const section = (title, rows) => {
+        if (rows.length > 0)
+            lines.push("", title, ...rows);
+    };
+    for (const c of diff.changed)
+        section(c.field, [...(c.from === null ? [] : [`- ${c.from}`]), ...(c.to === null ? [] : [`+ ${c.to}`])]);
+    section("body", diff.body.map((l) => (l.op === "skip" ? `  ... ${l.lines} unchanged line${l.lines === 1 ? "" : "s"}` : `${{ same: " ", add: "+", remove: "-" }[l.op]} ${l.text}`)));
+    for (const l of diff.lists)
+        section(l.field, [...l.removed.map((v) => `- ${value(v)}`), ...l.added.map((v) => `+ ${value(v)}`)]);
+    if (diff.html)
+        section("html", [...(diff.html.fromUrl ? [`- ${diff.html.fromUrl}`] : []), ...(diff.html.toUrl ? [`+ ${diff.html.toUrl}`] : [])]);
+    const file = (m) => `${m.contentType} ${m.sha256.slice(0, 12)} ${m.url}`;
+    section("files", [...diff.media.removed.map((m) => `- ${file(m)}`), ...diff.media.added.map((m) => `+ ${file(m)}`)]);
+    if (lines.length === 3)
+        lines.push("", "No changes.");
+    console.log(lines.join("\n"));
+}
+const planPath = (id) => `/api/v1/launch-plans/${encodeURIComponent(id)}`;
+function printPlan(plan, format) {
+    if (format === "json")
+        return printJson({ plan });
+    printFields({
+        id: plan.id,
+        name: plan.name,
+        goal: excerpt(plan.goal),
+        channel: plan.channel,
+        target: plan.target && JSON.stringify(plan.target),
+        landing: plan.landingUrl ?? plan.landingItemId,
+        status: plan.status,
+        next: plan.moves.length ? plan.moves.join(", ") : null,
+        by: plan.createdBy,
+    });
+    console.log("");
+    if (plan.items.length === 0)
+        return console.log("No items yet.");
+    console.log(renderTable(["position", "sku", "kind", "role", "status", "name"], plan.items));
+}
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const dollars = (cents) => `$${(cents / 100).toFixed(2)}`;
+/** The workspace's worker for the skill named `ref`, else the worker whose id it is: a skill's name may look like a uuid. */
+async function workerId(connection, ref) {
+    const { workers } = await api(connection, "/api/v1/workers");
+    const found = workers.find((w) => w.skill === ref) ?? workers.find((w) => w.id === ref.toLowerCase());
+    if (!found)
+        throw new CliError(`unknown_worker: no worker with skill or id ${JSON.stringify(ref)} in this workspace`, exitCodes.error);
+    return found.id;
+}
+function workerRunRow(r) {
+    const cents = (value) => (value === null ? "" : dollars(value));
+    const seconds = r.startedAt && r.finishedAt ? Math.round((Date.parse(r.finishedAt) - Date.parse(r.startedAt)) / 1000) : null;
+    return {
+        id: r.shadowOf ? `${r.id} (shadow)` : r.id,
+        version: r.version,
+        status: r.reason ? `${r.status} (${r.reason})` : r.status,
+        queued: r.queuedAt,
+        finished: r.finishedAt,
+        duration: seconds === null ? "" : `${seconds}s`,
+        ai: cents(r.aiCents),
+        tools: cents(r.toolCents),
+        compute: cents(r.computeCents),
+        error: r.error && excerpt(r.error),
+        report: r.reportLine && excerpt(r.reportLine),
+    };
+}
+/** The name now, and the name when published after it when the two differ. */
+function trailName(o) {
+    const now = o.name ?? o.id;
+    return o.nameAtPublish && o.nameAtPublish !== o.name ? `${now} (was ${o.nameAtPublish})` : now;
+}
+function printTrail(trail, format) {
+    if (format === "json")
+        return printJson({ trail });
+    const { totals } = trail;
+    printFields({
+        plan: trail.plan && `${trail.plan.name} (${trail.plan.id}, ${trail.plan.status})`,
+        "making cost": dollars(totals.makingCents),
+        ...Object.fromEntries(totals.ads.map((a) => [`ads ${a.currency}`, `spend ${a.lifetime.spend ?? 0}, purchases ${a.lifetime.purchases ?? 0}, revenue ${a.lifetime.revenue ?? 0} (30 days: spend ${a.last30Days.spend ?? 0})`])),
+        leads: totals.items.lifetime.leads,
+        sales: totals.items.lifetime.sales,
+    });
+    console.log("");
+    if (trail.items.length === 0)
+        return console.log("No items yet.");
+    const items = trail.items.map((i) => ({
+        sku: i.sku ?? i.id,
+        kind: i.kind,
+        status: i.status,
+        "made with": [...new Set(i.madeWith.map((r) => r.tool))].join(", "),
+        cost: dollars(i.makingCents),
+        leads: i.results.lifetime.leads,
+        sales: i.results.lifetime.sales,
+    }));
+    console.log(renderTable(["sku", "kind", "status", "made with", "cost", "leads", "sales"], items));
+    const lines = trail.items.flatMap((i) => i.publications.map((p) => ({
+        sku: i.sku ?? i.id,
+        where: `${p.platform} ${p.objectType} ${p.externalId ?? ""}`.trim(),
+        status: p.status,
+        campaign: trailName(p.campaign),
+        "ad set": trailName(p.adset),
+        ad: trailName(p.ad),
+        delivery: p.ad.status,
+        spend: p.results.lifetime.spend === null ? null : `${p.results.lifetime.spend} ${p.results.currency}`,
+        purchases: p.results.lifetime.purchases,
+    })));
+    console.log("");
+    if (lines.length === 0)
+        return console.log("Not published anywhere yet.");
+    console.log(renderTable(["sku", "where", "status", "campaign", "ad set", "ad", "delivery", "spend", "purchases"], lines));
+}
+/** One scorecard column as a table cell: the number, or each currency's number when the item has money in several. */
+function scoreCell(scorecards, column) {
+    const scored = scorecards.filter((s) => s.numbers[column] !== undefined);
+    if (scored.length <= 1)
+        return scored[0]?.numbers[column] ?? null;
+    return scored.map((s) => `${s.numbers[column]} ${s.currency ?? ""}`.trimEnd()).join(", ");
+}
+/** Every scorecard number as a field, named with its currency when the item has money in several. */
+function scoreFields(scorecards) {
+    if (scorecards.length === 1)
+        return { currency: scorecards[0].currency, ...scorecards[0].numbers };
+    return Object.fromEntries(scorecards.flatMap((s) => Object.entries(s.numbers).map(([column, value]) => [`${column} (${s.currency ?? "no money"})`, value])));
+}
+function printFields(rows) {
+    console.log(renderTable(["field", "value"], Object.entries(rows).filter(([, v]) => v != null).map(([field, value]) => ({ field, value }))));
+}
+function printPublication(publication, format) {
+    if (format === "json")
+        return printJson({ publication });
+    printFields({
+        publication: publication.id,
+        item: publication.itemId,
+        version: publication.version,
+        platform: publication.platform,
+        publisher: publication.publisher,
+        account: publication.accountId,
+        object: publication.objectType,
+        "external id": publication.externalId,
+        status: publication.status,
+        error: publication.error,
+        recorded: publication.recordedAt,
+        sent: publication.sentAt,
+        finished: publication.finishedAt,
+    });
+}
+async function readToolInput(options) {
+    let text;
+    if (options.input !== undefined)
+        text = options.input;
+    else if (options.file)
+        text = await readFile(await inRunFolder(options.file), "utf8");
+    else if (!process.stdin.isTTY)
+        text = await readStdin();
+    else
+        text = "";
+    if (!text.trim())
+        return {};
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        throw new CliError(`The tool input is not valid JSON: ${excerpt(text)}`, exitCodes.usage);
+    }
+}
+// The server holds a request open for at most SERVER_WAIT_CAP seconds, so longer waits are several requests.
+async function waitForRun(connection, run, seconds) {
+    const deadline = Date.now() + seconds * 1000;
+    let current = run;
+    while ((current.status === "pending" || current.status === "running") && Date.now() < deadline) {
+        const wait = Math.max(1, Math.min(SERVER_WAIT_CAP, Math.ceil((deadline - Date.now()) / 1000)));
+        current = (await api(connection, `/api/v1/runs/${current.id}?wait=${wait}`)).run;
+    }
+    return current;
+}
+function printRun(run, format) {
+    if (run.status === "failed" || run.status === "lost")
+        process.exitCode = exitCodes.error;
+    if (format === "json")
+        return printJson({ run });
+    const rows = [
+        { field: "run", value: run.id },
+        { field: "tool", value: run.tool },
+        { field: "status", value: run.status },
+        { field: "estimatedCents", value: run.estimatedCents },
+        { field: "actualCents", value: run.actualCents },
+    ];
+    if (run.error)
+        rows.push({ field: "error", value: run.error });
+    for (const asset of run.result?.assets ?? [])
+        rows.push({ field: "asset", value: asset.url });
+    if (run.result?.data !== undefined)
+        rows.push({ field: "data", value: run.result.data });
+    console.log(renderTable(["field", "value"], rows));
+    if (run.result?.text)
+        console.log(`\n${run.result.text}`);
+    if (run.status === "pending" || run.status === "running") {
+        console.error(`Still ${run.status}. Check again with: ${brand.slug} tools get ${run.id} --wait 60`);
+    }
+}
+const HOSTED_UPLOAD_MB = 4.5;
+const megabytes = (bytes) => Math.round((bytes / (1024 * 1024)) * 10) / 10;
+/** A file over the hosted app's request limit goes to storage first, and the server imports it from there. */
+async function uploadCsv(connection, name, file) {
+    const table = `/api/v1/imports/csv?table=${encodeURIComponent(name)}`;
+    if (file.byteLength > HOSTED_UPLOAD_MB * 1024 * 1024) {
+        const upload = await api(connection, "/api/v1/imports/csv/uploads", {}).catch((error) => {
+            // A server without storage takes the file directly, which works for anything its host lets through.
+            if (error instanceof ApiError && error.code === "storage_not_configured")
+                return null;
+            throw error;
+        });
+        if (upload) {
+            await putSigned(upload.uploadUrl, file, "text/csv");
+            return api(connection, `${table}&upload=${encodeURIComponent(upload.uploadId)}`, undefined, "POST");
+        }
+    }
+    try {
+        return await apiUpload(connection, table, file, "text/csv");
+    }
+    catch (error) {
+        // The importer's own 413 is too_large; any other 413 is the hosting platform refusing the body before the app sees it.
+        if (error instanceof ApiError && error.status === 413 && error.code !== "too_large") {
+            throw new CliError(`The server accepts at most ${HOSTED_UPLOAD_MB} MB per upload and has no file storage set up for bigger files, and this file is ${megabytes(file.byteLength)} MB. Split it into smaller files and import each under its own name.`, exitCodes.error);
+        }
+        throw error;
+    }
+}
+/** Refuses a name the server would refuse, before anything is sent. */
+function importName(name) {
+    if (!IMPORT_NAME_PATTERN.test(name)) {
+        throw new CliError(`"${excerpt(name)}" can't be a table name. Use lowercase letters, digits and underscores, start with a letter, and keep it to 41 characters or fewer.`, exitCodes.usage);
+    }
+    return name;
+}
+async function readImportFile(path) {
+    await inRunFolder(path);
+    const info = await stat(path).catch((error) => {
+        if (error.code === "ENOENT")
+            throw new CliError(`No file at ${path}.`, exitCodes.usage);
+        throw error;
+    });
+    if (!info.isFile())
+        throw new CliError(`${path} is not a file.`, exitCodes.usage);
+    if (info.size > IMPORT_LIMITS.bytes) {
+        throw new CliError(`${path} is ${megabytes(info.size)} MB. An import takes at most ${IMPORT_LIMITS.bytes / (1024 * 1024)} MB; split the file and import each part under its own name.`, exitCodes.error);
+    }
+    return readFile(path);
+}
+const ASSET_ROUTE = "/api/v1/assets/";
+/** What `creatives download` fetches, from a SKU, an asset path, or an asset link as `creatives show` prints it. */
+async function downloadTarget(arg, connection) {
+    const routeAt = arg.indexOf(ASSET_ROUTE);
+    if (routeAt !== -1 || arg.includes("/")) {
+        const assetPath = routeAt === -1 ? arg : decodeLinkPath(arg.slice(routeAt + ASSET_ROUTE.length).replace(/[?#].*$/, ""));
+        return { label: assetPath, assetPath, fileName: basename(assetPath) };
+    }
+    const { creative } = await api(connection, `/api/v1/creatives/${encodeURIComponent(arg)}`);
+    if (!creative.assetPath) {
+        const copy = creative.kind === "copy" ? ` It is copy; its text is in \`${brand.slug} creatives show ${creative.sku}\`.` : "";
+        throw new CliError(`${creative.sku} has no file to download.${copy}`, exitCodes.error);
+    }
+    return { label: creative.sku, assetPath: creative.assetPath, fileName: `${creative.sku}${extname(creative.assetPath)}` };
+}
+function decodeLinkPath(encoded) {
+    try {
+        return encoded.split("/").map(decodeURIComponent).join("/");
+    }
+    catch {
+        throw new CliError(`"${excerpt(encoded)}" is not a valid asset link.`, exitCodes.usage);
+    }
+}
+/** `--out` names the file, or an existing folder to save into under the default name. */
+async function savePath(out, fileName) {
+    if (out === undefined)
+        return inRunFolder(fileName);
+    const info = await stat(await inRunFolder(out)).catch((error) => {
+        if (error.code === "ENOENT")
+            return null;
+        throw error;
+    });
+    return inRunFolder(info?.isDirectory() ? join(out, fileName) : out);
+}
+function extensionFor(contentType) {
+    const subtype = contentType?.split(";")[0].split("/")[1]?.trim();
+    return subtype && /^[a-z0-9]+$/.test(subtype) ? subtype : "bin";
+}
+function fileSize(bytes) {
+    if (bytes < 1024)
+        return `${bytes} ${bytes === 1 ? "byte" : "bytes"}`;
+    return bytes < 1024 * 1024 ? `${(bytes / 1024).toFixed(1)} KB` : `${megabytes(bytes)} MB`;
+}
+function openFile(path) {
+    const [command, args] = process.platform === "darwin" ? ["open", [path]] : process.platform === "win32" ? ["explorer.exe", [path]] : ["xdg-open", [path]];
+    const child = spawn(command, args, { detached: true, stdio: "ignore" });
+    child.on("error", (error) => console.error(`Saved, but could not open it: ${error.message}`));
+    child.unref();
+}
+const INTAKE_PATH = "/api/v1/intake-endpoints";
+const intakePath = (id) => `${INTAKE_PATH}/${encodeURIComponent(id)}`;
+function parseRetentionDays(text) {
+    const days = Number(text);
+    if (!/^\d+$/.test(text) || days < 1)
+        throw new CliError("Retention must be a whole number of days, at least 1.", exitCodes.usage);
+    return days;
+}
+function printIntakeToken({ endpoint, address, token, link }, format) {
+    if (format === "json")
+        printJson({ endpoint, address, token, link });
+    else {
+        if (link)
+            console.log(`Link:    ${link}`);
+        console.log(`Address: ${address}`);
+        console.log(`Header:  Authorization: Bearer ${token}`);
+        console.log(`Token:   ${token}`);
+    }
+    console.error(`The token for ${endpoint.label} is shown only now. Rotate it if it is lost.`);
+}
+async function patchIntake(id, body, options, done) {
+    const { endpoint } = await api(await resolveConnection(options.apiUrl), intakePath(id), body, "PATCH");
+    if (options.format === "json")
+        return printJson({ endpoint });
+    console.log(done(endpoint));
+}
+function excerpt(text, max = 60) {
+    const flat = text.replace(/\s+/g, " ").trim();
+    return flat.length > max ? `${flat.slice(0, max - 1)}…` : flat;
+}
+function keepNumberDigits(_key, value, context) {
+    return typeof value === "number" && context?.source !== undefined ? context.source : value;
+}
+function printJson(value) {
+    console.log(JSON.stringify(value, null, 2));
+}
+function cell(value) {
+    if (value === null || value === undefined)
+        return "";
+    return typeof value === "string" ? value : JSON.stringify(value);
+}
+function renderTable(columns, rows) {
+    const cells = rows.map((row) => columns.map((c) => cell(row[c])));
+    const widths = columns.map((c, i) => Math.max(c.length, ...cells.map((r) => r[i].length)));
+    const line = (values) => values.map((v, i) => v.padEnd(widths[i])).join(" | ").trimEnd();
+    return [line(columns), widths.map((w) => "-".repeat(w)).join("-+-"), ...cells.map(line)].join("\n");
+}
+async function main(argv) {
+    const { positionals, options, help: wantsHelp } = parseOptions(argv);
+    if (wantsHelp || positionals.length === 0) {
+        process.stdout.write(help);
+        return;
+    }
+    const found = findCommand(positionals);
+    if (!found)
+        throw new CliError(`Unknown command. Run \`${brand.slug} --help\`.`, exitCodes.usage);
+    await found.command.run(found.args, options);
+}
+try {
+    await main(process.argv.slice(2));
+}
+catch (error) {
+    if (error instanceof CliError) {
+        console.error(`error: ${error.message}`);
+        if (error instanceof ApiError && error.hint)
+            console.error(`Hint: ${error.hint}`);
+        process.exitCode = error.exitCode;
+    }
+    else if (error.code?.startsWith("ERR_PARSE_ARGS")) {
+        console.error(`error: ${error.message}`);
+        process.exitCode = exitCodes.usage;
+    }
+    else {
+        throw error;
+    }
+}