@primitivedotdev/sdk 0.17.0 → 0.18.0

package/dist/oclif/api-command.js

@@ -302,6 +302,45 @@ export function writeErrorWithHints(payload) {
         process.stderr.write(`${ERROR_CODE_HINTS[code]}\n`);
     }
 }
+// Format milliseconds as a short human-readable wall-clock duration.
+// Sub-second uses 2 decimal places (e.g. `0.18s`); seconds use 2
+// decimals up to 60s (`12.34s`); minute-plus uses `Mm SS.SSs`.
+// Display-only; the underlying ms value is what the caller computed.
+export function formatElapsed(ms) {
+    const seconds = ms / 1000;
+    if (seconds < 60)
+        return `${seconds.toFixed(2)}s`;
+    const minutes = Math.floor(seconds / 60);
+    const rem = seconds - minutes * 60;
+    return `${minutes}m ${rem.toFixed(2)}s`;
+}
+// Run `fn` and, when `enabled` is true, write a one-line wall-clock
+// timing report to stderr after it completes. Stderr keeps the row
+// data on stdout grep/jq-friendly. The timer captures the full
+// duration of the function (HTTPS round trip, server-side gate +
+// agent + delivery, polling, etc.), not just the API call's
+// server-side processing.
+//
+// Used by every `--time` callsite across the CLI: generated
+// operation commands and hand-coded shortcuts (send, whoami,
+// emails:latest, describe). Pulled out as a helper so timing is
+// uniform across commands and a single render-format change
+// propagates everywhere.
+export async function runWithTiming(enabled, fn) {
+    if (!enabled)
+        return fn();
+    const start = Date.now();
+    try {
+        return await fn();
+    }
+    finally {
+        process.stderr.write(`[time: ${formatElapsed(Date.now() - start)}]\n`);
+    }
+}
+// Shared `--time` flag definition every CLI command spreads into its
+// own static flags. Lives here so the flag's description and short
+// name stay consistent across the hand-coded and generated commands.
+export const TIME_FLAG_DESCRIPTION = "Print the wall-clock duration of this command to stderr after it completes (e.g. `[time: 1.34s]`). Useful for measuring `--wait` send latency, comparing CLI overhead, or capturing timing in scripts.";
 // Reserved flag names the body-field expander must never overwrite.
 // `--raw-body` and `--body-file` are the JSON escape hatches.
 // `--api-key`, `--base-url`, `--output` are infra. Path and query
@@ -363,6 +402,9 @@ function buildFlags(operation) {
             description: "API base URL (defaults to PRIMITIVE_API_URL or production)",
             env: "PRIMITIVE_API_URL",
         }),
+        time: Flags.boolean({
+            description: TIME_FLAG_DESCRIPTION,
+        }),
     };
     for (const parameter of [...operation.pathParams, ...operation.queryParams]) {
         flags[flagName(parameter.name)] = flagForParameter(parameter);
@@ -460,101 +502,103 @@ export function createOperationCommand(operation) {
         async run() {
             const { flags } = await this.parse(OperationCommand);
             const parsedFlags = flags;
-            const apiClient = new PrimitiveApiClient({
-                apiKey: typeof parsedFlags["api-key"] === "string"
-                    ? parsedFlags["api-key"]
-                    : undefined,
-                baseUrl: typeof parsedFlags["base-url"] === "string"
-                    ? parsedFlags["base-url"]
-                    : undefined,
-            });
-            // Two body sources, merged: explicit JSON via --body /
-            // --body-file (the base) plus per-field flags (the
-            // overrides). Per-field flag values take precedence on key
-            // conflicts so a caller can pass a base payload via --body
-            // and override one field on the command line.
-            let body;
-            if (operation.hasJsonBody) {
-                const explicit = readJsonBody(parsedFlags);
-                const overrides = collectBodyFieldFlags(parsedFlags, bodyFieldFlagToProperty);
-                if (Object.keys(overrides).length > 0) {
-                    if (explicit === undefined) {
-                        body = overrides;
-                    }
-                    else if (explicit !== null &&
-                        typeof explicit === "object" &&
-                        !Array.isArray(explicit)) {
-                        body = { ...explicit, ...overrides };
+            await runWithTiming(parsedFlags.time === true, async () => {
+                const apiClient = new PrimitiveApiClient({
+                    apiKey: typeof parsedFlags["api-key"] === "string"
+                        ? parsedFlags["api-key"]
+                        : undefined,
+                    baseUrl: typeof parsedFlags["base-url"] === "string"
+                        ? parsedFlags["base-url"]
+                        : undefined,
+                });
+                // Two body sources, merged: explicit JSON via --body /
+                // --body-file (the base) plus per-field flags (the
+                // overrides). Per-field flag values take precedence on key
+                // conflicts so a caller can pass a base payload via --body
+                // and override one field on the command line.
+                let body;
+                if (operation.hasJsonBody) {
+                    const explicit = readJsonBody(parsedFlags);
+                    const overrides = collectBodyFieldFlags(parsedFlags, bodyFieldFlagToProperty);
+                    if (Object.keys(overrides).length > 0) {
+                        if (explicit === undefined) {
+                            body = overrides;
+                        }
+                        else if (explicit !== null &&
+                            typeof explicit === "object" &&
+                            !Array.isArray(explicit)) {
+                            body = { ...explicit, ...overrides };
+                        }
+                        else {
+                            // Caller passed --raw-body as null, an array, or a
+                            // primitive AND also passed per-field flags. We can't
+                            // merge per-field overrides into a non-object body
+                            // shape, and silently dropping either source would
+                            // leave the caller's actual intent unclear. Refuse
+                            // loudly so the next attempt is unambiguous.
+                            const explicitKind = explicit === null
+                                ? "null"
+                                : Array.isArray(explicit)
+                                    ? "array"
+                                    : typeof explicit;
+                            const overrideFlags = Object.keys(overrides)
+                                .map((p) => `--${flagName(p)}`)
+                                .join(", ");
+                            throw new Errors.CLIError(`--raw-body must be a JSON object when also passing per-field flags (got ${explicitKind}); supplied per-field flags: ${overrideFlags}. Either drop --raw-body and rely on the per-field flags, or move every field into the JSON --raw-body and drop the flags.`);
+                        }
                     }
                     else {
-                        // Caller passed --raw-body as null, an array, or a
-                        // primitive AND also passed per-field flags. We can't
-                        // merge per-field overrides into a non-object body
-                        // shape, and silently dropping either source would
-                        // leave the caller's actual intent unclear. Refuse
-                        // loudly so the next attempt is unambiguous.
-                        const explicitKind = explicit === null
-                            ? "null"
-                            : Array.isArray(explicit)
-                                ? "array"
-                                : typeof explicit;
-                        const overrideFlags = Object.keys(overrides)
-                            .map((p) => `--${flagName(p)}`)
-                            .join(", ");
-                        throw new Errors.CLIError(`--raw-body must be a JSON object when also passing per-field flags (got ${explicitKind}); supplied per-field flags: ${overrideFlags}. Either drop --raw-body and rely on the per-field flags, or move every field into the JSON --raw-body and drop the flags.`);
+                        body = explicit;
                     }
                 }
-                else {
-                    body = explicit;
+                if (operation.bodyRequired && body === undefined) {
+                    throw new Errors.CLIError(`Operation ${operation.operationId} requires a body. Pass each field as a --flag (see --help) or supply JSON via --raw-body / --body-file.`);
                 }
-            }
-            if (operation.bodyRequired && body === undefined) {
-                throw new Errors.CLIError(`Operation ${operation.operationId} requires a body. Pass each field as a --flag (see --help) or supply JSON via --raw-body / --body-file.`);
-            }
-            const operationFn = operations[operation.sdkName];
-            const result = await operationFn({
-                body,
-                client: apiClient.client,
-                parseAs: operation.binaryResponse ? "blob" : "auto",
-                path: collectValues(operation.pathParams, parsedFlags),
-                query: collectValues(operation.queryParams, parsedFlags),
-                responseStyle: "fields",
-            });
-            if (result.error) {
-                writeErrorWithHints(extractErrorPayload(result.error));
-                process.exitCode = 1;
-                return;
-            }
-            if (operation.binaryResponse) {
-                const blob = result.data;
-                const bytes = Buffer.from(await blob.arrayBuffer());
-                const output = parsedFlags.output;
-                if (typeof output === "string") {
-                    writeFileSync(output, bytes);
+                const operationFn = operations[operation.sdkName];
+                const result = await operationFn({
+                    body,
+                    client: apiClient.client,
+                    parseAs: operation.binaryResponse ? "blob" : "auto",
+                    path: collectValues(operation.pathParams, parsedFlags),
+                    query: collectValues(operation.queryParams, parsedFlags),
+                    responseStyle: "fields",
+                });
+                if (result.error) {
+                    writeErrorWithHints(extractErrorPayload(result.error));
+                    process.exitCode = 1;
                     return;
                 }
-                process.stdout.write(bytes);
-                return;
-            }
-            const envelope = result.data;
-            const cursor = envelope?.meta?.cursor;
-            if (cursor) {
-                process.stderr.write(`next cursor: ${cursor}\n`);
-            }
-            // Empty-result hint. When a list-style operation returns
-            // an empty array, emit an operation-specific note to
-            // stderr so a naive caller can distinguish "nothing here"
-            // from "something isn't set up." Stdout still gets the
-            // raw `[]` so machine-readable output is unchanged. The
-            // AGX walkthrough flagged this: `list-deliveries` returning
-            // `[]` left the agent unsure whether they had an empty
-            // delivery log or no endpoints configured at all.
-            if (Array.isArray(envelope?.data) && envelope.data.length === 0) {
-                const hint = EMPTY_RESULT_HINTS[operation.sdkName];
-                if (hint)
-                    process.stderr.write(`${hint}\n`);
-            }
-            this.log(JSON.stringify(envelope?.data ?? null, null, 2));
+                if (operation.binaryResponse) {
+                    const blob = result.data;
+                    const bytes = Buffer.from(await blob.arrayBuffer());
+                    const output = parsedFlags.output;
+                    if (typeof output === "string") {
+                        writeFileSync(output, bytes);
+                        return;
+                    }
+                    process.stdout.write(bytes);
+                    return;
+                }
+                const envelope = result.data;
+                const cursor = envelope?.meta?.cursor;
+                if (cursor) {
+                    process.stderr.write(`next cursor: ${cursor}\n`);
+                }
+                // Empty-result hint. When a list-style operation returns
+                // an empty array, emit an operation-specific note to
+                // stderr so a naive caller can distinguish "nothing here"
+                // from "something isn't set up." Stdout still gets the
+                // raw `[]` so machine-readable output is unchanged. The
+                // AGX walkthrough flagged this: `list-deliveries` returning
+                // `[]` left the agent unsure whether they had an empty
+                // delivery log or no endpoints configured at all.
+                if (Array.isArray(envelope?.data) && envelope.data.length === 0) {
+                    const hint = EMPTY_RESULT_HINTS[operation.sdkName];
+                    if (hint)
+                        process.stderr.write(`${hint}\n`);
+                }
+                this.log(JSON.stringify(envelope?.data ?? null, null, 2));
+            });
         }
     }
     return OperationCommand;

package/dist/oclif/commands/emails-latest.js

@@ -1,7 +1,7 @@
 import { Command, Flags } from "@oclif/core";
 import { listEmails } from "../../api/generated/sdk.gen.js";
 import { PrimitiveApiClient } from "../../api/index.js";
-import { extractErrorPayload, writeErrorWithHints } from "../api-command.js";
+import { extractErrorPayload, runWithTiming, TIME_FLAG_DESCRIPTION, writeErrorWithHints, } from "../api-command.js";
 // `primitive emails:latest` is the agent-grade shortcut for "show me
 // the most recent inbound emails as something I can read at a glance."
 // `emails:list-emails` returns the full JSON envelope which is great
@@ -113,43 +113,48 @@ class EmailsLatestCommand extends Command {
         json: Flags.boolean({
             description: "Print the raw response envelope (with full UUIDs and meta) as JSON on STDOUT instead of the text table. Useful for piping into `jq`, capturing ids for follow-up commands, or scripting.",
         }),
+        time: Flags.boolean({
+            description: TIME_FLAG_DESCRIPTION,
+        }),
     };
     async run() {
         const { flags } = await this.parse(EmailsLatestCommand);
-        const apiClient = new PrimitiveApiClient({
-            apiKey: flags["api-key"],
-            baseUrl: flags["base-url"],
-        });
-        const result = await listEmails({
-            client: apiClient.client,
-            query: { limit: flags.limit },
-            responseStyle: "fields",
+        await runWithTiming(flags.time, async () => {
+            const apiClient = new PrimitiveApiClient({
+                apiKey: flags["api-key"],
+                baseUrl: flags["base-url"],
+            });
+            const result = await listEmails({
+                client: apiClient.client,
+                query: { limit: flags.limit },
+                responseStyle: "fields",
+            });
+            if (result.error) {
+                writeErrorWithHints(extractErrorPayload(result.error));
+                process.exitCode = 1;
+                return;
+            }
+            const envelope = result.data;
+            if (flags.json) {
+                // Raw envelope on stdout. Mirrors the shape `emails:list-emails`
+                // emits so callers can swap one for the other when they want
+                // table vs json without remembering different command names.
+                this.log(JSON.stringify(envelope ?? null, null, 2));
+                return;
+            }
+            const rows = envelope?.data ?? [];
+            if (rows.length === 0) {
+                process.stderr.write("No inbound emails yet. Send an email to one of your verified domains to populate this list.\n");
+                return;
+            }
+            const idWidth = pickIdWidth(Boolean(process.stdout.isTTY));
+            // Header on stderr so the table itself stays grep-friendly.
+            const header = `${"ID".padEnd(idWidth)}  ${"RECEIVED (UTC)".padEnd(RECEIVED_DISPLAY_WIDTH)}  ${"FROM".padEnd(ADDRESS_DISPLAY_WIDTH)}  ${"TO".padEnd(ADDRESS_DISPLAY_WIDTH)}  SUBJECT`;
+            process.stderr.write(`${header}\n`);
+            for (const row of rows) {
+                this.log(formatRow(row, idWidth));
+            }
         });
-        if (result.error) {
-            writeErrorWithHints(extractErrorPayload(result.error));
-            process.exitCode = 1;
-            return;
-        }
-        const envelope = result.data;
-        if (flags.json) {
-            // Raw envelope on stdout. Mirrors the shape `emails:list-emails`
-            // emits so callers can swap one for the other when they want
-            // table vs json without remembering different command names.
-            this.log(JSON.stringify(envelope ?? null, null, 2));
-            return;
-        }
-        const rows = envelope?.data ?? [];
-        if (rows.length === 0) {
-            process.stderr.write("No inbound emails yet. Send an email to one of your verified domains to populate this list.\n");
-            return;
-        }
-        const idWidth = pickIdWidth(Boolean(process.stdout.isTTY));
-        // Header on stderr so the table itself stays grep-friendly.
-        const header = `${"ID".padEnd(idWidth)}  ${"RECEIVED (UTC)".padEnd(RECEIVED_DISPLAY_WIDTH)}  ${"FROM".padEnd(ADDRESS_DISPLAY_WIDTH)}  ${"TO".padEnd(ADDRESS_DISPLAY_WIDTH)}  SUBJECT`;
-        process.stderr.write(`${header}\n`);
-        for (const row of rows) {
-            this.log(formatRow(row, idWidth));
-        }
     }
 }
 export default EmailsLatestCommand;

package/dist/oclif/commands/send.js

@@ -1,7 +1,7 @@
 import { Command, Errors, Flags } from "@oclif/core";
 import { listDomains, sendEmail } from "../../api/generated/sdk.gen.js";
 import { PrimitiveApiClient } from "../../api/index.js";
-import { extractErrorCode, extractErrorPayload, formatErrorPayload, writeErrorWithHints, } from "../api-command.js";
+import { extractErrorCode, extractErrorPayload, formatErrorPayload, runWithTiming, TIME_FLAG_DESCRIPTION, writeErrorWithHints, } from "../api-command.js";
 // `primitive send` is the agent-grade shortcut for the most common
 // case: send a fresh outbound email. It wraps `sending:send-email`
 // with two ergonomic defaults that the underlying operation can't
@@ -139,43 +139,48 @@ class SendCommand extends Command {
         "wait-timeout-ms": Flags.integer({
             description: "Maximum time to wait when --wait is set. Defaults to 30000ms.",
         }),
+        time: Flags.boolean({
+            description: TIME_FLAG_DESCRIPTION,
+        }),
     };
     async run() {
         const { flags } = await this.parse(SendCommand);
         if (!flags.body && !flags.html) {
             throw new Errors.CLIError("Either --body or --html (or both) is required.");
         }
-        const apiClient = new PrimitiveApiClient({
-            apiKey: flags["api-key"],
-            baseUrl: flags["base-url"],
-        });
-        const from = flags.from ?? (await pickDefaultFromAddress(apiClient));
-        const subject = flags.subject ?? (flags.body ? deriveSubject(flags.body) : "Message");
-        const result = await sendEmail({
-            body: {
-                from,
-                to: flags.to,
-                subject,
-                ...(flags.body !== undefined ? { body_text: flags.body } : {}),
-                ...(flags.html !== undefined ? { body_html: flags.html } : {}),
-                ...(flags["in-reply-to"] !== undefined
-                    ? { in_reply_to: flags["in-reply-to"] }
-                    : {}),
-                ...(flags.wait !== undefined ? { wait: flags.wait } : {}),
-                ...(flags["wait-timeout-ms"] !== undefined
-                    ? { wait_timeout_ms: flags["wait-timeout-ms"] }
-                    : {}),
-            },
-            client: apiClient.client,
-            responseStyle: "fields",
+        await runWithTiming(flags.time, async () => {
+            const apiClient = new PrimitiveApiClient({
+                apiKey: flags["api-key"],
+                baseUrl: flags["base-url"],
+            });
+            const from = flags.from ?? (await pickDefaultFromAddress(apiClient));
+            const subject = flags.subject ?? (flags.body ? deriveSubject(flags.body) : "Message");
+            const result = await sendEmail({
+                body: {
+                    from,
+                    to: flags.to,
+                    subject,
+                    ...(flags.body !== undefined ? { body_text: flags.body } : {}),
+                    ...(flags.html !== undefined ? { body_html: flags.html } : {}),
+                    ...(flags["in-reply-to"] !== undefined
+                        ? { in_reply_to: flags["in-reply-to"] }
+                        : {}),
+                    ...(flags.wait !== undefined ? { wait: flags.wait } : {}),
+                    ...(flags["wait-timeout-ms"] !== undefined
+                        ? { wait_timeout_ms: flags["wait-timeout-ms"] }
+                        : {}),
+                },
+                client: apiClient.client,
+                responseStyle: "fields",
+            });
+            if (result.error) {
+                writeErrorWithHints(extractErrorPayload(result.error));
+                process.exitCode = 1;
+                return;
+            }
+            const envelope = result.data;
+            this.log(JSON.stringify(envelope?.data ?? null, null, 2));
         });
-        if (result.error) {
-            writeErrorWithHints(extractErrorPayload(result.error));
-            process.exitCode = 1;
-            return;
-        }
-        const envelope = result.data;
-        this.log(JSON.stringify(envelope?.data ?? null, null, 2));
     }
 }
 export default SendCommand;

package/dist/oclif/commands/whoami.js

@@ -1,7 +1,7 @@
 import { Command, Errors, Flags } from "@oclif/core";
 import { getAccount } from "../../api/generated/sdk.gen.js";
 import { PrimitiveApiClient } from "../../api/index.js";
-import { extractErrorPayload, writeErrorWithHints } from "../api-command.js";
+import { extractErrorPayload, runWithTiming, TIME_FLAG_DESCRIPTION, writeErrorWithHints, } from "../api-command.js";
 // `primitive whoami` is the credentials smoke-test the AGX
 // walkthrough kept asking for. Before this command, a user with a
 // suspect API key had no fast way to verify "is my key live and
@@ -28,40 +28,45 @@ class WhoamiCommand extends Command {
             description: "API base URL (defaults to PRIMITIVE_API_URL or production)",
             env: "PRIMITIVE_API_URL",
         }),
+        time: Flags.boolean({
+            description: TIME_FLAG_DESCRIPTION,
+        }),
     };
     async run() {
         const { flags } = await this.parse(WhoamiCommand);
-        const apiClient = new PrimitiveApiClient({
-            apiKey: flags["api-key"],
-            baseUrl: flags["base-url"],
-        });
-        const result = await getAccount({
-            client: apiClient.client,
-            responseStyle: "fields",
+        await runWithTiming(flags.time, async () => {
+            const apiClient = new PrimitiveApiClient({
+                apiKey: flags["api-key"],
+                baseUrl: flags["base-url"],
+            });
+            const result = await getAccount({
+                client: apiClient.client,
+                responseStyle: "fields",
+            });
+            if (result.error) {
+                writeErrorWithHints(extractErrorPayload(result.error));
+                process.exitCode = 1;
+                return;
+            }
+            const envelope = result.data;
+            const account = envelope?.data;
+            if (!account) {
+                process.stderr.write("Server returned an empty account body; this should not happen for a valid key.\n");
+                throw new Errors.CLIError("unexpected empty response");
+            }
+            // Concise human-readable summary on stderr; the full account
+            // JSON goes to stdout so a script can pipe it.
+            const onboarding = account.onboarding_completed === true
+                ? "complete"
+                : account.onboarding_step
+                    ? `in progress (step: ${account.onboarding_step})`
+                    : "incomplete";
+            process.stderr.write(`Authenticated as ${account.email}\n`);
+            process.stderr.write(`  Account id: ${account.id}\n`);
+            process.stderr.write(`  Plan:       ${account.plan}\n`);
+            process.stderr.write(`  Onboarding: ${onboarding}\n`);
+            this.log(JSON.stringify(account, null, 2));
         });
-        if (result.error) {
-            writeErrorWithHints(extractErrorPayload(result.error));
-            process.exitCode = 1;
-            return;
-        }
-        const envelope = result.data;
-        const account = envelope?.data;
-        if (!account) {
-            process.stderr.write("Server returned an empty account body; this should not happen for a valid key.\n");
-            throw new Errors.CLIError("unexpected empty response");
-        }
-        // Concise human-readable summary on stderr; the full account
-        // JSON goes to stdout so a script can pipe it.
-        const onboarding = account.onboarding_completed === true
-            ? "complete"
-            : account.onboarding_step
-                ? `in progress (step: ${account.onboarding_step})`
-                : "incomplete";
-        process.stderr.write(`Authenticated as ${account.email}\n`);
-        process.stderr.write(`  Account id: ${account.id}\n`);
-        process.stderr.write(`  Plan:       ${account.plan}\n`);
-        process.stderr.write(`  Onboarding: ${onboarding}\n`);
-        this.log(JSON.stringify(account, null, 2));
     }
 }
 export default WhoamiCommand;

package/oclif.manifest.json

@@ -150,6 +150,12 @@
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
+        },
+        "time": {
+          "description": "Print the wall-clock duration of this command to stderr after it completes (e.g. `[time: 1.34s]`). Useful for measuring `--wait` send latency, comparing CLI overhead, or capturing timing in scripts.",
+          "name": "time",
+          "allowNo": false,
+          "type": "boolean"
         }
       },
       "hasDynamicHelp": false,
@@ -186,6 +192,12 @@
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
+        },
+        "time": {
+          "description": "Print the wall-clock duration of this command to stderr after it completes (e.g. `[time: 1.34s]`). Useful for measuring `--wait` send latency, comparing CLI overhead, or capturing timing in scripts.",
+          "name": "time",
+          "allowNo": false,
+          "type": "boolean"
         }
       },
       "hasDynamicHelp": false,
@@ -238,6 +250,12 @@
           "name": "json",
           "allowNo": false,
           "type": "boolean"
+        },
+        "time": {
+          "description": "Print the wall-clock duration of this command to stderr after it completes (e.g. `[time: 1.34s]`). Useful for measuring `--wait` send latency, comparing CLI overhead, or capturing timing in scripts.",
+          "name": "time",
+          "allowNo": false,
+          "type": "boolean"
         }
       },
       "hasDynamicHelp": false,
@@ -270,6 +288,12 @@
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
+        },
+        "time": {
+          "description": "Print the wall-clock duration of this command to stderr after it completes (e.g. `[time: 1.34s]`). Useful for measuring `--wait` send latency, comparing CLI overhead, or capturing timing in scripts.",
+          "name": "time",
+          "allowNo": false,
+          "type": "boolean"
         }
       },
       "hasDynamicHelp": false,
@@ -302,6 +326,12 @@
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
+        },
+        "time": {
+          "description": "Print the wall-clock duration of this command to stderr after it completes (e.g. `[time: 1.34s]`). Useful for measuring `--wait` send latency, comparing CLI overhead, or capturing timing in scripts.",
+          "name": "time",
+          "allowNo": false,
+          "type": "boolean"
         }
       },
       "hasDynamicHelp": false,
@@ -334,6 +364,12 @@
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
+        },
+        "time": {
+          "description": "Print the wall-clock duration of this command to stderr after it completes (e.g. `[time: 1.34s]`). Useful for measuring `--wait` send latency, comparing CLI overhead, or capturing timing in scripts.",
+          "name": "time",
+          "allowNo": false,
+          "type": "boolean"
         }
       },
       "hasDynamicHelp": false,
@@ -366,6 +402,12 @@
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
+        },
+        "time": {
+          "description": "Print the wall-clock duration of this command to stderr after it completes (e.g. `[time: 1.34s]`). Useful for measuring `--wait` send latency, comparing CLI overhead, or capturing timing in scripts.",
+          "name": "time",
+          "allowNo": false,
+          "type": "boolean"
         }
       },
       "hasDynamicHelp": false,
@@ -399,6 +441,12 @@
           "multiple": false,
           "type": "option"
         },
+        "time": {
+          "description": "Print the wall-clock duration of this command to stderr after it completes (e.g. `[time: 1.34s]`). Useful for measuring `--wait` send latency, comparing CLI overhead, or capturing timing in scripts.",
+          "name": "time",
+          "allowNo": false,
+          "type": "boolean"
+        },
         "raw-body": {
           "description": "Full request body as raw JSON. Escape hatch for nested or complex fields (e.g. arrays); prefer per-field flags (e.g. --to, --from, --body-text) when available.",
           "name": "raw-body",
@@ -458,6 +506,12 @@
           "multiple": false,
           "type": "option"
         },
+        "time": {
+          "description": "Print the wall-clock duration of this command to stderr after it completes (e.g. `[time: 1.34s]`). Useful for measuring `--wait` send latency, comparing CLI overhead, or capturing timing in scripts.",
+          "name": "time",
+          "allowNo": false,
+          "type": "boolean"
+        },
         "raw-body": {
           "description": "Full request body as raw JSON. Escape hatch for nested or complex fields (e.g. arrays); prefer per-field flags (e.g. --to, --from, --body-text) when available.",
           "name": "raw-body",
@@ -511,6 +565,12 @@
           "multiple": false,
           "type": "option"
         },
+        "time": {
+          "description": "Print the wall-clock duration of this command to stderr after it completes (e.g. `[time: 1.34s]`). Useful for measuring `--wait` send latency, comparing CLI overhead, or capturing timing in scripts.",
+          "name": "time",
+          "allowNo": false,
+          "type": "boolean"
+        },
         "id": {
           "description": "Resource UUID",
           "name": "id",
@@ -550,6 +610,12 @@
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
+        },
+        "time": {
+          "description": "Print the wall-clock duration of this command to stderr after it completes (e.g. `[time: 1.34s]`). Useful for measuring `--wait` send latency, comparing CLI overhead, or capturing timing in scripts.",
+          "name": "time",
+          "allowNo": false,
+          "type": "boolean"
         }
       },
       "hasDynamicHelp": false,
@@ -583,6 +649,12 @@
           "multiple": false,
           "type": "option"
         },
+        "time": {
+          "description": "Print the wall-clock duration of this command to stderr after it completes (e.g. `[time: 1.34s]`). Useful for measuring `--wait` send latency, comparing CLI overhead, or capturing timing in scripts.",
+          "name": "time",
+          "allowNo": false,
+          "type": "boolean"
+        },
         "id": {
           "description": "Resource UUID",
           "name": "id",
@@ -650,6 +722,12 @@
           "multiple": false,
           "type": "option"
         },
+        "time": {
+          "description": "Print the wall-clock duration of this command to stderr after it completes (e.g. `[time: 1.34s]`). Useful for measuring `--wait` send latency, comparing CLI overhead, or capturing timing in scripts.",
+          "name": "time",
+          "allowNo": false,
+          "type": "boolean"
+        },
         "id": {
           "description": "Resource UUID",
           "name": "id",
@@ -690,6 +768,12 @@
           "multiple": false,
           "type": "option"
         },
+        "time": {
+          "description": "Print the wall-clock duration of this command to stderr after it completes (e.g. `[time: 1.34s]`). Useful for measuring `--wait` send latency, comparing CLI overhead, or capturing timing in scripts.",
+          "name": "time",
+          "allowNo": false,
+          "type": "boolean"
+        },
         "id": {
           "description": "Resource UUID",
           "name": "id",
@@ -730,6 +814,12 @@
           "multiple": false,
           "type": "option"
         },
+        "time": {
+          "description": "Print the wall-clock duration of this command to stderr after it completes (e.g. `[time: 1.34s]`). Useful for measuring `--wait` send latency, comparing CLI overhead, or capturing timing in scripts.",
+          "name": "time",
+          "allowNo": false,
+          "type": "boolean"
+        },
         "id": {
           "description": "Resource UUID",
           "name": "id",
@@ -770,6 +860,12 @@
           "multiple": false,
           "type": "option"
         },
+        "time": {
+          "description": "Print the wall-clock duration of this command to stderr after it completes (e.g. `[time: 1.34s]`). Useful for measuring `--wait` send latency, comparing CLI overhead, or capturing timing in scripts.",
+          "name": "time",
+          "allowNo": false,
+          "type": "boolean"
+        },
         "id": {
           "description": "Resource UUID",
           "name": "id",
@@ -825,6 +921,12 @@
           "multiple": false,
           "type": "option"
         },
+        "time": {
+          "description": "Print the wall-clock duration of this command to stderr after it completes (e.g. `[time: 1.34s]`). Useful for measuring `--wait` send latency, comparing CLI overhead, or capturing timing in scripts.",
+          "name": "time",
+          "allowNo": false,
+          "type": "boolean"
+        },
         "id": {
           "description": "Resource UUID",
           "name": "id",
@@ -880,6 +982,12 @@
           "multiple": false,
           "type": "option"
         },
+        "time": {
+          "description": "Print the wall-clock duration of this command to stderr after it completes (e.g. `[time: 1.34s]`). Useful for measuring `--wait` send latency, comparing CLI overhead, or capturing timing in scripts.",
+          "name": "time",
+          "allowNo": false,
+          "type": "boolean"
+        },
         "id": {
           "description": "Resource UUID",
           "name": "id",
@@ -920,6 +1028,12 @@
           "multiple": false,
           "type": "option"
         },
+        "time": {
+          "description": "Print the wall-clock duration of this command to stderr after it completes (e.g. `[time: 1.34s]`). Useful for measuring `--wait` send latency, comparing CLI overhead, or capturing timing in scripts.",
+          "name": "time",
+          "allowNo": false,
+          "type": "boolean"
+        },
         "cursor": {
           "description": "Pagination cursor from a previous response's `meta.cursor` field.\nFormat: `{ISO-datetime}|{id}`\n",
           "name": "cursor",
@@ -1008,6 +1122,12 @@
           "multiple": false,
           "type": "option"
         },
+        "time": {
+          "description": "Print the wall-clock duration of this command to stderr after it completes (e.g. `[time: 1.34s]`). Useful for measuring `--wait` send latency, comparing CLI overhead, or capturing timing in scripts.",
+          "name": "time",
+          "allowNo": false,
+          "type": "boolean"
+        },
         "id": {
           "description": "Resource UUID",
           "name": "id",
@@ -1048,6 +1168,12 @@
           "multiple": false,
           "type": "option"
         },
+        "time": {
+          "description": "Print the wall-clock duration of this command to stderr after it completes (e.g. `[time: 1.34s]`). Useful for measuring `--wait` send latency, comparing CLI overhead, or capturing timing in scripts.",
+          "name": "time",
+          "allowNo": false,
+          "type": "boolean"
+        },
         "raw-body": {
           "description": "Full request body as raw JSON. Escape hatch for nested or complex fields (e.g. arrays); prefer per-field flags (e.g. --to, --from, --body-text) when available.",
           "name": "raw-body",
@@ -1114,6 +1240,12 @@
           "multiple": false,
           "type": "option"
         },
+        "time": {
+          "description": "Print the wall-clock duration of this command to stderr after it completes (e.g. `[time: 1.34s]`). Useful for measuring `--wait` send latency, comparing CLI overhead, or capturing timing in scripts.",
+          "name": "time",
+          "allowNo": false,
+          "type": "boolean"
+        },
         "id": {
           "description": "Resource UUID",
           "name": "id",
@@ -1153,6 +1285,12 @@
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
+        },
+        "time": {
+          "description": "Print the wall-clock duration of this command to stderr after it completes (e.g. `[time: 1.34s]`). Useful for measuring `--wait` send latency, comparing CLI overhead, or capturing timing in scripts.",
+          "name": "time",
+          "allowNo": false,
+          "type": "boolean"
         }
       },
       "hasDynamicHelp": false,
@@ -1186,6 +1324,12 @@
           "multiple": false,
           "type": "option"
         },
+        "time": {
+          "description": "Print the wall-clock duration of this command to stderr after it completes (e.g. `[time: 1.34s]`). Useful for measuring `--wait` send latency, comparing CLI overhead, or capturing timing in scripts.",
+          "name": "time",
+          "allowNo": false,
+          "type": "boolean"
+        },
         "id": {
           "description": "Resource UUID",
           "name": "id",
@@ -1226,6 +1370,12 @@
           "multiple": false,
           "type": "option"
         },
+        "time": {
+          "description": "Print the wall-clock duration of this command to stderr after it completes (e.g. `[time: 1.34s]`). Useful for measuring `--wait` send latency, comparing CLI overhead, or capturing timing in scripts.",
+          "name": "time",
+          "allowNo": false,
+          "type": "boolean"
+        },
         "id": {
           "description": "Resource UUID",
           "name": "id",
@@ -1300,6 +1450,12 @@
           "multiple": false,
           "type": "option"
         },
+        "time": {
+          "description": "Print the wall-clock duration of this command to stderr after it completes (e.g. `[time: 1.34s]`). Useful for measuring `--wait` send latency, comparing CLI overhead, or capturing timing in scripts.",
+          "name": "time",
+          "allowNo": false,
+          "type": "boolean"
+        },
         "raw-body": {
           "description": "Full request body as raw JSON. Escape hatch for nested or complex fields (e.g. arrays); prefer per-field flags (e.g. --to, --from, --body-text) when available.",
           "name": "raw-body",
@@ -1371,6 +1527,12 @@
           "multiple": false,
           "type": "option"
         },
+        "time": {
+          "description": "Print the wall-clock duration of this command to stderr after it completes (e.g. `[time: 1.34s]`). Useful for measuring `--wait` send latency, comparing CLI overhead, or capturing timing in scripts.",
+          "name": "time",
+          "allowNo": false,
+          "type": "boolean"
+        },
         "id": {
           "description": "Resource UUID",
           "name": "id",
@@ -1410,6 +1572,12 @@
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
+        },
+        "time": {
+          "description": "Print the wall-clock duration of this command to stderr after it completes (e.g. `[time: 1.34s]`). Useful for measuring `--wait` send latency, comparing CLI overhead, or capturing timing in scripts.",
+          "name": "time",
+          "allowNo": false,
+          "type": "boolean"
         }
       },
       "hasDynamicHelp": false,
@@ -1443,6 +1611,12 @@
           "multiple": false,
           "type": "option"
         },
+        "time": {
+          "description": "Print the wall-clock duration of this command to stderr after it completes (e.g. `[time: 1.34s]`). Useful for measuring `--wait` send latency, comparing CLI overhead, or capturing timing in scripts.",
+          "name": "time",
+          "allowNo": false,
+          "type": "boolean"
+        },
         "id": {
           "description": "Resource UUID",
           "name": "id",
@@ -1502,6 +1676,12 @@
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
+        },
+        "time": {
+          "description": "Print the wall-clock duration of this command to stderr after it completes (e.g. `[time: 1.34s]`). Useful for measuring `--wait` send latency, comparing CLI overhead, or capturing timing in scripts.",
+          "name": "time",
+          "allowNo": false,
+          "type": "boolean"
         }
       },
       "hasDynamicHelp": false,
@@ -1535,6 +1715,12 @@
           "multiple": false,
           "type": "option"
         },
+        "time": {
+          "description": "Print the wall-clock duration of this command to stderr after it completes (e.g. `[time: 1.34s]`). Useful for measuring `--wait` send latency, comparing CLI overhead, or capturing timing in scripts.",
+          "name": "time",
+          "allowNo": false,
+          "type": "boolean"
+        },
         "id": {
           "description": "Resource UUID",
           "name": "id",
@@ -1575,6 +1761,12 @@
           "multiple": false,
           "type": "option"
         },
+        "time": {
+          "description": "Print the wall-clock duration of this command to stderr after it completes (e.g. `[time: 1.34s]`). Useful for measuring `--wait` send latency, comparing CLI overhead, or capturing timing in scripts.",
+          "name": "time",
+          "allowNo": false,
+          "type": "boolean"
+        },
         "cursor": {
           "description": "Pagination cursor from a previous response's `meta.cursor` field.\nFormat: `{ISO-datetime}|{id}`\n",
           "name": "cursor",
@@ -1663,6 +1855,12 @@
           "multiple": false,
           "type": "option"
         },
+        "time": {
+          "description": "Print the wall-clock duration of this command to stderr after it completes (e.g. `[time: 1.34s]`). Useful for measuring `--wait` send latency, comparing CLI overhead, or capturing timing in scripts.",
+          "name": "time",
+          "allowNo": false,
+          "type": "boolean"
+        },
         "id": {
           "description": "Resource UUID",
           "name": "id",
@@ -1744,6 +1942,12 @@
           "multiple": false,
           "type": "option"
         },
+        "time": {
+          "description": "Print the wall-clock duration of this command to stderr after it completes (e.g. `[time: 1.34s]`). Useful for measuring `--wait` send latency, comparing CLI overhead, or capturing timing in scripts.",
+          "name": "time",
+          "allowNo": false,
+          "type": "boolean"
+        },
         "raw-body": {
           "description": "Full request body as raw JSON. Escape hatch for nested or complex fields (e.g. arrays); prefer per-field flags (e.g. --to, --from, --body-text) when available.",
           "name": "raw-body",
@@ -1845,6 +2049,12 @@
           "multiple": false,
           "type": "option"
         },
+        "time": {
+          "description": "Print the wall-clock duration of this command to stderr after it completes (e.g. `[time: 1.34s]`). Useful for measuring `--wait` send latency, comparing CLI overhead, or capturing timing in scripts.",
+          "name": "time",
+          "allowNo": false,
+          "type": "boolean"
+        },
         "cursor": {
           "description": "Pagination cursor from a previous response's `meta.cursor` field.\nFormat: `{ISO-datetime}|{id}`\n",
           "name": "cursor",
@@ -1931,6 +2141,12 @@
           "multiple": false,
           "type": "option"
         },
+        "time": {
+          "description": "Print the wall-clock duration of this command to stderr after it completes (e.g. `[time: 1.34s]`). Useful for measuring `--wait` send latency, comparing CLI overhead, or capturing timing in scripts.",
+          "name": "time",
+          "allowNo": false,
+          "type": "boolean"
+        },
         "id": {
           "description": "Delivery ID (numeric)",
           "name": "id",
@@ -1951,5 +2167,5 @@
       "enableJsonFlag": false
     }
   },
-  "version": "0.17.0"
+  "version": "0.18.0"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@primitivedotdev/sdk",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "description": "Official Primitive Node.js SDK — webhook, api, openapi, contract, and parser modules",
   "type": "module",
   "module": "./dist/index.js",