@garuhq/cli 0.9.0 → 0.11.0

package/CHANGELOG.md

@@ -3,6 +3,39 @@
 All notable changes to `@garuhq/cli` are documented in this file. Format:
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Versioning: [SemVer](https://semver.org/).
 
+## [0.11.0] — 2026-08-22
+
+### Changed
+
+- **`garu webhooks events` now targets `/api/v1/webhook-events`, uuid-keyed.**
+  `get`, `retry`, and `resend` take a `<uuid>` positional argument instead of
+  a numeric id. `list` output now reports `count`/`totalCount`/`totalPages`
+  instead of a `page`/`total` counter, and every row/detail view prints the
+  event's `uuid`.
+- **`@garuhq/node` bumped to `3.0.0`.** Breaking for `garu.webhookEvents.*`
+  (see that package's changelog).
+
+### Breaking
+
+- `garu webhooks events get <id>` / `retry <id>` / `resend <id>` now expect
+  a `uuid`, not a numeric id. Run `garu webhooks events list` to read the
+  `uuid` of the event you want to act on.
+
+## [0.10.0] — 2026-08-22
+
+### Added
+
+- **`garu customers` — manage your customer base.** `create`, `list`, `get`,
+  `update`, `set-billing-email`, `clear-billing-email`, `delete`. Backed by
+  the new `/api/v1/customers`, keyed on `uuid`.
+
+### Changed
+
+- **`@garuhq/node` bumped to `2.0.0`.** Breaking for `garu.customers.*` (see
+  that package's changelog); does not affect any other `garu-cli` command —
+  `customers` is a new command group in this release, so nothing here
+  changes behavior.
+
 ## [0.9.0] — 2026-08-21
 
 ### Added
@@ -42,7 +75,7 @@ All notable changes to `@garuhq/cli` are documented in this file. Format:
     `.expiresAt` (was `.date` / `.deadline`), and a new `charge.chargedTotal`
     field (what was actually charged, vs. `.amount`, the product's base
     price). `charges list`'s response shape is now `{ data, count, totalCount,
-    totalPages }` (was `{ data, meta }`).
+totalPages }` (was `{ data, meta }`).
 
 ## [0.8.0] — 2026-07-18
 

package/README.md

@@ -402,6 +402,43 @@ garu refund-requests reject a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
 
 ---
 
+### `garu customers create`
+
+Register a customer for the current seller. Registering the same `document`
+twice attaches your profile to the existing global customer instead of
+erroring — safe to call once per seller per person.
+
+```bash
+garu customers create \
+  --name "Maria Silva" --email maria@exemplo.com.br \
+  --document 12345678909 --phone 11987654321 \
+  --person-type fisica
+```
+
+| Flag                    | Description                                    |
+| ----------------------- | ---------------------------------------------- |
+| `--name <name>`         | Customer name (required)                       |
+| `--email <email>`       | Customer email (required)                      |
+| `--document <document>` | CPF (11 digits) or CNPJ (14 digits) (required) |
+| `--phone <phone>`       | Phone with area code, 10-11 digits (required)  |
+| `--person-type <type>`  | `fisica` or `juridica` (required)              |
+| `--zip-code <cep>` etc. | Address fields (all optional)                  |
+
+---
+
+### `garu customers` — other subcommands
+
+| Command                                    | Description                                                      |
+| ------------------------------------------ | ---------------------------------------------------------------- |
+| `list [--page --limit --search --status]`  | List customers (`--status overdue` filters to at-risk customers) |
+| `get <uuid>`                               | Fetch a single customer                                          |
+| `update <uuid> [...]`                      | Partial update — same flags as `create`, all optional            |
+| `set-billing-email <uuid> --email <email>` | Set the sticky per-seller billing-email override                 |
+| `clear-billing-email <uuid>`               | Clear the override, falling back to the last-used email          |
+| `delete <uuid>`                            | Unlink the customer from the current seller                      |
+
+---
+
 ### `garu doctor`
 
 Run environment diagnostics. Verifies your CLI version, API connectivity, credentials, and detects AI agent integrations.

package/dist/index.cjs

@@ -15,7 +15,7 @@ var pc__default = /*#__PURE__*/_interopDefault(pc);
 // src/index.ts
 
 // src/version.ts
-var CLI_VERSION = "0.9.0";
+var CLI_VERSION = "0.11.0";
 var CliError = class extends Error {
   code;
   exitCode;
@@ -251,6 +251,13 @@ function parsePaymentMethod(raw) {
 function toChargePaymentMethod(type) {
   return type === "credit_card" ? "creditCard" : type;
 }
+function parsePersonType(raw) {
+  if (raw === "fisica" || raw === "juridica") return raw;
+  throw new CliError(
+    "invalid_input",
+    `--person-type must be 'fisica' or 'juridica' (got '${raw}')`
+  );
+}
 function parseChargePaymentMethodFilter(raw) {
   return toChargePaymentMethod(parsePaymentMethod(raw));
 }
@@ -523,6 +530,108 @@ function prettyCharge(charge) {
     lines.push(`  refund:       ${charge.refund.amount} (${charge.refund.reason ?? "no reason"})`);
   return lines.join("\n");
 }
+
+// src/commands/customers.ts
+async function getClient2(opts) {
+  if (opts.garu) return opts.garu;
+  const auth = await resolveAuth({
+    ...opts.apiKey !== void 0 ? { apiKey: opts.apiKey } : {},
+    ...opts.profile !== void 0 ? { profile: opts.profile } : {}
+  });
+  return createGaruClient({
+    auth,
+    ...opts.baseUrl !== void 0 ? { baseUrl: opts.baseUrl } : {}
+  });
+}
+async function customersCreateCommand(opts) {
+  const garu = await getClient2(opts);
+  const params = {
+    name: opts.name,
+    email: opts.email,
+    document: opts.document,
+    phone: opts.phone,
+    personType: opts.personType
+  };
+  if (opts.zipCode !== void 0) params.zipCode = opts.zipCode;
+  if (opts.street !== void 0) params.street = opts.street;
+  if (opts.number !== void 0) params.number = opts.number;
+  if (opts.complement !== void 0) params.complement = opts.complement;
+  if (opts.neighborhood !== void 0) params.neighborhood = opts.neighborhood;
+  if (opts.city !== void 0) params.city = opts.city;
+  if (opts.state !== void 0) params.state = opts.state;
+  const customer = await garu.customers.create(params);
+  printResult(customer, { ...opts, prettyPrint: prettyCustomer });
+  return customer;
+}
+async function customersListCommand(opts) {
+  const garu = await getClient2(opts);
+  const params = {};
+  if (opts.page !== void 0) params.page = opts.page;
+  if (opts.limit !== void 0) params.limit = opts.limit;
+  if (opts.search !== void 0) params.search = opts.search;
+  if (opts.status !== void 0) params.status = opts.status;
+  const result = await garu.customers.list(params);
+  printResult(result, { ...opts, prettyPrint: prettyCustomerList });
+  return result;
+}
+async function customersGetCommand(opts) {
+  const garu = await getClient2(opts);
+  const customer = await garu.customers.get(opts.uuid);
+  printResult(customer, { ...opts, prettyPrint: prettyCustomer });
+  return customer;
+}
+async function customersUpdateCommand(opts) {
+  const garu = await getClient2(opts);
+  const params = {};
+  if (opts.name !== void 0) params.name = opts.name;
+  if (opts.email !== void 0) params.email = opts.email;
+  if (opts.phone !== void 0) params.phone = opts.phone;
+  if (opts.document !== void 0) params.document = opts.document;
+  if (opts.personType !== void 0) params.personType = opts.personType;
+  if (opts.zipCode !== void 0) params.zipCode = opts.zipCode;
+  if (opts.street !== void 0) params.street = opts.street;
+  if (opts.number !== void 0) params.number = opts.number;
+  if (opts.complement !== void 0) params.complement = opts.complement;
+  if (opts.neighborhood !== void 0) params.neighborhood = opts.neighborhood;
+  if (opts.city !== void 0) params.city = opts.city;
+  if (opts.state !== void 0) params.state = opts.state;
+  const customer = await garu.customers.update(opts.uuid, params);
+  printResult(customer, { ...opts, prettyPrint: prettyCustomer });
+  return customer;
+}
+async function customersSetBillingEmailOverrideCommand(opts) {
+  const garu = await getClient2(opts);
+  const params = {
+    billingEmailOverride: opts.billingEmailOverride
+  };
+  const customer = await garu.customers.setBillingEmailOverride(opts.uuid, params);
+  printResult(customer, { ...opts, prettyPrint: prettyCustomer });
+  return customer;
+}
+async function customersDeleteCommand(opts) {
+  const garu = await getClient2(opts);
+  const result = await garu.customers.delete(opts.uuid);
+  printResult(result, { ...opts });
+  return result;
+}
+function prettyCustomerList(list) {
+  if (list.data.length === 0) return "No customers found";
+  const header = `Customers (${list.count} of ${list.totalCount} total, ${list.totalPages} page(s))`;
+  const rows = list.data.map((c) => `  ${c.uuid}  ${c.name.padEnd(30)}  ${c.email}`);
+  return [header, ...rows].join("\n");
+}
+function prettyCustomer(c) {
+  const lines = [
+    `Customer ${c.uuid}`,
+    `  name:         ${c.name}`,
+    `  email:        ${c.email}`,
+    `  phone:        ${c.phone}`,
+    `  document:     ${c.document}`,
+    `  personType:   ${c.personType}`,
+    `  billingEmail: ${c.billingEmail}${c.hasBillingEmailOverride ? " (override)" : ""}`
+  ];
+  return lines.join("\n");
+}
 async function doctorCommand(opts = {}) {
   const home = opts.home ?? os.homedir();
   const cwd = opts.cwd ?? process.cwd();
@@ -617,7 +726,7 @@ function prettyDoctor(r) {
 }
 
 // src/commands/installment-plans.ts
-async function getClient2(opts) {
+async function getClient3(opts) {
   if (opts.garu) return opts.garu;
   const auth = await resolveAuth({
     ...opts.apiKey !== void 0 ? { apiKey: opts.apiKey } : {},
@@ -629,7 +738,7 @@ async function getClient2(opts) {
   });
 }
 async function installmentPlansCreateCommand(opts) {
-  const garu = await getClient2(opts);
+  const garu = await getClient3(opts);
   const params = {
     productId: opts.productId,
     customerId: opts.customerId,
@@ -643,7 +752,7 @@ async function installmentPlansCreateCommand(opts) {
   return plan;
 }
 async function installmentPlansListCommand(opts) {
-  const garu = await getClient2(opts);
+  const garu = await getClient3(opts);
   const params = {};
   if (opts.page !== void 0) params.page = opts.page;
   if (opts.limit !== void 0) params.limit = opts.limit;
@@ -659,19 +768,19 @@ async function installmentPlansListCommand(opts) {
   return result;
 }
 async function installmentPlansGetCommand(opts) {
-  const garu = await getClient2(opts);
+  const garu = await getClient3(opts);
   const plan = await garu.installmentPlans.get(opts.uuid);
   printResult(plan, { ...opts, prettyPrint: prettyInstallmentPlanDetail });
   return plan;
 }
 async function installmentPlansReissueCommand(opts) {
-  const garu = await getClient2(opts);
+  const garu = await getClient3(opts);
   const result = await garu.installmentPlans.reissueInstallment(opts.uuid, opts.number);
   printResult(result, { ...opts, prettyPrint: prettyReissueResult });
   return result;
 }
 async function installmentPlansPostponeCommand(opts) {
-  const garu = await getClient2(opts);
+  const garu = await getClient3(opts);
   const params = { newDueDate: opts.newDueDate };
   const installment = await garu.installmentPlans.postponeInstallment(
     opts.uuid,
@@ -682,13 +791,13 @@ async function installmentPlansPostponeCommand(opts) {
   return installment;
 }
 async function installmentPlansMarkPaidCommand(opts) {
-  const garu = await getClient2(opts);
+  const garu = await getClient3(opts);
   const installment = await garu.installmentPlans.markInstallmentPaid(opts.uuid, opts.number);
   printResult(installment, { ...opts, prettyPrint: prettyInstallment });
   return installment;
 }
 async function installmentPlansCancelCommand(opts) {
-  const garu = await getClient2(opts);
+  const garu = await getClient3(opts);
   const params = {};
   if (opts.note !== void 0) params.note = opts.note;
   const plan = await garu.installmentPlans.cancel(opts.uuid, params);
@@ -696,7 +805,7 @@ async function installmentPlansCancelCommand(opts) {
   return plan;
 }
 async function installmentPlansRequestRefundCommand(opts) {
-  const garu = await getClient2(opts);
+  const garu = await getClient3(opts);
   const params = {};
   if (opts.amount !== void 0) params.amount = opts.amount;
   if (opts.reason !== void 0) params.reason = opts.reason;
@@ -808,7 +917,7 @@ async function logoutCommand(opts = {}) {
 }
 
 // src/commands/products.ts
-async function getClient3(opts) {
+async function getClient4(opts) {
   if (opts.garu) return opts.garu;
   const auth = await resolveAuth({
     ...opts.apiKey !== void 0 ? { apiKey: opts.apiKey } : {},
@@ -839,7 +948,7 @@ function buildProductBody(opts) {
   return body;
 }
 async function productsCreateCommand(opts) {
-  const garu = await getClient3(opts);
+  const garu = await getClient4(opts);
   const params = { ...buildProductBody(opts), name: opts.name };
   const product = await garu.products.create(params);
   printSuccess(`Created product ${product.uuid ?? product.id}`, opts);
@@ -851,7 +960,7 @@ async function productsUpdateCommand(opts) {
   if (Object.keys(body).length === 0) {
     throw new CliError("invalid_input", "Nothing to update \u2014 pass at least one field to change.");
   }
-  const garu = await getClient3(opts);
+  const garu = await getClient4(opts);
   const product = await garu.products.update(opts.id, body);
   printSuccess(`Updated product ${product.uuid ?? product.id}`, opts);
   printResult(product, { ...opts, prettyPrint: prettyProduct });
@@ -875,7 +984,7 @@ function prettyProduct(p) {
 }
 
 // src/commands/refund-requests.ts
-async function getClient4(opts) {
+async function getClient5(opts) {
   if (opts.garu) return opts.garu;
   const auth = await resolveAuth({
     ...opts.apiKey !== void 0 ? { apiKey: opts.apiKey } : {},
@@ -887,7 +996,7 @@ async function getClient4(opts) {
   });
 }
 async function refundRequestsListCommand(opts) {
-  const garu = await getClient4(opts);
+  const garu = await getClient5(opts);
   const params = {};
   if (opts.page !== void 0) params.page = opts.page;
   if (opts.limit !== void 0) params.limit = opts.limit;
@@ -901,13 +1010,13 @@ async function refundRequestsListCommand(opts) {
   return result;
 }
 async function refundRequestsGetCommand(opts) {
-  const garu = await getClient4(opts);
+  const garu = await getClient5(opts);
   const request = await garu.refundRequests.get(opts.uuid);
   printResult(request, { ...opts, prettyPrint: prettyRefundRequest2 });
   return request;
 }
 async function refundRequestsConfirmCommand(opts) {
-  const garu = await getClient4(opts);
+  const garu = await getClient5(opts);
   const params = {};
   if (opts.note !== void 0) params.note = opts.note;
   const request = await garu.refundRequests.confirm(opts.uuid, params);
@@ -915,7 +1024,7 @@ async function refundRequestsConfirmCommand(opts) {
   return request;
 }
 async function refundRequestsRejectCommand(opts) {
-  const garu = await getClient4(opts);
+  const garu = await getClient5(opts);
   const params = {};
   if (opts.note !== void 0) params.note = opts.note;
   const request = await garu.refundRequests.reject(opts.uuid, params);
@@ -941,7 +1050,7 @@ function prettyRefundRequest2(r) {
 }
 
 // src/commands/scheduled-charges.ts
-async function getClient5(opts) {
+async function getClient6(opts) {
   if (opts.garu) return opts.garu;
   const auth = await resolveAuth({
     ...opts.apiKey !== void 0 ? { apiKey: opts.apiKey } : {},
@@ -978,7 +1087,7 @@ function assertPixAutomaticRequirements(opts) {
 }
 async function scheduledChargesCreateCommand(opts) {
   assertPixAutomaticRequirements(opts);
-  const garu = await getClient5(opts);
+  const garu = await getClient6(opts);
   const params = {
     customerId: opts.customerId,
     amount: opts.amount,
@@ -1000,7 +1109,7 @@ async function scheduledChargesCreateCommand(opts) {
   return charge;
 }
 async function scheduledChargesListCommand(opts) {
-  const garu = await getClient5(opts);
+  const garu = await getClient6(opts);
   const params = {};
   if (opts.page !== void 0) params.page = opts.page;
   if (opts.limit !== void 0) params.limit = opts.limit;
@@ -1017,13 +1126,13 @@ async function scheduledChargesListCommand(opts) {
   return result;
 }
 async function scheduledChargesGetCommand(opts) {
-  const garu = await getClient5(opts);
+  const garu = await getClient6(opts);
   const detail = await garu.scheduledCharges.get(opts.id);
   printResult(detail, { ...opts, prettyPrint: prettyScheduledChargeDetail });
   return detail;
 }
 async function scheduledChargesPostponeCommand(opts) {
-  const garu = await getClient5(opts);
+  const garu = await getClient6(opts);
   const params = { newDueDate: opts.newDueDate };
   if (opts.reason !== void 0) params.reason = opts.reason;
   const charge = await garu.scheduledCharges.postpone(opts.id, params);
@@ -1031,7 +1140,7 @@ async function scheduledChargesPostponeCommand(opts) {
   return charge;
 }
 async function scheduledChargesPauseCommand(opts) {
-  const garu = await getClient5(opts);
+  const garu = await getClient6(opts);
   const params = {};
   if (opts.reason !== void 0) params.reason = opts.reason;
   const charge = await garu.scheduledCharges.pause(opts.id, params);
@@ -1039,13 +1148,13 @@ async function scheduledChargesPauseCommand(opts) {
   return charge;
 }
 async function scheduledChargesResumeCommand(opts) {
-  const garu = await getClient5(opts);
+  const garu = await getClient6(opts);
   const charge = await garu.scheduledCharges.resume(opts.id);
   printResult(charge, { ...opts, prettyPrint: prettyScheduledCharge });
   return charge;
 }
 async function scheduledChargesMarkPaidCommand(opts) {
-  const garu = await getClient5(opts);
+  const garu = await getClient6(opts);
   const params = { paymentDate: opts.paymentDate };
   if (opts.externalReference !== void 0) params.externalReference = opts.externalReference;
   if (opts.cycleNumber !== void 0) params.cycleNumber = opts.cycleNumber;
@@ -1054,7 +1163,7 @@ async function scheduledChargesMarkPaidCommand(opts) {
   return charge;
 }
 async function scheduledChargesCancelRecurrenceCommand(opts) {
-  const garu = await getClient5(opts);
+  const garu = await getClient6(opts);
   const params = {};
   if (opts.reason !== void 0) params.reason = opts.reason;
   const charge = await garu.scheduledCharges.cancelRecurrence(opts.id, params);
@@ -1062,14 +1171,14 @@ async function scheduledChargesCancelRecurrenceCommand(opts) {
   return charge;
 }
 async function scheduledChargesCancelAtPeriodEndCommand(opts) {
-  const garu = await getClient5(opts);
+  const garu = await getClient6(opts);
   const params = { enabled: opts.enabled };
   const charge = await garu.scheduledCharges.setCancelAtPeriodEnd(opts.id, params);
   printResult(charge, { ...opts, prettyPrint: prettyScheduledCharge });
   return charge;
 }
 async function scheduledChargesChangePaymentMethodCommand(opts) {
-  const garu = await getClient5(opts);
+  const garu = await getClient6(opts);
   const params = {
     paymentMethodId: opts.paymentMethodId
   };
@@ -1078,13 +1187,13 @@ async function scheduledChargesChangePaymentMethodCommand(opts) {
   return charge;
 }
 async function scheduledChargesClearPaymentMethodCommand(opts) {
-  const garu = await getClient5(opts);
+  const garu = await getClient6(opts);
   const charge = await garu.scheduledCharges.clearPaymentMethod(opts.id);
   printResult(charge, { ...opts, prettyPrint: prettyScheduledCharge });
   return charge;
 }
 async function scheduledChargesAttemptsCommand(opts) {
-  const garu = await getClient5(opts);
+  const garu = await getClient6(opts);
   const params = {};
   if (opts.page !== void 0) params.page = opts.page;
   if (opts.limit !== void 0) params.limit = opts.limit;
@@ -1094,7 +1203,7 @@ async function scheduledChargesAttemptsCommand(opts) {
   return result;
 }
 async function scheduledChargesChargeNowCommand(opts) {
-  const garu = await getClient5(opts);
+  const garu = await getClient6(opts);
   const result = await garu.scheduledCharges.chargeNow(opts.id);
   printResult(result, { ...opts, prettyPrint: prettyChargeNow });
   if (result.outcome === "failed" || result.outcome === "not_sent") {
@@ -1158,7 +1267,7 @@ function prettyChargeNow(result) {
   if (result.reason) lines.push(`  reason:  ${result.reason}`);
   return lines.join("\n");
 }
-async function getClient6(opts) {
+async function getClient7(opts) {
   if (opts.garu) return opts.garu;
   const auth = await resolveAuth({
     ...opts.apiKey !== void 0 ? { apiKey: opts.apiKey } : {},
@@ -1170,7 +1279,7 @@ async function getClient6(opts) {
   });
 }
 async function webhooksEventsListCommand(opts) {
-  const garu = await getClient6(opts);
+  const garu = await getClient7(opts);
   const params = {};
   if (opts.page !== void 0) params.page = opts.page;
   if (opts.limit !== void 0) params.limit = opts.limit;
@@ -1182,21 +1291,21 @@ async function webhooksEventsListCommand(opts) {
   return result;
 }
 async function webhooksEventsGetCommand(opts) {
-  const garu = await getClient6(opts);
-  const event = await garu.webhookEvents.get(opts.id);
+  const garu = await getClient7(opts);
+  const event = await garu.webhookEvents.get(opts.uuid);
   printResult(event, { ...opts, prettyPrint: prettyWebhookEvent });
   return event;
 }
 async function webhooksEventsRetryCommand(opts) {
-  const garu = await getClient6(opts);
-  const event = await garu.webhookEvents.retry(opts.id);
+  const garu = await getClient7(opts);
+  const event = await garu.webhookEvents.retry(opts.uuid);
   printResult(event, { ...opts, prettyPrint: prettyWebhookEvent });
   return event;
 }
 async function webhooksEventsResendCommand(opts) {
-  const garu = await getClient6(opts);
-  const clone = await garu.webhookEvents.resend(opts.id);
-  printSuccess(`Resent event ${opts.id} \u2192 new event ${clone.id}`, opts);
+  const garu = await getClient7(opts);
+  const clone = await garu.webhookEvents.resend(opts.uuid);
+  printSuccess(`Resent event ${opts.uuid} \u2192 new event ${clone.uuid}`, opts);
   printResult(clone, { ...opts, prettyPrint: prettyWebhookEvent });
   return clone;
 }
@@ -1207,18 +1316,16 @@ function statusBadge(status) {
   return pc__default.default.yellow(padded);
 }
 function prettyWebhookEventList(list) {
-  if (list.data.length === 0) {
-    return `No webhook events found (page ${list.meta.page}/${list.meta.totalPages || 1})`;
-  }
-  const header = `Webhook events (page ${list.meta.page}/${list.meta.totalPages || "?"}, ${list.meta.total} total)`;
+  if (list.data.length === 0) return "No webhook events found";
+  const header = `Webhook events (${list.count} of ${list.totalCount} total, ${list.totalPages} page(s))`;
   const rows = list.data.map(
-    (e) => `  ${String(e.id).padStart(8)}  ${statusBadge(e.status)}  attempts=${String(e.attempts).padStart(2)}  ${e.eventType.padEnd(38)}  ${e.createdAt}`
+    (e) => `  ${e.uuid}  ${statusBadge(e.status)}  attempts=${String(e.attempts).padStart(2)}  ${e.eventType.padEnd(38)}  ${e.createdAt}`
   );
   return [header, ...rows].join("\n");
 }
 function prettyWebhookEvent(event) {
   const lines = [
-    `Webhook event ${event.id}`,
+    `Webhook event ${event.uuid}`,
     `  status:        ${statusBadge(event.status)}`,
     `  eventType:     ${event.eventType}`,
     `  attempts:      ${event.attempts}`,
@@ -1530,31 +1637,105 @@ Recipes:
       }).catch((err) => printErrorAndExit(err, base));
     }
   );
-  events.command("get <id>").description("Fetch a single webhook event by ID").action(async (id) => {
+  events.command("get <uuid>").description("Fetch a single webhook event by uuid").action(async (uuid) => {
+    const base = toCommandOptions(program);
+    await webhooksEventsGetCommand({ ...base, uuid }).catch(
+      (err) => printErrorAndExit(err, base)
+    );
+  });
+  events.command("retry <uuid>").description(
+    "[deprecated: prefer `resend`] Re-deliver a webhook event in place (resets the original row to pending and triggers an immediate attempt; destroys the prior failure record)"
+  ).action(async (uuid) => {
+    const base = toCommandOptions(program);
+    await webhooksEventsRetryCommand({ ...base, uuid }).catch(
+      (err) => printErrorAndExit(err, base)
+    );
+  });
+  events.command("resend <uuid>").description(
+    "Re-deliver a webhook event by cloning it (audit-trail preserving: original row is untouched, clone gets a new uuid and points back via manualResendOf)"
+  ).action(async (uuid) => {
+    const base = toCommandOptions(program);
+    await webhooksEventsResendCommand({ ...base, uuid }).catch(
+      (err) => printErrorAndExit(err, base)
+    );
+  });
+  const customers = program.command("customers").description("Manage your customer base");
+  customers.command("create").description("Register a customer for the current seller (dedup by document)").requiredOption("--name <name>", "customer name").requiredOption("--email <email>", "customer email").requiredOption("--document <document>", "CPF (11 digits) or CNPJ (14 digits), digits only").requiredOption("--phone <phone>", "phone with area code, 10-11 digits").requiredOption("--person-type <type>", "'fisica' or 'juridica'").option("--zip-code <cep>", "ZIP code, 8 digits").option("--street <street>", "street address").option("--number <number>", "address number").option("--complement <text>", "address complement").option("--neighborhood <text>", "neighborhood").option("--city <city>", "city").option("--state <uf>", "2-letter state code, e.g. SP").action(async (cmdOpts) => {
+    const base = toCommandOptions(program);
+    await customersCreateCommand({
+      ...base,
+      name: cmdOpts.name,
+      email: cmdOpts.email,
+      document: cmdOpts.document,
+      phone: cmdOpts.phone,
+      personType: parsePersonType(cmdOpts.personType),
+      zipCode: cmdOpts.zipCode,
+      street: cmdOpts.street,
+      number: cmdOpts.number,
+      complement: cmdOpts.complement,
+      neighborhood: cmdOpts.neighborhood,
+      city: cmdOpts.city,
+      state: cmdOpts.state
+    }).catch((err) => printErrorAndExit(err, base));
+  });
+  customers.command("list").description("List customers with pagination and search").option("--page <n>", "page number (1-based)", (v) => parseInt(v, 10)).option("--limit <n>", "items per page (1-100)", (v) => parseInt(v, 10)).option("--search <query>", "search by name, email, or document").option(
+    "--status <status>",
+    "'overdue' returns customers with at least one overdue scheduled charge"
+  ).action(
+    async (cmdOpts) => {
+      const base = toCommandOptions(program);
+      await customersListCommand({
+        ...base,
+        page: cmdOpts.page,
+        limit: cmdOpts.limit,
+        search: cmdOpts.search,
+        status: cmdOpts.status === "overdue" ? "overdue" : void 0
+      }).catch((err) => printErrorAndExit(err, base));
+    }
+  );
+  customers.command("get <uuid>").description("Fetch a single customer by uuid").action(async (uuid) => {
+    const base = toCommandOptions(program);
+    await customersGetCommand({ ...base, uuid }).catch((err) => printErrorAndExit(err, base));
+  });
+  customers.command("update <uuid>").description("Partially update a customer (only the flags you pass change)").option("--name <name>", "customer name").option("--email <email>", "customer email").option("--phone <phone>", "phone with area code, 10-11 digits").option("--document <document>", "CPF (11 digits) or CNPJ (14 digits), digits only").option("--person-type <type>", "'fisica' or 'juridica'").option("--zip-code <cep>", "ZIP code, 8 digits").option("--street <street>", "street address").option("--number <number>", "address number").option("--complement <text>", "address complement").option("--neighborhood <text>", "neighborhood").option("--city <city>", "city").option("--state <uf>", "2-letter state code, e.g. SP").action(async (uuid, cmdOpts) => {
     const base = toCommandOptions(program);
-    await webhooksEventsGetCommand({
+    await customersUpdateCommand({
       ...base,
-      id: parsePositiveIntId(id, "Webhook event ID")
+      uuid,
+      name: cmdOpts.name,
+      email: cmdOpts.email,
+      phone: cmdOpts.phone,
+      document: cmdOpts.document,
+      personType: cmdOpts.personType ? parsePersonType(cmdOpts.personType) : void 0,
+      zipCode: cmdOpts.zipCode,
+      street: cmdOpts.street,
+      number: cmdOpts.number,
+      complement: cmdOpts.complement,
+      neighborhood: cmdOpts.neighborhood,
+      city: cmdOpts.city,
+      state: cmdOpts.state
     }).catch((err) => printErrorAndExit(err, base));
   });
-  events.command("retry <id>").description(
-    "[deprecated: prefer `resend`] Re-deliver a webhook event in place (resets the original row to pending and triggers an immediate attempt; destroys the prior failure record)"
-  ).action(async (id) => {
+  customers.command("set-billing-email <uuid>").description("Set the sticky per-seller billing-email override").requiredOption("--email <email>", "the billing email to set").action(async (uuid, cmdOpts) => {
     const base = toCommandOptions(program);
-    await webhooksEventsRetryCommand({
+    await customersSetBillingEmailOverrideCommand({
       ...base,
-      id: parsePositiveIntId(id, "Webhook event ID")
+      uuid,
+      billingEmailOverride: cmdOpts.email
     }).catch((err) => printErrorAndExit(err, base));
   });
-  events.command("resend <id>").description(
-    "Re-deliver a webhook event by cloning it (audit-trail preserving: original row is untouched, clone gets a new id and points back via manualResendOf)"
-  ).action(async (id) => {
+  customers.command("clear-billing-email <uuid>").description("Clear the billing-email override, falling back to the last-used email").action(async (uuid) => {
     const base = toCommandOptions(program);
-    await webhooksEventsResendCommand({
+    await customersSetBillingEmailOverrideCommand({
       ...base,
-      id: parsePositiveIntId(id, "Webhook event ID")
+      uuid,
+      billingEmailOverride: null
     }).catch((err) => printErrorAndExit(err, base));
   });
+  customers.command("delete <uuid>").description("Remove a customer from the current seller (unlinks your profile only)").action(async (uuid) => {
+    const base = toCommandOptions(program);
+    await customersDeleteCommand({ ...base, uuid }).catch((err) => printErrorAndExit(err, base));
+  });
   const installmentPlans = program.command("installment-plans").description("Sell a product as boleto parcelado (carn\xEA) and manage its installments");
   installmentPlans.command("create").description("Sell a product as a carn\xEA (installments of boleto slips)").requiredOption("--product-id <uuid>", "product uuid (must have boleto parcelado enabled)").requiredOption(
     "--customer-id <n>",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@garuhq/cli",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "description": "Official command-line interface for the Garu payment gateway.",
   "license": "MIT",
   "homepage": "https://garu.com.br",
@@ -46,7 +46,7 @@
     "prepublishOnly": "npm run check:version-sync && npm run typecheck && npm test && npm run build"
   },
   "dependencies": {
-    "@garuhq/node": "1.1.0",
+    "@garuhq/node": "3.0.0",
     "@inquirer/prompts": "8.4.1",
     "commander": "12.0.0",
     "picocolors": "1.0.0",