@wrangled/cli 0.2.0

package/dist/api.js

@@ -0,0 +1,192 @@
+import { mkdir, readFile, rm } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { brand, envPrefix } from "./brand.js";
+import { writeFileAtomic } from "./files.js";
+export const exitCodes = { ok: 0, error: 1, usage: 2, auth: 3, interrupted: 130 };
+export class CliError extends Error {
+    exitCode;
+    constructor(message, exitCode) {
+        super(message);
+        this.exitCode = exitCode;
+    }
+}
+export class UnreadableCredentialsError extends CliError {
+    constructor(path) {
+        super(`The saved credentials at ${path} are unreadable. Run \`${brand.slug} login\` again.`, exitCodes.auth);
+    }
+}
+/** Copies of the server's IMPORT_LIMITS and import name rule; src/lib/cli-consistency.test.ts keeps them in step. */
+export const IMPORT_LIMITS = { bytes: 50 * 1024 * 1024, rows: 1_000_000, columns: 500 };
+export const IMPORT_NAME_PATTERN = /^[a-z][a-z0-9_]{0,40}$/;
+/** `configHome` defaults to $XDG_CONFIG_HOME, or ~/.config. */
+export function credentialsPath(configHome = process.env.XDG_CONFIG_HOME || join(homedir(), ".config")) {
+    return join(configHome, brand.slug, "credentials.json");
+}
+export async function readCredentials() {
+    const path = credentialsPath();
+    let text;
+    try {
+        text = await readFile(path, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return null;
+        throw error;
+    }
+    const credentials = parseCredentials(text);
+    if (!credentials)
+        throw new UnreadableCredentialsError(path);
+    return credentials;
+}
+function parseCredentials(text) {
+    try {
+        const value = JSON.parse(text);
+        if (typeof value?.apiKey !== "string" || typeof value.apiUrl !== "string")
+            return null;
+        return { apiKey: value.apiKey, apiUrl: value.apiUrl };
+    }
+    catch {
+        return null;
+    }
+}
+export async function writeCredentials(credentials, configHome) {
+    const path = credentialsPath(configHome);
+    await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+    await writeFileAtomic(path, `${JSON.stringify(credentials, null, 2)}\n`, 0o600);
+    return path;
+}
+export async function removeCredentials() {
+    await rm(credentialsPath(), { force: true });
+}
+export async function resolveConnection(apiUrlFlag) {
+    const stored = await readCredentials();
+    const apiKey = process.env[`${envPrefix}_API_KEY`] || stored?.apiKey;
+    if (!apiKey) {
+        throw new CliError(`Not logged in. Run \`${brand.slug} login\` or set ${envPrefix}_API_KEY.`, exitCodes.auth);
+    }
+    return { apiUrl: resolveApiUrl(apiUrlFlag, stored), apiKey };
+}
+export function resolveApiUrl(apiUrlFlag, stored) {
+    return (apiUrlFlag || process.env[`${envPrefix}_API_URL`] || stored?.apiUrl || brand.apiUrl).replace(/\/+$/, "");
+}
+export async function api(connection, path, body, method) {
+    return JSON.parse(await apiText(connection, path, body, method));
+}
+export async function apiText(connection, path, body, method) {
+    return send(connection, path, method ?? (body === undefined ? "GET" : "POST"), "application/json", body === undefined ? undefined : JSON.stringify(body));
+}
+/** POSTs `body` as it is, with its own content type, and parses the JSON answer. */
+export async function apiUpload(connection, path, body, contentType) {
+    return JSON.parse(await send(connection, path, "POST", contentType, body));
+}
+/** A non-2xx answer other than 401; `code` is the API's error code when the body carried one. */
+export class ApiError extends CliError {
+    status;
+    code;
+    hint;
+    constructor(message, status, code, hint) {
+        super(message, exitCodes.error);
+        this.status = status;
+        this.code = code;
+        this.hint = hint;
+    }
+}
+async function send(connection, path, method, contentType, body) {
+    const response = await request(connection, path, { method, headers: { "content-type": contentType }, body });
+    if (!response.ok)
+        throw new ApiError(`HTTP ${response.status} from ${path}`, response.status, undefined);
+    return response.text();
+}
+/**
+ * Fetches a stored asset. The API answers with a redirect to a short-lived signed storage URL, which is
+ * fetched without the workspace key. The signed URL carries its own token, so no message ever includes it.
+ */
+export async function apiDownload(connection, path) {
+    const redirect = await request(connection, path, { method: "GET", redirect: "manual" });
+    const location = redirect.headers.get("location");
+    if (redirect.status < 300 || redirect.status >= 400 || !location) {
+        throw new CliError(`Expected a redirect to the file from ${path}, got HTTP ${redirect.status}.`, exitCodes.error);
+    }
+    const signed = new URL(location, connection.apiUrl);
+    let response;
+    try {
+        response = await fetch(signed);
+    }
+    catch (error) {
+        const code = error.cause?.code ?? "network error";
+        throw new CliError(`Cannot reach media storage at ${signed.origin}: ${code}`, exitCodes.error);
+    }
+    if (!response.ok) {
+        await response.body?.cancel();
+        throw new CliError(`Media storage answered HTTP ${response.status} for ${path}. Try again.`, exitCodes.error);
+    }
+    return { bytes: new Uint8Array(await response.arrayBuffer()), contentType: response.headers.get("content-type") };
+}
+/**
+ * PUTs a file to a signed storage URL the API handed out, without the workspace key. The URL carries its own token,
+ * so no message ever includes it.
+ */
+export async function putSigned(signedUrl, body, contentType) {
+    const signed = new URL(signedUrl);
+    let response;
+    try {
+        response = await fetch(signed, { method: "PUT", headers: { "content-type": contentType }, body });
+    }
+    catch (error) {
+        const code = error.cause?.code ?? "network error";
+        throw new CliError(`Cannot reach file storage at ${signed.origin}: ${code}`, exitCodes.error);
+    }
+    await response.body?.cancel();
+    if (!response.ok)
+        throw new CliError(`File storage answered HTTP ${response.status} to the upload. Try again.`, exitCodes.error);
+}
+/**
+ * GETs a file from a signed storage URL the API handed out, without any credential of ours. The URL carries its own
+ * token, so no message ever includes it.
+ */
+export async function getSigned(signedUrl) {
+    const signed = new URL(signedUrl);
+    let response;
+    try {
+        response = await fetch(signed);
+    }
+    catch (error) {
+        const code = error.cause?.code ?? "network error";
+        throw new CliError(`Cannot reach file storage at ${signed.origin}: ${code}`, exitCodes.error);
+    }
+    if (!response.ok) {
+        await response.body?.cancel();
+        throw new CliError(`File storage answered HTTP ${response.status} to the download. Try again.`, exitCodes.error);
+    }
+    return new Uint8Array(await response.arrayBuffer());
+}
+async function request(connection, path, init) {
+    let response;
+    try {
+        response = await fetch(`${connection.apiUrl}${path}`, {
+            ...init,
+            headers: { authorization: `Bearer ${connection.apiKey}`, ...init.headers },
+        });
+    }
+    catch (error) {
+        const cause = error.cause?.message ?? error.message;
+        throw new CliError(`Cannot reach ${connection.apiUrl}: ${cause}`, exitCodes.error);
+    }
+    if (response.status === 401) {
+        throw new CliError(connection.rejected ?? `The API key was rejected by ${connection.apiUrl}. Run \`${brand.slug} login\` with a valid key.`, exitCodes.auth);
+    }
+    if (response.status >= 400) {
+        const error = parseErrorBody(await response.text());
+        throw new ApiError(error ? `${error.code}: ${error.message}` : `HTTP ${response.status} from ${path}`, response.status, error?.code, error?.hint);
+    }
+    return response;
+}
+function parseErrorBody(text) {
+    try {
+        return JSON.parse(text).error;
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/brand.js

@@ -0,0 +1,9 @@
+export const brand = {
+    name: "Wrangled",
+    slug: "wr",
+    apiUrl: "https://app.wrangled.co",
+    apiKeyPrefix: "wr_",
+    legacyApiKeyPrefixes: ["ult_"],
+    runnerTokenPrefix: "wrrun_",
+};
+export const envPrefix = brand.slug.toUpperCase();

package/dist/files.js

@@ -0,0 +1,66 @@
+import { randomBytes } from "node:crypto";
+import { lstat, readlink, realpath, rename, rm, writeFile } from "node:fs/promises";
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { CliError, exitCodes } from "./api.js";
+import { envPrefix } from "./brand.js";
+/** Set by the runner to the run's folder; inside a run, the CLI reads and writes files only there. */
+export const RUN_ROOT_ENV = `${envPrefix}_RUN_ROOT`;
+/**
+ * Returns `path` unchanged, or throws when a run root is set and the path's real location (symlinks followed) is
+ * outside it. A path that does not exist yet is judged by its nearest existing folder.
+ */
+export async function inRunFolder(path) {
+    const root = process.env[RUN_ROOT_ENV];
+    if (!root)
+        return path;
+    const realRoot = await realpath(root);
+    // A sandbox around the CLI (Codex's) can forbid even looking up a path outside the run; that path is judged as written.
+    const realTarget = await realLocation(resolve(path)).catch((error) => {
+        if (error.code === "EPERM" || error.code === "EACCES")
+            return resolve(path);
+        throw error;
+    });
+    const rel = relative(realRoot, realTarget);
+    if (rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel)) {
+        throw new CliError(`${path} is outside this run's folder; inside a run, files can only be read and written there.`, exitCodes.usage);
+    }
+    return path;
+}
+async function realLocation(path) {
+    try {
+        return await realpath(path);
+    }
+    catch (error) {
+        const parent = dirname(path);
+        if (error.code !== "ENOENT" || parent === path)
+            throw error;
+        // A dangling symlink would be written through, so it is judged by where it points.
+        const link = await readlink(path).catch(() => null);
+        if (link !== null)
+            return realLocation(resolve(parent, link));
+        return join(await realLocation(parent), basename(path));
+    }
+}
+export async function writeFileAtomic(path, content, mode) {
+    const temp = join(dirname(path), `.${basename(path)}.${randomBytes(6).toString("hex")}.tmp`);
+    try {
+        await writeFile(temp, content, { mode, flag: "wx" });
+        await rename(temp, path);
+    }
+    catch (error) {
+        await rm(temp, { force: true });
+        throw error;
+    }
+}
+export async function firstSymlink(paths) {
+    for (const path of paths) {
+        const info = await lstat(path).catch((error) => {
+            if (error.code === "ENOENT")
+                return null;
+            throw error;
+        });
+        if (info?.isSymbolicLink())
+            return path;
+    }
+    return null;
+}

package/dist/guide.js

@@ -0,0 +1,221 @@
+import { IMPORT_LIMITS } from "./api.js";
+import { brand, envPrefix } from "./brand.js";
+import { PULL_STATE_FILE } from "./pull.js";
+const cli = brand.slug;
+export const guide = `# ${brand.name} CLI
+
+\`${cli}\` gives read-only SQL access to one client's marketing data warehouse (ad spend, orders, and other synced sources), runs paid generation and research tools for that client, and keeps the creative ledger. Each API key belongs to exactly one workspace, and every command works only in that workspace.
+
+## Setup
+
+1. Check the login: \`${cli} whoami\`. It prints the workspace name, slug, and id.
+2. If it exits with code 3, you are not logged in. Ask the user to run \`${cli} login\` in their own terminal. It prompts for the key without showing it. Never ask for the key in chat and never put it on a command line, where it lands in shell history and logs. In CI, the key comes from the \`${envPrefix}_API_KEY\` environment variable.
+
+## Start with the data guide
+
+Run \`${cli} guide\` first. It says, in plain words, what this workspace has: each connected source with when it last synced and how many rows it holds over which dates; the content library's ads, emails, text messages, landing pages, videos and posts and how many videos and recordings have transcripts; and what is missing, such as a source that is not connected, a failing sync, or videos and recordings without a transcript yet.
+
+## Content: search before SQL
+
+To find content, such as "the 10 emails with the best click rate", "our 5 best videos by return on ad spend" or "every landing page that mentions the guarantee", use \`${cli} content search\` before writing SQL on the \`content_\` tables.
+
+- \`--text "<words>"\` finds words in the current version's subject, headline and body, or in a video's transcript. Words are stemmed ("guarantee" finds "guaranteed"); use "quotes" for a phrase and -word to leave a word out.
+- \`--mode meaning\` finds content that means something close to \`--text\`, even in other words: \`--text "saves time"\` also finds "done in five minutes". Results come nearest first, each with its distance (0 is the same meaning) and the closest passage as its words. It takes no \`--sort\` or \`--order\`, and finds only content embedded so far (each hour, new versions and transcripts are embedded).
+- \`--kind\` (ad, email, sms, landing_page, video, social_post, conversation), \`--platform\` (meta, ghl, klaviyo, roezan, bayengage, google_ads, web, youtube, instagram, workspace, upload) and \`--origin\` (discovered or made) narrow it. \`--from\` and \`--to\` keep content live on those days: from its first day with numbers (or the day the library first saw it) to its last.
+- \`--sort\` is \`recent\` (the default, newest first) or any number in the \`content_scorecard\` view, such as \`click_rate\`, \`open_rate\`, \`roas\`, \`spend\` or their \`_30d\` twins for the last 30 days. Content with money in several currencies has a number per currency and sorts by its best. Content without that number comes last. \`--order asc\` turns it around; \`--limit\` is 1 to 50 (default 10).
+- Each result has the item's id or SKU, its words, how many files it has, whether it has a transcript, and its scorecard numbers. \`${cli} content show <sku | item-id>\` prints one item in full: its words, how many versions it has, its transcript and every number; \`--format json\` adds every version, and links to its files.
+- To add marketing that lives somewhere no source connects to, such as a sales video, a webinar recording, a script or an email from another tool, run \`${cli} content capture --kind <kind> --name <name>\` with \`--body\`, \`--file\`, \`--source\` (where it came from) and \`--url\`. It is kept as found, with no SKU, so it is never approved or published; \`--platform upload\` finds these. Videos and audio are transcribed on their own; give \`--transcript @file\` when you already have one, so none is paid for.
+
+To read the whole library with your own tools, such as "every email we have" or "every transcript", copy it to a folder: \`${cli} content pull <dir>\`. It writes one Markdown file per item, \`<dir>/<kind>/<SKU or natural key>.md\`: front matter with its id, SKU, kind, platform, origin, name, status, version, when that version was captured, \`removed_at\` (set when the platform no longer has it), its links, its HTML and file storage paths, and its scorecard numbers, one set per currency; then its subject, preview text, headline, body, fields (as JSON) and transcripts. Search the folder with grep or open the files. Run the same command again to fetch only what changed since the last pull (the folder's \`${PULL_STATE_FILE}\` remembers where it stopped); only files whose text changed are rewritten, and the output lists them. \`--kind\`, \`--platform\` and \`--origin\` copy part of the library; \`--media\` also saves each item's files and HTML under \`media/\`; \`--full\` fetches every item again, which brings new scorecard numbers, since numbers change without the item changing. A folder holds one workspace's content; pulling another workspace into it is refused.
+
+## Query workflow: schema first
+
+1. Run \`${cli} warehouse schema --summary\` before writing any SQL. It lists each table once: whether it is a table or a view, which source fills it, how many columns it has, and a one-line summary. Then run \`${cli} warehouse schema --table <name>\` (repeat for several) or \`--search <words>\` for the full detail of just the tables you need: every column with its Postgres type, nullability, and description. Plain \`${cli} warehouse schema\` prints every column of every table, which on a big warehouse is a lot. Read the descriptions: they say what null means and which metrics do not add up. Use only these names. Never guess a table or column name.
+2. Write one SQL statement in the PostgreSQL dialect. Refer to tables unqualified (\`FROM orders\`). The workspace schema is already on the search path.
+3. Run it: \`${cli} warehouse query "SELECT ..."\`. For long SQL, use \`--file query.sql\` or pipe it on stdin.
+4. Aggregate in SQL (\`GROUP BY\`, \`SUM\`, \`date_trunc\`) and add \`LIMIT\`. Do not pull raw rows to aggregate them yourself.
+5. Before trusting recent or old numbers, run \`${cli} sources list\`. It shows when each source last synced, its last error, and when it syncs next. \`${cli} sources show <id>\` adds each table's row count and date range, the history still to fetch, and the last sync runs.
+
+## Funnel, campaign and money reports
+
+For "how is the funnel doing?", "which campaigns are working?" and "where does the money come from and go?", start with these three reports before writing SQL. All three cover the last 30 days ending today in the workspace reporting time zone unless \`--from\` and \`--to\` (YYYY-MM-DD, both days included) say otherwise, and at most 400 days.
+
+- \`${cli} funnel [--grain day|week|month]\` prints ad spend, leads, booked calls, calls held, sales and net revenue per day, week (starting Monday) or month, with cost per lead, per booked call and per sale and ROAS, then totals for the whole range.
+- \`${cli} campaigns [--channel <channel>] [--limit <n>]\` prints each campaign's spend, leads, booked calls, sales and revenue, best first (most first-touch revenue, then most spend), then totals over every matching campaign. Each lead and sale is credited to the person's first touch and last touch side by side. \`--limit\` is 1 to 200 (default 50); \`--channel\` is meta, google, affiliate, a utm_source, or unknown.
+- \`${cli} money [--grain day|week|month]\` prints money in (gross, refunds, net, orders), ad spend, affiliate payouts, what is left after ad costs and ROAS per period, then totals for the whole range, money in per payment source (stripe, ghl) and the biggest refund days. Refunds come off on the day they were made, not the day of the sale. \`left_after_ad_costs\` is net less ad spend and affiliate payouts; it is not profit. Its \`roas\` is net over ad spend alone, so it differs from \`${cli} funnel\`'s, which divides by all spend including affiliate payouts.
+- Money is never converted or added across currencies: there is one row per currency, and one total per currency. In \`${cli} funnel\`, leads and calls are counted for the whole period and repeat on every currency row, so never add them across its rows. In \`${cli} campaigns\`, each campaign's leads and calls sit on the row of the currency it spends in (or a blank-currency row when it has no spend), so they do add up across rows and totals. Ratios come from the summed numbers, not averages. An empty cell means the source is not connected, or a ratio would divide by 0.
+- To go deeper, query the views behind them: \`daily_funnel\`, \`campaign_results_daily\`, \`daily_spend\` and \`daily_sales\`. Their descriptions in \`${cli} warehouse schema\` say what each counts.
+
+## Webhook addresses
+
+A webhook address lets a tool such as a form or webinar platform push events into the warehouse's \`raw_events\` table. \`${cli} intake list\` shows each address with whether it is on, how many days it keeps events, the events of the last 24 hours, the last event's time, and the rows it holds. \`${cli} intake create <label>\` makes one and prints its link, address and token. The link is the one URL to paste into the sending tool: the address with the token on the end, or for Mailgun the bare address. Add \`--kind ghl_workflow\` for a GoHighLevel workflow's Webhook step: its events also land, typed, in \`ghl_events\`. Add \`--kind aloware\` for Aloware's call and text webhooks: they also land, typed, in \`aloware_calls\` and \`aloware_texts\`. Add \`--kind webinarfuel\` or \`--kind stealth_seminar\` for a webinar tool: its sign-ups, attendance, replays and offer clicks land in \`webinar_events\`. Add \`--kind mailgun --signing-key-stdin\`, with Mailgun's HTTP webhook signing key piped on stdin, for a Mailgun account's webhooks: each event's signature is checked and alone proves the sender, so Mailgun posts to the address itself with no token, and its events also land, typed, in \`mailgun_events\`. When the account's key changes, pipe the new one to \`${cli} intake signing-key <id> --signing-key-stdin\`; deleting the workspace's last Mailgun address deletes the key. The link and token are shown only then and after \`${cli} intake rotate <id>\`. Paste the link into the sending tool, or, when the tool can set a header, give it the address and \`Authorization: Bearer <token>\` instead, which keeps the token out of request logs. Never paste either anywhere else. Events are kept for 90 days unless \`--retention-days\` or \`${cli} intake retention <id> <days>\` says otherwise (1 to 3650). \`${cli} intake delete <id> --yes\` deletes the address and every event it saved. A website visit tag shows in \`${cli} intake list\` as an address of kind \`visit_tag\`, and each page view it records lands in \`site_visits\` (host, path, referrer host, UTM tags, click ids, country, device type, a bot flag and a random visitor id). \`${cli} intake create\` cannot make one: a tag has no token and needs its list of allowed sites, so an operator makes it with the server's \`npm run visit-tag:create\` script.
+
+## Limits
+
+- One statement per call, and it must return rows: \`SELECT\`, \`VALUES\`, or \`WITH ... SELECT\`. Anything else (\`INSERT\`, \`UPDATE\`, \`DELETE\`, DDL, \`SET\`, \`COPY\`) fails.
+- 15-second statement timeout.
+- Results stop at 1000 rows or about 5 MB. In JSON output, \`truncated\` is \`"row_limit"\` or \`"byte_limit"\` when a limit was hit, otherwise \`null\`.
+- In JSON output, \`columns\` lists each column's name and Postgres type. \`numeric\` and \`bigint\` values are JSON numbers with their exact digits, so parse them with a big-number-safe parser when precision matters. Dates are \`YYYY-MM-DD\` strings.
+- Every output column needs a unique name. Alias duplicates (\`a.id AS order_id\`).
+
+## Importing a CSV file
+
+\`${cli} import csv <file> --table <name>\` loads a spreadsheet export into the warehouse as the table \`import_<name>\`, next to the synced data; query it with \`${cli} warehouse query\` like any other table. The name uses lowercase letters, digits and underscores, starts with a letter, and is at most 41 characters. Importing again under the same name replaces the table in one step: a query running meanwhile sees the old table or the new one, never neither, and a failed import leaves the old table as it was. \`${cli} import remove --table <name> --yes\` drops the table and removes the import from the Sources page; a name with no import fails with \`not_found\`.
+
+- The file is UTF-8 CSV with a header row. Column names come from the headers, lowercased, with each run of other characters turned into \`_\`. Blank values are NULL.
+- Each column gets the first type every value fits: \`boolean\` (true, false, yes, no), \`bigint\`, \`numeric\`, \`date\` (2026-01-31 or 1/31/2026), \`timestamptz\` (ISO 8601), else \`text\`. Numbers may carry \`$\`, thousands commas and, for \`numeric\`, a trailing \`%\`, which are dropped. A number with a leading zero, like a ZIP code, stays text.
+- Limits: ${IMPORT_LIMITS.bytes / (1024 * 1024)} MB, ${IMPORT_LIMITS.rows.toLocaleString("en-US")} rows and ${IMPORT_LIMITS.columns} columns per file. A file over 4.5 MB, more than the hosted app takes in one request, goes to the workspace's private file storage first and is imported from there, then deleted; the command does this by itself.
+- The output lists the table, its row count, and each column with its type and original header. \`--format json\` prints \`{ sourceId, table, rows, columns: [{ name, type, sourceHeader }], importedAt }\`.
+
+## Making ads: tools and the creative ledger
+
+1. \`${cli} tools list\` shows each tool id (\`provider:tool\`, such as \`kie:nano-banana\`), whether it runs sync or async, and what it makes. \`--format json\` adds each tool's description, cost, and input JSON Schema.
+2. \`${cli} tools run kie:nano-banana --input '{"prompt": "...", "aspectRatio": "1:1"}' --idempotency-key <key>\` starts a run and waits for it (up to \`--wait\` seconds, default 300). Tools cost money. Always pass an idempotency key, and reuse it when you retry, so a retry returns the same run instead of paying twice.
+3. A run that is still going prints its id. Check it with \`${cli} tools get <run-id>\`. Image results list an \`asset\` link. Save the file with \`${cli} creatives download <asset-link>\`, or fetch the link with your API key as a bearer token; it redirects to a copy that works for 10 minutes.
+4. Record a succeeded run in the ledger with its lineage: \`${cli} creatives create --run <run-id> --lineage '{"persona": "...", "painPoint": "...", "desiredOutcome": "...", "angle": "...", "sourceAd": {"metaAdId": "..."}}'\`. Each output gets a SKU such as \`DLC-000123\`. The SKU goes in the Meta ad name.
+5. \`${cli} creatives list\` and \`${cli} creatives show <sku>\` read the ledger. \`${cli} creatives download <sku>\` saves a creative's image or video as \`<sku>.<ext>\` in the current folder; \`--out <path>\` names the file or a folder, and \`--open\` opens it. It also takes an asset path or link, such as a \`meta_ad_creatives\` \`image_path\`. \`--format json\` prints \`{ path, bytes, contentType }\`. Copy has no file; its text is in \`${cli} creatives show\`. For performance, query the \`creatives\` table or the \`creative_performance_daily\` view with \`${cli} warehouse query\`.
+
+## Landing pages
+
+The warehouse's content library keeps each landing page's words in order, read about once a day: one \`landing_page\` item per page in \`content_items\`, its versions in \`content_versions\` (\`fields->'blocks'\` holds the headings, paragraphs, lists, buttons, image descriptions and form field labels), and the list of pages with when each was last read in \`content_pages\`. Pages come from Meta ad links and GA4 landing pages. Add any other page with \`${cli} content add-page <url>\`: it is read at once, and the output shows its key, whether it could be read (\`ok\`, \`not_found\`, \`blocked\` by robots.txt, \`failed\`, \`not_html\`), and its version. A link that redirects, such as a link shortener, is recorded under the page it leads to.
+
+## Making content: a SKU and a record first
+
+Save anything you make before it goes anywhere: an ad written without a tool, an email, a text message, a landing page, a video or a social post. \`${cli} content create --kind email --name "Spring sale" --subject "..." --body @email.txt --note "first draft"\` gives it the workspace's next SKU (the same counter as creatives), status draft, and version 1, recorded as made by your API key, or by your agent run with \`--run <agent-run-id>\`. Kinds are \`ad\`, \`email\`, \`sms\`, \`landing_page\`, \`video\` and \`social_post\`. \`--body\` and \`--html\` take text or \`@file\`; \`--file <path>\` (repeatable) uploads an image, video or audio file of up to 50 MB (HTML stays at most 3 MB, and a file that does not fit beside it in one 3 MB request goes to storage first, on its own); \`--tool-run <id>\` (repeatable) links the tool runs it was made with; \`--fields\` takes JSON for structure such as a call to action.
+
+- What each kind needs: an ad, body or a file; an email, a subject and a body or HTML; a text message, a body of at most 1600 characters and only image files; a landing page, HTML or body; a video, a video file or a tool run; a social post, body or a file.
+- \`${cli} content edit <sku> --body @v2.txt --note "shorter"\` saves a new version with only what you change; the rest stays. An edit that changes nothing saves no version. A retired item cannot be edited.
+- \`${cli} content status <sku> approved\` moves it along the same steps as creatives. Launching needs where it went and that platform's id: \`${cli} content status <sku> launched --platform ghl --external-id <id>\`.
+- \`${cli} content show <sku>\` prints the current version. Every version is in the \`content_versions\` table for \`${cli} warehouse query\`.
+- \`${cli} content diff <sku | item-id>\` shows what changed from the version before the current one to the current one: each version's time, who made it and its note, then the subject, preview or headline before and after, the body's lines with \`-\` before each removed line and \`+\` before each added one, links and ad copy added or removed, and files added or removed. \`--from <n> --to <n>\` compares any two versions; \`--format json\` gives the same as data.
+- Propose a made item to a person with \`${cli} proposals create\` (kind \`creative\`, its SKU).
+
+### Publishing
+
+\`${cli} content publish <sku> --to <publisher> --target '<json>' --idempotency-key <key>\` publishes an approved item through one of ${brand.name}'s publishers, adding \`--plan <plan-id>\` when it is part of a launch plan and \`--run <run-id>\` from a helper's run. Only the approved version is published; an item edited after approval must be approved again. The server checks every rule first and refuses with each failure listed, recording nothing: one unfinished send per platform account, and at least 15 seconds between sends to one account. Otherwise it records exactly what it sends before sending it, then saves the platform's ids, marks the item launched, and moves the launch plan to live once all its items are out. For Meta without the \`--run\` of a helper in live mode, nothing is sent: the publication is saved as \`not_sent_practice\` with the full request. A send that may or may not have landed stays \`sending\` and is never retried; \`${cli} content reconcile <publication-id>\` asks the platform and finishes it. The same key returns the same publication. A page host is the publisher \`page_host:<host>\` with the target \`{"site":"...","path":"/..."}\`: it puts an approved landing page's HTML online, tags each link that leaves the page with the SKU, and is never held back by practice mode. \`${cli} content show <sku>\` lists the page's deployments with their ids. \`${cli} content unpublish <deployment-id>\` takes one live page down; the site's other pages stay up, and the deployment records when and by whom. It is refused while a synced Meta ad that is delivering links to the page, naming each ad, because a broken link in a running ad wastes money; \`--force\` takes it down anyway. Never roll a site back in Vercel's dashboard instead: the next deploy brings the rolled-away pages back.
+
+The \`meta_ads\` publisher puts an approved ad on Facebook, always paused, in an ad set that already exists: \`--to meta_ads --target '{"accountId": "act_<id>", "adsetId": "<id>"}'\`. The ad needs pictures or a video (not both), body text and an https link in \`fields.link_urls\` (\`fields.cta\`, such as "Shop now", sets the button; \`fields.bodies\`, \`fields.titles\` and \`fields.descriptions\` add variations). The account, the ad set's campaign and the ad set must all be on the helper's publish list, which only an operator sets, and the ad set and campaign must be in the last Meta sync and not archived. A live send also needs a run of the Facebook ads helper, Meta numbers pulled under 12 hours ago, and room under the daily limit of new ads. The ad is named \`<SKU> | <name>\` and its creative's \`url_tags\` carry the SKU. In practice mode the same command stores the full request for review and sends nothing. Each publication's \`targetSnapshot\` names the campaign and ad set as they were at publish time.
+
+When you send something yourself instead, record it in ${brand.name} before anything is sent, so the record never depends on the platform remembering it:
+
+1. \`${cli} content publish-record <sku> --file publication.json\` saves exactly what you are about to send. The file holds \`platform\` (\`meta\`, \`ghl\`, \`klaviyo\`, \`roezan\`, \`youtube\`, \`instagram\` or \`web\`), \`objectType\` as the syncs name it (\`ad\` or \`creative\` on Meta; \`email_step\`, \`email_blast\`, \`workflow\` or \`campaign\` on GoHighLevel; \`campaign\`, \`campaign_message\`, \`flow\` or \`flow_message\` on Klaviyo; \`broadcast\` on Roezan; \`video\` on YouTube; \`media\` on Instagram), \`request\` (the body you will send), an \`idempotencyKey\` of your own, and optionally \`accountId\`, \`version\` and \`runId\`. Secrets are removed before it is stored. Recording the same key again returns the same publication.
+2. \`${cli} content publish-finish <publication-id> --status sending\` immediately before the platform call.
+3. Right after, \`${cli} content publish-finish <publication-id> --status published --input '{"externalId": "<platform id>"}'\`, adding \`links\` for other ids (such as \`[{"objectType": "creative", "externalId": "..."}]\`) and \`response\`; or \`--status failed --input '{"error": "..."}'\`. Published ids join the item to its results.
+
+A publication still \`sending\` after 15 minutes reads \`unknown\`: the send may or may not have happened. Never send it again; check the platform, then finish it as \`published\` or \`failed\`. Unless the publication was recorded with the \`runId\` of a helper in live mode, ${brand.name} refuses \`sending\`, \`published\` and \`failed\` for Meta: finish the record as \`not_sent_practice\` instead. \`${cli} content show <sku>\` lists each publication, and the \`content_publications\` table holds them all.
+
+When a sync later brings back something made here, found by a published id, an id already linked, or the SKU in its name, it is recorded on the made item, not as a new discovered one. A copy edited on the platform becomes a new version captured by the sync.
+
+### Tracking links: the SKU on every link
+
+Every link you publish, in an ad, email, text message or page, carries its item's SKU, so leads and sales come back to the exact item. Never write the tags by hand. \`${cli} content track-link <sku> <url> --channel email --campaign <id>\` prints the link tagged with \`utm_source\` and \`utm_medium\` for the channel (\`facebook\` and \`paid\`, \`email\` and \`email\`, \`sms\` and \`sms\`, or \`web\` and \`referral\`, the default), \`utm_campaign\` when you pass \`--campaign\`, and \`utm_content=<SKU>\`. Tags the link already has are replaced; the rest of the link is kept as it was. It takes only https links, and only the SKU of an item that exists in this workspace (made with \`${cli} content create\` or recorded with \`${cli} creatives create\`).
+
+A Meta ad's name starts with its SKU: \`<SKU> | <readable name>\`, at most 400 characters. Its creative's \`url_tags\` is exactly \`utm_source=facebook&utm_medium=paid&utm_campaign={{campaign.id}}&utm_term={{adset.id}}&utm_content=<SKU>&ad_id={{ad.id}}&campaign_id={{campaign.id}}\`; Meta fills in the \`{{...}}\` parts. Code in ${brand.name} itself uses \`tagUrl\`, \`metaUrlTags\` and \`adName\` from \`src/lib/content/tracking.ts\`.
+
+The \`touches\` view reads the SKU back into its \`sku\` column, and \`item_results_daily\` counts leads, booked calls and sales per SKU per day, by first and last touch.
+
+## Launch plans
+
+A launch plan writes down one campaign push before you make things for it, and keeps those things together: what the push is for, where it runs, the landing page its ads send people to, and the saved items that belong to it. Nothing in a plan is sent anywhere.
+
+1. \`${cli} plans create --name "P1 cold, guarantee page" --goal "Five new static ads" --channel meta --target '{"account_id": "act_1", "campaign_id": "<id>", "adset_id": "<id>"}' --landing-url https://example.com/guarantee\` makes a draft plan and prints its id. Channels are \`meta\`, \`ghl\`, \`klaviyo\` and \`web\`. A meta plan's target uses ids from \`meta_campaigns\` and \`meta_adsets\`, never names: \`adset_id\` adds the ads to that ad set, \`template_adset_id\` instead copies that ad set for the push. The campaign and ad set must be synced and belong together, and with \`--run <agent-run-id>\` they must be among the campaigns your agent may touch. \`--landing <sku>\` names a landing page made here instead of an address.
+2. \`${cli} content create --kind ad ... --plan <plan-id>\` saves a new item straight into the plan. \`${cli} plans add <plan-id> <sku>\` adds one already saved; an item may sit in several plans. The role defaults from the item's kind (\`ad\`, \`email\`, \`sms\`, \`landing_page\`, \`video\`, or \`post\` for a social post); \`--role copy\` or \`--role image\` says otherwise, and \`--position <n>\` sets its place. \`${cli} plans remove <plan-id> <sku>\` takes it out.
+3. \`${cli} plans status <plan-id> ready\` moves the plan one step along \`draft\`, \`ready\`, \`publishing\`, \`live\`, \`done\`. \`cancelled\` ends a plan that is not done. A done or cancelled plan cannot be edited.
+4. \`${cli} plans show <plan-id>\` prints the plan and its items in order. Every plan is in the \`content_launch_plans\` and \`content_launch_plan_items\` tables for \`${cli} warehouse query\`.
+
+## The campaign trail
+
+\`${cli} trail <plan-id>\` follows a plan's items from how they were made to where they ran and how they did; \`${cli} trail <sku>\` does it for one item. For each item it shows the paid tool runs it was made from (the tool, the prompt and the cost; \`--format json\` has every prompt) and every place it was published: one line per placement, so an ad in three ad sets has three lines. Each Meta line names the campaign, ad set and ad by their name now, with the name they had when published in brackets when it changed, and the ad's spend and purchases. Leads and sales are per item, credited to its SKU. Everything joins by Meta id, so a renamed campaign or an ad whose name lost its SKU still shows. For SQL, the same lines are in the \`content_trail\` and \`content_trail_results\` views.
+
+## The Facebook ads agent
+
+The daily Facebook ads agent follows its own playbook: install it with \`${cli} skill install meta-ads\` (or \`--codex\` for an AGENTS.md in the current directory) and read it with \`${cli} docs meta-ads\`. It works in runs (\`${cli} agent start\`, \`${cli} agent finish\`), keeps four memory notes (\`${cli} memory\`), a brand profile (\`${cli} brand\`), and makes proposals (\`${cli} proposals\`) that a person approves in the web app. Nothing it does is sent to Meta.
+
+## The P3 refresh helper
+
+The weekly P3 refresh helper is a second agent. Pass \`--agent p3_refresh\` to the agent and memory commands to use it instead of the default \`--agent meta_ads\`. \`${cli} agent draft --agent p3_refresh\` prints the counted draft its run starts from: the P3 purchase campaign's ad sets ranked over 7, 14 and 30 completed days, the audience template, and every P1 winner marked new, already in P3, or unresolved. Its run then proposes one \`p3_refresh_batch\` with \`${cli} proposals create\`: the ad set to retire, the template ad set, and the roster of ads, for a person to approve. Its playbook installs with \`${cli} skill install p3-refresh\` (or \`--codex\` for a Codex skill under \`$CODEX_HOME/skills\`) and prints with \`${cli} docs p3-refresh\`.
+
+## Workers
+
+A worker is a skill from the library that runs for this workspace on a schedule. \`${cli} worker list\` shows each one: its skill, the version in use (and one on trial), schedule and time zone, mode, runner, whether it is on, its next run, and how its last run went. \`${cli} worker runs <worker-id | skill> [--limit <n>]\` shows its last runs, newest first: status (a skipped run says why), when it was queued and finished, how long it took, its cost as AI, tools and compute, its error, and the first line of its report. \`${cli} worker run-now <worker-id | skill>\` queues one run now, even for a worker that is off. It is refused (\`open_run\`) while the worker has a run queued or going, and (\`monthly_cap\`) when the run could take the workspace over its monthly limit for workers. A worker run's own key cannot start runs. Only the operator changes a worker's schedule, mode or limits.
+
+A worker's run acts as its skill's agent, the way the Facebook ads agent works in runs. Inside a run the agent and memory commands use \`--agent skill\` unless told otherwise, and only a worker run's own key can. A published skill should run \`${cli} agent start\` first, which opens the run's log and prints its run id and notes, and \`${cli} agent finish <run-id> --status succeeded|failed --file <report.md>\` last, with a report whose first line says what the run did. Each run of the worker gets a run of its own; the four notes (\`${cli} memory\`) carry over from one run to the next. A skill's agent proposes draft ads (\`creative\`) with \`${cli} proposals create\` and the run id, under the same daily limit as a new Facebook ads agent, and nothing else.
+
+## Output
+
+- \`--format table\` (the default) prints an aligned text table.
+- \`--format json\` prints the raw API response. Use it when you need to parse the result.
+- Errors go to stderr. A SQL error prints the Postgres error code, for example \`sql_42P01: relation "x" does not exist\`. A wrong table or column name adds a \`Hint:\` line with the nearest real names.
+
+## Exit codes
+
+- 0: success.
+- 1: request or SQL error, or a tool run that failed.
+- 2: usage error (unknown command or missing argument).
+- 3: not logged in, or the API key was rejected.
+
+## Commands
+
+\`\`\`
+${cli} login                        validate a key (prompted, piped, or ${envPrefix}_API_KEY) and save it
+${cli} logout                       delete saved credentials
+${cli} whoami                       show the current workspace
+${cli} guide                        what this workspace's data holds, how fresh it is, and what is missing: read it first
+${cli} warehouse schema [--summary] [--table <name> ...] [--search <words>]   list tables and columns; --summary for one row per table
+${cli} warehouse query "<sql>"      run one read-only query (or --file <path>, or stdin)
+${cli} funnel [--from <date>] [--to <date>] [--grain day|week|month]   spend, leads, calls and sales per period, with totals
+${cli} money [--from <date>] [--to <date>] [--grain day|week|month]   money in, refunds, ad spend, payouts and what is left, per period, with totals
+${cli} campaigns [--from <date>] [--to <date>] [--channel <channel>] [--limit <n>]   each campaign's results, best first, with totals
+${cli} sources list                 list data sources and their health
+${cli} sources show <id>            show one source's health, tables and last sync runs
+${cli} sources settings <id> [<key>=<value> ...]   show a key source's settings, or check them with its saved key and save them
+${cli} intake list                  list webhook addresses and their health
+${cli} intake create <label> [--kind generic|ghl_workflow|aloware|webinarfuel|stealth_seminar|mailgun] [--retention-days <n>] [--signing-key-stdin]   make a webhook address; prints its link and token once
+${cli} intake rotate <id>           replace an address's token; prints the new link and token once
+${cli} intake signing-key <id> --signing-key-stdin   replace the workspace's signing key for that address's kind (mailgun)
+${cli} intake disable <id> | enable <id>   turn an address off or back on
+${cli} intake rename <id> <label> | retention <id> <days>
+${cli} intake delete <id> --yes     delete an address and every event it saved
+${cli} import csv <file> --table <name>   load a CSV file as the table import_<name>, replacing an earlier import
+${cli} import remove --table <name> --yes   drop the table import_<name> and its import
+${cli} tools list                   list generation and research tools
+${cli} tools run <tool> --input '<json>' [--idempotency-key <key>] [--wait <seconds>]
+${cli} tools get <run-id>           show a tool run, waiting for it to finish (--wait)
+${cli} creatives list               list creatives (--status, --kind, --limit)
+${cli} creatives show <sku>         show one creative with its spec and lineage
+${cli} creatives download <sku | asset-path | asset-link> [--out <path>] [--open]   save a creative's image or video
+${cli} creatives create --run <run-id> [--lineage '<json>' | @file.json]   record a run's output with a new SKU
+${cli} content create --kind <kind> [--body ...] [--file <path>] [--note <why>] [--plan <plan-id>]   save made content with a new SKU
+${cli} content search [--text <words>] [--mode word|meaning] [--kind <kind>] [--platform <p>] [--origin <o>] [--from <date>] [--to <date>] [--sort <column>] [--order asc|desc] [--limit <n>]   find content with its numbers
+${cli} content pull <dir> [--kind <kind>] [--platform <p>] [--origin <o>] [--media] [--full]   copy the library to a folder of Markdown files; rerun for changes
+${cli} content show <sku | item-id> | content edit <sku> [...] --note <why> | content status <sku> <status>
+${cli} content diff <sku | item-id> [--from <n>] [--to <n>]   what changed between two versions
+${cli} content publish <sku> --to <publisher> --target '<json>' --idempotency-key <key> [--plan <id>] [--version <n>] [--run <run-id>]   publish an approved item
+${cli} content reconcile <publication-id>   check whether a publish left sending landed
+${cli} content unpublish <deployment-id> [--force]   take one deployed landing page down
+${cli} content publish-record <sku> --file <publication.json>   record a publish before sending it
+${cli} content publish-finish <publication-id> --status sending|published|failed|not_sent_practice [--input '<json>']
+${cli} content track-link <sku> <url> [--channel facebook|email|sms|web] [--campaign <id>]   tag a link with its SKU
+${cli} agent start | show <run-id> | runs | finish <run-id> --status <s> --file <report>   [--agent meta_ads|p3_refresh]
+${cli} agent draft --agent p3_refresh   the P3 refresh helper's counted draft
+${cli} memory get [<note>] | memory set <note> --file <path>   [--agent meta_ads|p3_refresh]
+${cli} brand get | brand set --file <path> [--sources '<json>' | @file.json]
+${cli} proposals create --input '<json>' | proposals list [--status <s>] [--run <run-id>]
+${cli} content add-page <url>      add a landing page and read it now
+${cli} plans create --name <name> --goal <text> --channel meta|ghl|klaviyo|web [--target '<json>'] [--landing <sku> | --landing-url <url>] [--run <agent-run-id>]   plan a campaign push
+${cli} plans show <plan-id> | plans add <plan-id> <sku> [--role <role>] [--position <n>] | plans remove <plan-id> <sku>
+${cli} plans status <plan-id> draft|ready|publishing|live|done|cancelled
+${cli} trail <plan-id | sku | item-id>   how a plan's items were made, where they ran, and their results
+${cli} worker list | worker runs <worker-id | skill> [--limit <n>] | worker run-now <worker-id | skill>   this workspace's workers, their runs and costs, and Run now
+${cli} skill install [meta-ads|p3-refresh] [--project] [--codex]   install a Claude Code skill (or the playbook for Codex)
+${cli} docs [meta-ads|p3-refresh]   print this guide, or a helper's playbook
+\`\`\`
+
+Global options: \`--format table|json\`, \`--api-url <url>\` (or \`${envPrefix}_API_URL\`).
+`;
+export const skill = `---
+name: ${cli}
+description: Query a client's marketing data warehouse (ad spend, orders, synced sources) with read-only SQL, generate ad images and copy through paid tools, and read the creative ledger, through the \`${cli}\` CLI. Use when the user asks about marketing performance, ad spend, ROAS, orders, making ad creatives, or anything stored in their ${brand.name} warehouse.
+---
+
+${guide}`;