@oxygen-agent/cli 1.1014.985 → 1.1014.1087

package/dist/command-families/tables/imports.js

@@ -0,0 +1,200 @@
+import { readRecordString } from "../../cli-values.js";
+import { readRecord } from "../../command-support.js";
+import { requestOxygen } from "../../http-client.js";
+import { shouldStreamFileImport, STREAMED_FILE_IMPORT_MIN_BYTES, scanStreamedImportFile, rowsForStreamedImportTarget, putImportFileStream } from "../../streamed-file-import.js";
+import { readOption } from "../../util.js";
+import { chunk } from "@oxygen/shared/array-utils";
+import { OxygenError } from "@oxygen/shared/cli-result";
+import { normalizeRowsFormat, inferRowsFileFormat, assertImportFormatWithinBufferedLimit, dropBlankImportCells } from "@oxygen/shared/file-import";
+import { statSync, readFileSync } from "node:fs";
+import { basename } from "node:path";
+import { emitQueueWaitStderrNote, enqueueImportFile, formatMebibytes, putImportFile, tryEnqueueStagedFileImport } from "./import-upload.js";
+import { LARGE_IMPORT_BACKGROUND_ROW_THRESHOLD, SAFE_IMPORT_WRITE_BATCH_SIZE, hashImportFile, normalizeImportBatchSize, withImportWaitNextStep } from "./import-values.js";
+import { readRowsFile } from "./bundle-format.js";
+import { prepareImportTarget } from "./import-columns.js";
+import { writeImportBatchWithAutoSplit } from "./import-batches.js";
+/**
+ * `--url` hands the fetch to the server: the same durable import the file path
+ * enqueues, with the bytes read by OXYGEN behind SSRF, size and content guards,
+ * so the CLI never downloads anything and a 0-credit preview is one flag away.
+ */
+export async function importRowsFromUrl(table, options) {
+    if (options.create && table) {
+        throw new OxygenError("invalid_import_target", "Pass either a table argument or --create, not both.", { exitCode: 1 });
+    }
+    if (!options.preview && !options.create && !table) {
+        throw new OxygenError("invalid_import_target", "Pass a table argument or --create <name>, or add --preview to look first.", { exitCode: 1 });
+    }
+    const result = await requestOxygen("/api/cli/tables/import-from-url", {
+        method: "POST",
+        timeoutMs: 120_000,
+        body: {
+            url: options.url,
+            mode: options.preview ? "preview" : "import",
+            ...(table ? { table } : {}),
+            ...(options.create ? { create_name: options.create } : {}),
+            ...(readOption(options.project) ? { project: readOption(options.project) } : {}),
+            ...(readOption(options.upsertKey) ? { upsert_key: readOption(options.upsertKey) } : {}),
+            ...(readOption(options.format) ? { format: readOption(options.format) } : {}),
+            ...(readOption(options.sheet) ? { sheet: readOption(options.sheet) } : {}),
+        },
+    });
+    if (options.preview)
+        return result;
+    emitQueueWaitStderrNote(readRecord(result, "queue_wait"));
+    return withImportWaitNextStep({ ...result, background: true, autoBackground: true });
+}
+export async function importRows(table, options) {
+    if (options.url && options.skipBlankCells) {
+        throw new OxygenError("invalid_request", "--skip-blank-cells works on --file imports. Download the link and import the file.", { exitCode: 1 });
+    }
+    if (options.url)
+        return importRowsFromUrl(table, { ...options, url: options.url });
+    if (!options.file) {
+        throw new OxygenError("invalid_request", "Pass --file <path> or --url <https-link>.", { exitCode: 1 });
+    }
+    if (options.preview) {
+        throw new OxygenError("invalid_request", "--preview only applies to --url imports.", { exitCode: 1 });
+    }
+    return importRowsFromFile(table, { ...options, file: options.file });
+}
+export async function importRowsFromFile(table, options) {
+    const format = normalizeRowsFormat(options.format, inferRowsFileFormat(options.file));
+    // Refuse a JSON or XLSX file too large to hold in memory before reading it,
+    // and send a large CSV or JSONL file down the streamed path, which never does.
+    const fileBytes = statSync(options.file).size;
+    assertImportFormatWithinBufferedLimit(format, fileBytes);
+    if (shouldStreamFileImport(format, fileBytes)) {
+        return withImportWaitNextStep(await importLargeFileStreamed(table, options, format, fileBytes));
+    }
+    const parsedRows = await readRowsFile(options.file, format, options.sheet);
+    if (parsedRows.length === 0) {
+        throw new OxygenError("invalid_rows", "Import file did not contain any rows.", {
+            exitCode: 1,
+        });
+    }
+    const batchSize = normalizeImportBatchSize(options.batchSize);
+    const effectiveBatchSize = Math.min(batchSize, SAFE_IMPORT_WRITE_BATCH_SIZE);
+    const sourceHash = hashImportFile(options.file);
+    const shouldUseBackground = options.background
+        || (!options.sync && parsedRows.length > LARGE_IMPORT_BACKGROUND_ROW_THRESHOLD);
+    const preparedBackgroundTarget = shouldUseBackground && table && !options.create
+        ? await prepareImportTarget(table, options, parsedRows)
+        : null;
+    if (shouldUseBackground) {
+        // Prefer the object-storage fast path: upload the raw file once via a
+        // presigned URL (no request-body limit) so the worker COPY-loads it.
+        // Falls back to the inline multipart import when storage is unconfigured.
+        const fileBuffer = readFileSync(options.file);
+        const staged = await tryEnqueueStagedFileImport(table, options, format, {
+            byteLength: fileBuffer.byteLength,
+            read: () => Promise.resolve({ targetRows: parsedRows, rowCount: parsedRows.length, sha256: sourceHash }),
+            put: (uploadUrl, contentType) => putImportFile(uploadUrl, fileBuffer, contentType),
+        }, {
+            autoBackground: !options.background,
+            batchSize,
+        }, preparedBackgroundTarget);
+        if (staged)
+            return withImportWaitNextStep(staged);
+        return withImportWaitNextStep(await enqueueImportFile(table, options, format, batchSize, {
+            autoBackground: !options.background,
+            sourceHash,
+        }, preparedBackgroundTarget));
+    }
+    const prepared = await prepareImportTarget(table, options, parsedRows);
+    // The foreground writes rows itself: a row without a key leaves that value alone.
+    const target = options.skipBlankCells
+        ? { ...prepared, rows: prepared.rows.map((row) => dropBlankImportCells(row, prepared.upsertKey)) }
+        : prepared;
+    let rowCount = 0;
+    let insertedCount = 0;
+    let updatedCount = 0;
+    let warningCount = 0;
+    const warnings = [];
+    let warningsTruncated = false;
+    let lastResult = null;
+    let writeRequestCount = 0;
+    let requestTooLargeRetries = 0;
+    let byteSplits = 0;
+    let minimumBatchSizeUsed = null;
+    for (const [batchIndex, batch] of chunk(target.rows, effectiveBatchSize).entries()) {
+        const result = await writeImportBatchWithAutoSplit({
+            tableRef: target.tableRef,
+            upsertKey: target.upsertKey,
+            rows: batch,
+            ...(!target.upsertKey
+                ? { requestId: `tables-import:${sourceHash}:${batchIndex}` }
+                : {}),
+        });
+        rowCount += result.rowCount;
+        insertedCount += result.insertedCount;
+        updatedCount += result.updatedCount;
+        warningCount += result.warningCount;
+        for (const warning of result.warnings) {
+            if (warnings.length < 20)
+                warnings.push(warning);
+        }
+        warningsTruncated = warningsTruncated || result.warningsTruncated || warningCount > warnings.length;
+        writeRequestCount += result.writeRequestCount;
+        requestTooLargeRetries += result.requestTooLargeRetries;
+        byteSplits += result.byteSplits;
+        minimumBatchSizeUsed = minimumBatchSizeUsed === null
+            ? result.minimumBatchSizeUsed
+            : Math.min(minimumBatchSizeUsed, result.minimumBatchSizeUsed);
+        lastResult = result.lastResult;
+    }
+    return {
+        table: lastResult?.table ?? null,
+        ...(target.createdTable ? { createdTable: target.createdTable } : {}),
+        rowCount,
+        insertedCount,
+        updatedCount,
+        ...(warningCount > 0 ? {
+            warnings,
+            warningCount,
+            ...(warningsTruncated ? { warningsTruncated: true } : {}),
+        } : {}),
+        batchCount: writeRequestCount,
+        batchSize: effectiveBatchSize,
+        ...(effectiveBatchSize !== batchSize ? { requestedBatchSize: batchSize } : {}),
+        // Two separate counters: a byte pre-split cost nothing, a server 413 cost a
+        // wasted upload — reporting them as one number would hide which happened.
+        ...(requestTooLargeRetries > 0 ? { requestTooLargeRetries } : {}),
+        ...(byteSplits > 0 ? { byteSplits } : {}),
+        ...(requestTooLargeRetries > 0 || byteSplits > 0 ? { minimumBatchSizeUsed } : {}),
+        ...(target.tableWebUrl ? { table_web_url: target.tableWebUrl } : {}),
+        ...(readRecordString(lastResult, "web_url") ? { web_url: readRecordString(lastResult, "web_url") } : {}),
+    };
+}
+/**
+ * A CSV or JSONL file over STREAMED_FILE_IMPORT_MIN_BYTES: never read whole.
+ * One streaming pass counts, hashes and collects its columns, the upload streams
+ * from disk, and the import always runs in the background. There is no inline
+ * fallback: a file this large cannot travel in one API request.
+ */
+export async function importLargeFileStreamed(table, options, format, fileBytes) {
+    if (options.sync) {
+        process.stderr.write(`note: files over ${Math.round(STREAMED_FILE_IMPORT_MIN_BYTES / (1024 * 1024))} MiB always import in the background; --sync is ignored\n`);
+    }
+    const staged = await tryEnqueueStagedFileImport(table, options, format, {
+        byteLength: fileBytes,
+        read: async () => {
+            process.stderr.write(`note: reading ${basename(options.file)} (${formatMebibytes(fileBytes)}) to count its rows before uploading\n`);
+            const scan = await scanStreamedImportFile(options.file, format);
+            if (scan.rowCount === 0) {
+                throw new OxygenError("invalid_rows", "Import file did not contain any rows.", { exitCode: 1 });
+            }
+            return { targetRows: rowsForStreamedImportTarget(scan), rowCount: scan.rowCount, sha256: scan.sha256 };
+        },
+        put: (uploadUrl, contentType) => putImportFileStream({ uploadUrl, path: options.file, byteLength: fileBytes, contentType }),
+    }, {
+        autoBackground: !options.background,
+        batchSize: normalizeImportBatchSize(options.batchSize),
+    });
+    if (staged)
+        return { ...staged, streamed_upload: true };
+    throw new OxygenError("object_storage_not_configured", `Files over ${Math.round(STREAMED_FILE_IMPORT_MIN_BYTES / (1024 * 1024))} MiB upload straight to file storage, which this OXYGEN server has not configured.`, {
+        details: { file_bytes: fileBytes, streamed_import_min_bytes: STREAMED_FILE_IMPORT_MIN_BYTES },
+        exitCode: 1,
+    });
+}

package/dist/command-families/tables/options.d.ts

@@ -0,0 +1,314 @@
+import { JsonOptions } from "../../cli-output.js";
+export type TablesViewOptions = JsonOptions & {
+    name?: string;
+    viewType?: string;
+    config?: string;
+    groupBy?: string;
+    default?: boolean;
+    position?: string;
+};
+export type TablesHubSpotImportOptions = JsonOptions & {
+    list?: string;
+    object?: string;
+    destination?: string;
+    connection?: string;
+    sample?: boolean;
+    dncList?: string;
+    companyDncList?: string;
+    name?: string;
+    project?: string;
+    contactLinkedinProperty?: string;
+    contactCompanyDomainProperty?: string;
+    contactCompanyLinkedinProperty?: string;
+    companyDomainProperty?: string;
+    companyLinkedinProperty?: string;
+    contactProperties?: string;
+    maxRecordsPerList?: string;
+    maxCredits?: string;
+    once?: boolean;
+    cron?: string;
+    timezone?: string;
+    reviewedFingerprint?: string;
+    idempotencyKey?: string;
+    live?: boolean;
+    approved?: boolean;
+};
+export type TablesPipedriveImportOptions = JsonOptions & {
+    filter?: string;
+    dncFilter?: string;
+    orgDncFilter?: string;
+    name?: string;
+    project?: string;
+    personLinkedinField?: string;
+    personTitleField?: string;
+    orgDomainField?: string;
+    orgLinkedinField?: string;
+    personFields?: string;
+    maxRecordsPerFilter?: string;
+    maxCredits?: string;
+    once?: boolean;
+    cron?: string;
+    timezone?: string;
+    reviewedFingerprint?: string;
+    idempotencyKey?: string;
+    live?: boolean;
+    approved?: boolean;
+};
+export type TablesWatcherOptions = JsonOptions & {
+    table?: string;
+    name?: string;
+    project?: string;
+    profilesJson?: string;
+    maxCredits?: string;
+    requestId?: string;
+    previewHash?: string;
+    approved?: boolean;
+    credentialMode?: string;
+};
+export type TablesFollowersOptions = JsonOptions & {
+    tableId?: string;
+    company?: string;
+    records?: string;
+    package?: string;
+    name?: string;
+    project?: string;
+    maxCredits?: string;
+    requestId?: string;
+    credentialMode?: string;
+};
+export type TablesCreateOptions = JsonOptions & {
+    columnsJson: string;
+    project?: string;
+};
+export type TablesListOptions = JsonOptions & {
+    project?: string;
+    tag?: string;
+    includeArchived?: boolean;
+    /** `--limit`: cap the listed window (default 200, max 1000). */
+    limit?: string;
+    /** `--all`: list every table instead of the newest window. */
+    all?: boolean;
+    cursor?: string;
+    query?: string;
+    projection?: "full" | "summary";
+    maxChars?: string;
+};
+export type TablesDuplicateOptions = JsonOptions & {
+    name?: string;
+    schemaOnly?: boolean;
+};
+export type TablesQueryOptions = JsonOptions & Record<string, unknown> & {
+    limit?: string;
+    cursor?: string;
+    offset?: string;
+    fields?: string;
+    filterJson?: string;
+    filterTreeJson?: string;
+    search?: string;
+    formulaValues?: string;
+    sortJson?: string;
+    systemFields?: boolean;
+    output?: string;
+};
+export type TablesPreviewOptions = JsonOptions & {
+    limit?: string;
+    fields?: string;
+    includeSystemFields?: boolean;
+    includeCellStates?: boolean;
+    summaryOnly?: boolean;
+};
+export type TablesInsertOptions = JsonOptions & {
+    rowsJson: string;
+    requestId?: string;
+};
+export type TablesUpdateOptions = JsonOptions & {
+    valuesJson: string;
+};
+export type TablesDeleteRowsOptions = JsonOptions & {
+    metadataJson?: string;
+    format?: string;
+    rowIdsJson?: string;
+    rowIdsFile?: string;
+    rowIdColumn?: string;
+    sheet?: string;
+};
+export type TablesDescribeOptions = JsonOptions & {
+    includeArchived?: boolean;
+    stats?: boolean;
+    column?: string;
+};
+export type TablesActivityOptions = JsonOptions & {
+    limit?: string;
+};
+export type TablesTidySuggestOptions = JsonOptions & {
+    limit?: string;
+    categories?: string;
+};
+export type TablesRenameOptions = JsonOptions & {
+    name: string;
+};
+export type TablesMoveOptions = JsonOptions & {
+    project: string;
+};
+export type TablesUpsertOptions = JsonOptions & {
+    key: string;
+    rowsJson: string;
+    "return"?: string;
+    dryRun?: boolean;
+};
+export type TablesSourcesOptions = JsonOptions & {
+    group?: string;
+};
+export type TablesImportOptions = JsonOptions & {
+    file?: string;
+    url?: string;
+    preview?: boolean;
+    format?: string;
+    upsertKey?: string;
+    skipBlankCells?: boolean;
+    batchSize?: string;
+    background?: boolean;
+    sync?: boolean;
+    maxConcurrency?: string;
+    create?: string;
+    project?: string;
+    sheet?: string;
+};
+export type TablesExportOptions = JsonOptions & {
+    format?: string;
+    output?: string;
+    limit?: string;
+};
+export type TablesExportBundleOptions = JsonOptions & {
+    output?: string;
+    pageSize?: string;
+};
+export type TablesImportBundleOptions = JsonOptions & {
+    file: string;
+    name?: string;
+    project?: string;
+    into?: string;
+    key?: string;
+    batchSize?: string;
+};
+export type TablesRelateOptions = JsonOptions & {
+    to?: string;
+    targetTable?: string;
+    displayName?: string;
+    cardinality?: string;
+    inverseSlug?: string;
+    inverseDisplayName?: string;
+    live?: boolean;
+    dryRun?: boolean;
+};
+export type TablesRelationUpdateOptions = JsonOptions & {
+    displayName?: string;
+    inverseDisplayName?: string;
+    cardinality?: string;
+    approved?: boolean;
+    dryRun?: boolean;
+};
+export type TablesRelationArchiveOptions = JsonOptions & {
+    approved?: boolean;
+    dryRun?: boolean;
+};
+export type TablesUnlinkOptions = JsonOptions & {
+    relation: string;
+    targetRowId: string;
+    approved?: boolean;
+    live?: boolean;
+    dryRun?: boolean;
+};
+export type TablesLinkOptions = JsonOptions & {
+    to?: string;
+    on?: string;
+    approved?: boolean;
+    createMissing?: boolean;
+    maxConcurrency?: string;
+    undo?: string;
+    relation?: string;
+    targetRowId?: string;
+    live?: boolean;
+    dryRun?: boolean;
+};
+export type TablesWebhookCreateOptions = JsonOptions & {
+    name?: string;
+    source?: string;
+    account?: string;
+    events?: string;
+    mapping?: string;
+    mode?: string;
+    status?: string;
+    authMode?: string;
+    upsertKey?: string;
+    itemsPath?: string;
+    eventIdPath?: string;
+    eventTypePath?: string;
+    occurredAtPath?: string;
+    autoRunColumns?: string;
+    autoRunMaxCredits?: string;
+    autoRunMaxConcurrency?: string;
+    autoRunForce?: boolean;
+    autoRunConnectionId?: string;
+    autoRunApproved?: boolean;
+    clearAutoRun?: boolean;
+    table?: string;
+    limit?: string;
+    autoRunStatus?: string;
+};
+export type TablesAutoRunSetOptions = JsonOptions & {
+    columns?: string;
+    sources?: string;
+    force?: boolean;
+    maxCredits?: string;
+    maxConcurrency?: string;
+};
+export type TablesAutoDedupeSetOptions = JsonOptions & {
+    on: string;
+    normalize?: string;
+    keep?: string;
+    mergeValues?: string;
+};
+export type TablesScheduleSetOptions = JsonOptions & {
+    cron?: string;
+    every?: string;
+    maxCredits?: string;
+    approved?: boolean;
+    force?: boolean;
+};
+export type TablesPromoteOptions = JsonOptions & {
+    object?: string;
+    map: string;
+    policy?: string;
+    rowId?: string[];
+    dryRun?: boolean;
+    approved?: boolean;
+    maxConcurrency?: string;
+};
+export type TablesDedupeOptions = JsonOptions & {
+    on: string;
+    normalize?: string;
+    keep?: string;
+    mergeValues?: string;
+    scanLimit?: string;
+    apply?: boolean;
+    approved?: boolean;
+    against?: string;
+    againstColumn?: string;
+};
+export type TablesSendOptions = JsonOptions & {
+    map?: string[];
+    mapping?: string;
+    automap?: boolean;
+    flatten?: string;
+    flattenPath?: string;
+    filter?: string;
+    mode?: string;
+    upsertKey?: string;
+    pageSize?: string;
+    dryRun?: boolean;
+};
+/** Import options once `--file` is known to be present. */
+export type TablesFileImportOptions = TablesImportOptions & {
+    file: string;
+};

package/dist/command-families/tables/options.js

@@ -0,0 +1 @@
+export {};

package/dist/command-families/tables/register-automation.d.ts

@@ -0,0 +1,2 @@
+import type { TablesRegistrationContext } from "./registration-context.js";
+export declare function registerAutomation({ tablesCommand, handleAsyncAction }: TablesRegistrationContext): void;

package/dist/command-families/tables/register-automation.js

@@ -0,0 +1,127 @@
+import { readPositiveInt } from "../../cli-values.js";
+import { readPositiveNumber, readCsvOption, CADENCE_FLAG_DESCRIPTION } from "../../command-support.js";
+import { requestOxygen } from "../../http-client.js";
+import { readOption } from "../../util.js";
+import { Command } from "commander";
+import { buildTablesAutoDedupeSetBody } from "./automation.js";
+export function registerAutomation({ tablesCommand, handleAsyncAction }) {
+    tablesCommand.addCommand(new Command("auto-run")
+        .description("Inspect and manage a table's standing auto-run configuration (columns queued automatically when new rows are written).")
+        .addCommand(new Command("get")
+        .description("Show a table's standing auto-run configuration (columns queued automatically when new rows are written).")
+        .argument("<table>", "Table id or slug.")
+        .option("--json", "Print a JSON envelope.")
+        .action((table, options) => handleAsyncAction("tables auto-run get", options, () => {
+        const params = new URLSearchParams({ table });
+        return requestOxygen(`/api/cli/tables/auto-run?${params.toString()}`);
+    })))
+        .addCommand(new Command("set")
+        .description("Enable a standing auto-run: automatically queue the given columns for rows written to this table (imports, inserts, upserts), including workflow audience upserts and own-follower capture. A queued cell that already has a value is skipped unless --force, so an upsert that touches an existing, filled row is not charged again. Profile viewers use their separate `viewers enrichment --on` subscription. Default off.")
+        .argument("<table>", "Table id or slug.")
+        .requiredOption("--columns <csv>", "Comma-separated column keys to auto-run on newly written rows (tool, AI, formula, enrichment, bind, or lookup columns).")
+        .option("--sources <csv>", "Which write sources trigger the auto-run: any of import, insert, upsert, send. Defaults to all when omitted.")
+        .option("--force", "Re-run the columns even for rows that already have values.")
+        .option("--max-credits <n>", "Credit ceiling PER enqueued auto-run batch; rows beyond it are skipped with credit_limit_reached. Defaults to your plan's per-delivery ceiling when omitted.")
+        .option("--max-concurrency <n>", "Maximum concurrent row items per auto-run batch.")
+        .option("--json", "Print a JSON envelope.")
+        .action((table, options) => {
+        const columns = readCsvOption(options.columns);
+        const sources = readCsvOption(options.sources);
+        const maxCredits = readPositiveNumber(options.maxCredits);
+        const maxConcurrency = readPositiveInt(options.maxConcurrency);
+        const force = Boolean(options.force);
+        return handleAsyncAction("tables auto-run set", options, () => requestOxygen("/api/cli/tables/auto-run", {
+            method: "POST",
+            body: {
+                table,
+                columns,
+                ...(sources.length ? { sources } : {}),
+                ...(force ? { force: true } : {}),
+                ...(maxCredits !== undefined ? { max_credits: maxCredits } : {}),
+                ...(maxConcurrency ? { max_concurrency: maxConcurrency } : {}),
+            },
+        }));
+    }))
+        .addCommand(new Command("disable")
+        .description("Disable (clear) a table's standing auto-run configuration.")
+        .argument("<table>", "Table id or slug.")
+        .option("--json", "Print a JSON envelope.")
+        .action((table, options) => handleAsyncAction("tables auto-run disable", options, () => requestOxygen("/api/cli/tables/auto-run", {
+        method: "DELETE",
+        body: { table },
+    })))));
+    tablesCommand.addCommand(new Command("auto-dedupe")
+        .description("Inspect and manage a table's standing auto-dedupe configuration (duplicate rows collapsed automatically after every write; deleted rows are kept in row history).")
+        .addCommand(new Command("get")
+        .description("Show a table's standing auto-dedupe configuration.")
+        .argument("<table>", "Table id or slug.")
+        .option("--json", "Print a JSON envelope.")
+        .action((table, options) => handleAsyncAction("tables auto-dedupe get", options, () => {
+        const params = new URLSearchParams({ table });
+        return requestOxygen(`/api/cli/tables/auto-dedupe?${params.toString()}`);
+    })))
+        .addCommand(new Command("set")
+        .description("Enable a standing auto-dedupe: after every write (insert, upsert, import, send, webhook), duplicate groups containing a just-written row are collapsed by the keep policy — losers are DELETED automatically without per-write approval (kept in row history), and any standing auto-run only enriches the survivors. Runs BEFORE auto-run so credits are never spent on rows about to be deleted. Fuzzy-label matching is on-demand only: use `oxygen tables dedupe --normalize fuzzy-label` instead.")
+        .argument("<table>", "Table id or slug.")
+        .requiredOption("--on <cols>", "Key column(s): one column, or two comma-separated for a composite key (e.g. email or first_name,company).")
+        .option("--normalize <modes>", "Match mode per --on column, comma-separated positionally: exact (default), email, domain, or linkedin. Unpaired columns default to exact; fuzzy-label is rejected (on-demand only).")
+        .option("--keep <policy>", "Survivor per duplicate group (existing rows included): oldest (default), newest, or most-complete.", "oldest")
+        .option("--merge-values <mode>", "Fill the survivor's blank cells from the losers before deleting them: fill-empty.")
+        .option("--json", "Print a JSON envelope.")
+        .action((table, options) => handleAsyncAction("tables auto-dedupe set", options, () => requestOxygen("/api/cli/tables/auto-dedupe", {
+        method: "POST",
+        body: buildTablesAutoDedupeSetBody(table, options),
+    }))))
+        .addCommand(new Command("disable")
+        .description("Disable (clear) a table's standing auto-dedupe configuration.")
+        .argument("<table>", "Table id or slug.")
+        .option("--json", "Print a JSON envelope.")
+        .action((table, options) => handleAsyncAction("tables auto-dedupe disable", options, () => requestOxygen("/api/cli/tables/auto-dedupe", {
+        method: "DELETE",
+        body: { table },
+    })))));
+    tablesCommand.addCommand(new Command("schedule")
+        .description("Scheduled column refresh: a cron workflow re-runs one column on a schedule (only empty/failed cells unless --force). One schedule per column.")
+        .addCommand(new Command("set")
+        .description("Create or replace a column's scheduled refresh (a cron-triggered hosted workflow; visible via `oxygen workflows list`). Paid columns (tool, AI, enrichment) require --max-credits AND --approved; formula columns are free.")
+        .argument("<table>", "Table id or slug.")
+        .argument("<column>", "Column key or id (tool, AI, formula, or enrichment kind).")
+        .option("--cron <expr>", 'Cron expression in UTC, e.g. "0 9 * * *".')
+        .option("--every <sugar>", CADENCE_FLAG_DESCRIPTION)
+        .option("--max-credits <n>", "Credit ceiling PER scheduled refresh; required with --approved for paid columns.")
+        .option("--approved", "Approve the recurring paid runs; required with --max-credits for paid columns.")
+        .option("--force", "Re-run cells that already have values on every tick (full refresh instead of fill-missing).")
+        .option("--json", "Print a JSON envelope.")
+        .action((table, column, options) => {
+        const maxCredits = readPositiveNumber(options.maxCredits);
+        return handleAsyncAction("tables schedule set", options, () => requestOxygen("/api/cli/tables/schedule", {
+            method: "POST",
+            body: {
+                table,
+                column,
+                ...(readOption(options.cron) ? { cron: readOption(options.cron) } : {}),
+                ...(readOption(options.every) ? { every: readOption(options.every) } : {}),
+                ...(maxCredits !== undefined ? { max_credits: maxCredits } : {}),
+                ...(options.approved ? { approved: true } : {}),
+                ...(options.force ? { force: true } : {}),
+            },
+        }));
+    }))
+        .addCommand(new Command("list")
+        .description("List a table's scheduled column refreshes.")
+        .argument("<table>", "Table id or slug.")
+        .option("--json", "Print a JSON envelope.")
+        .action((table, options) => handleAsyncAction("tables schedule list", options, () => {
+        const params = new URLSearchParams({ table });
+        return requestOxygen(`/api/cli/tables/schedule?${params.toString()}`);
+    })))
+        .addCommand(new Command("remove")
+        .description("Remove a column's scheduled refresh (deletes the backing cron workflow; future scheduled runs stop).")
+        .argument("<table>", "Table id or slug.")
+        .argument("<column>", "Column key or id.")
+        .option("--json", "Print a JSON envelope.")
+        .action((table, column, options) => handleAsyncAction("tables schedule remove", options, () => requestOxygen("/api/cli/tables/schedule", {
+        method: "DELETE",
+        body: { table, column },
+    })))));
+}

package/dist/command-families/tables/register-external-imports.d.ts

@@ -0,0 +1,2 @@
+import type { TablesRegistrationContext } from "./registration-context.js";
+export declare function registerExternalImports({ tablesCommand, handleAsyncAction }: TablesRegistrationContext): void;