@sentroy-co/client-sdk 2.13.9 → 2.15.0

package/src/cli/args.ts

@@ -0,0 +1,225 @@
+/**
+ * Shared CLI utilities — flag parser, ANSI helpers, auth resolver, HTTP
+ * client, fail/info/ok/warn loggers. Reused by every subcommand
+ * (env, mail, storage, ai).
+ *
+ * `env.ts` historically inlined these; new subcommands import them from
+ * here to stay DRY and to allow extending `VALUE_FLAGS` in one place.
+ */
+
+export interface ParsedArgs {
+  positional: string[]
+  flags: Record<string, string | boolean>
+}
+
+export interface SharedOpts {
+  token: string
+  baseUrl: string
+  /** Company slug — mail/storage commands need it; env doesn't (token is
+   *  vault-scoped). Resolved from --company-slug, $SENTROY_COMPANY_SLUG,
+   *  or thrown error. */
+  companySlug?: string
+}
+
+// ── ANSI helpers (no deps) ──────────────────────────────────────────────
+// Honor https://no-color.org and FORCE_COLOR override before falling back
+// to TTY detection. Captured at module load — wrappers/tests that need to
+// override should set the env var before requiring this module.
+const supportsColor = (() => {
+  if (typeof process === "undefined") return false
+  if (process.env.NO_COLOR) return false
+  if (process.env.FORCE_COLOR) return process.env.FORCE_COLOR !== "0"
+  return Boolean(process.stdout?.isTTY) && process.env.TERM !== "dumb"
+})()
+
+export const c = {
+  bold: (s: string) => (supportsColor ? `\x1b[1m${s}\x1b[0m` : s),
+  dim: (s: string) => (supportsColor ? `\x1b[2m${s}\x1b[0m` : s),
+  red: (s: string) => (supportsColor ? `\x1b[31m${s}\x1b[0m` : s),
+  green: (s: string) => (supportsColor ? `\x1b[32m${s}\x1b[0m` : s),
+  yellow: (s: string) => (supportsColor ? `\x1b[33m${s}\x1b[0m` : s),
+  cyan: (s: string) => (supportsColor ? `\x1b[36m${s}\x1b[0m` : s),
+  magenta: (s: string) => (supportsColor ? `\x1b[35m${s}\x1b[0m` : s),
+}
+
+export function fail(msg: string): never {
+  process.stderr.write(`${c.red("✗")} ${msg}\n`)
+  process.exit(1)
+}
+
+export function info(msg: string): void {
+  process.stdout.write(`${c.cyan("→")} ${msg}\n`)
+}
+
+export function ok(msg: string): void {
+  process.stdout.write(`${c.green("✓")} ${msg}\n`)
+}
+
+export function warn(msg: string): void {
+  process.stdout.write(`${c.yellow("⚠")} ${msg}\n`)
+}
+
+/**
+ * Flags that take a value as a separate token (`--flag value`). All other
+ * `--flag` tokens are booleans. The `--flag=value` form always works
+ * regardless of this list.
+ */
+const VALUE_FLAGS = new Set([
+  "token",
+  "url",
+  "company-slug",
+  "output",
+  "page",
+  "limit",
+  "skip",
+  "mailbox",
+  "folder",
+  "q",
+  "domain",
+  "reason",
+  "status",
+  "from",
+  "to",
+  "days",
+  "type",
+  "sort",
+  "dir",
+  "out",
+  "source",
+  "pin",
+])
+
+export function parseFlags(args: string[]): ParsedArgs {
+  const positional: string[] = []
+  const flags: Record<string, string | boolean> = {}
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i]!
+    if (!a.startsWith("--")) {
+      positional.push(a)
+      continue
+    }
+    const body = a.slice(2)
+    const eq = body.indexOf("=")
+    if (eq >= 0) {
+      flags[body.slice(0, eq)] = body.slice(eq + 1)
+      continue
+    }
+    if (VALUE_FLAGS.has(body)) {
+      const next = args[i + 1]
+      if (next === undefined || next.startsWith("--")) {
+        fail(
+          `flag --${body} requires a value (use --${body}=value or --${body} value)`,
+        )
+      }
+      flags[body] = next
+      i++
+    } else {
+      flags[body] = true
+    }
+  }
+  return { positional, flags }
+}
+
+/**
+ * Resolve shared opts for general (non-vault) Sentroy CLI commands.
+ *
+ * Token resolution priority:
+ *   1. --token=stk_... flag
+ *   2. SENTROY_API_KEY env var
+ *   3. SENTROY_ENV_API_KEY env var (back-compat — same token namespace works)
+ *
+ * Base URL priority:
+ *   1. --url=https://... flag
+ *   2. SENTROY_API_URL env var
+ *   3. SENTROY_ENV_API_URL env var
+ *   4. https://sentroy.com
+ *
+ * Company slug priority (REQUIRED for mail/storage):
+ *   1. --company-slug=<slug> flag
+ *   2. SENTROY_COMPANY_SLUG env var
+ */
+export function resolveSharedOpts(
+  flags: Record<string, string | boolean>,
+  opts: { requireCompanySlug?: boolean } = {},
+): SharedOpts {
+  const token =
+    (typeof flags.token === "string" ? flags.token : null) ??
+    process.env.SENTROY_API_KEY ??
+    process.env.SENTROY_ENV_API_KEY ??
+    null
+  if (!token) {
+    fail(
+      "no token. Pass --token=stk_... or set SENTROY_API_KEY (or SENTROY_ENV_API_KEY for vault) in your environment.",
+    )
+  }
+  const baseUrl = (
+    (typeof flags.url === "string" ? flags.url : null) ??
+    process.env.SENTROY_API_URL ??
+    process.env.SENTROY_ENV_API_URL ??
+    "https://sentroy.com"
+  ).replace(/\/+$/, "")
+
+  const companySlug =
+    (typeof flags["company-slug"] === "string"
+      ? (flags["company-slug"] as string)
+      : null) ??
+    process.env.SENTROY_COMPANY_SLUG ??
+    undefined
+  if (opts.requireCompanySlug && !companySlug) {
+    fail(
+      "no company slug. Pass --company-slug=<slug> or set SENTROY_COMPANY_SLUG in your environment.",
+    )
+  }
+  return { token, baseUrl, companySlug }
+}
+
+/**
+ * Thin fetch wrapper used by all subcommands that hit the Sentroy REST
+ * API. Strips trailing slashes from baseUrl, adds Bearer auth, unwraps
+ * `{success, data}` envelope, raises on non-2xx with a useful message.
+ */
+export async function apiFetch<T = unknown>(
+  shared: SharedOpts,
+  path: string,
+  init?: RequestInit,
+): Promise<T> {
+  const res = await fetch(`${shared.baseUrl}${path}`, {
+    ...init,
+    headers: {
+      Authorization: `Bearer ${shared.token}`,
+      ...(init?.body ? { "Content-Type": "application/json" } : {}),
+      ...(init?.headers ?? {}),
+    },
+  })
+  const text = await res.text()
+  let body: unknown
+  try {
+    body = text ? JSON.parse(text) : null
+  } catch {
+    body = text
+  }
+  if (!res.ok) {
+    // Sentroy returns different envelopes depending on handler; try the
+    // common shapes in priority order before falling back to HTTP status.
+    let errMsg = `HTTP ${res.status} ${res.statusText}`.trim()
+    if (body && typeof body === "object") {
+      const b = body as Record<string, unknown>
+      if (typeof b.error === "string") errMsg = b.error
+      else if (typeof b.message === "string") errMsg = b.message
+      else if (
+        b.error &&
+        typeof b.error === "object" &&
+        typeof (b.error as Record<string, unknown>).message === "string"
+      ) {
+        errMsg = (b.error as Record<string, string>).message
+      }
+    }
+    throw new Error(`${path}: ${errMsg}`)
+  }
+  // Envelope: {success: true, data: T} (most endpoints) or raw {data: T}.
+  // Some return body directly without envelope; fall back to body.
+  if (body && typeof body === "object" && "data" in body) {
+    return (body as { data: T }).data
+  }
+  return body as T
+}

package/src/cli/env.ts

@@ -283,6 +283,7 @@ export async function cmdPull(args: string[]): Promise<void> {
   const { positional, flags } = parseFlags(args)
   const file = positional[0] ?? DEFAULT_FILE
   const force = !!flags.force
+  const publicOnly = !!flags["public-only"]
   const shared = resolveSharedOpts(flags)
 
   const target = path.resolve(process.cwd(), file)
@@ -291,7 +292,12 @@ export async function cmdPull(args: string[]): Promise<void> {
   }
 
   info(`fetching from ${shared.baseUrl}…`)
-  const remote = await http<FetchResponse>(shared, "/api/env-vault/fetch")
+  // Browser-safe subset (public-only) hits a dedicated endpoint that
+  // strips secrets — useful for `.env.public` files committed to repos.
+  const endpoint = publicOnly
+    ? "/api/env-vault/public"
+    : "/api/env-vault/fetch"
+  const remote = await http<FetchResponse>(shared, endpoint)
   const entries: DotenvEntry[] = remote.variables.map((v) => ({
     key: v.key,
     value: v.value,
@@ -301,7 +307,9 @@ export async function cmdPull(args: string[]): Promise<void> {
   const text = serializeDotenv(entries)
   fs.writeFileSync(target, text, "utf8")
   ok(
-    `wrote ${entries.length} variable(s) to ${file} (${remote.project}/${remote.environment})`,
+    `wrote ${entries.length} variable(s) to ${file} (${remote.project}/${remote.environment})${
+      publicOnly ? " [public-only]" : ""
+    }`,
   )
 }
 

package/src/cli/format.ts

@@ -0,0 +1,147 @@
+/**
+ * Output formatters — table (human-friendly) + json (script/automation).
+ *
+ * CLI commands accept `--output=json|table` (default: table) and call
+ * `printRows(rows, columns, flags)`.
+ */
+
+import { c } from "./args"
+
+export interface Column<T> {
+  /** Header text shown in table mode (uppercase recommended). */
+  header: string
+  /** Value extractor; should return a primitive that .toString()'s cleanly. */
+  get: (row: T) => string | number | null | undefined
+  /** Max display width — longer values get truncated with `…`. Default 40. */
+  maxWidth?: number
+  /** Right-align numeric columns. Default false. */
+  alignRight?: boolean
+}
+
+/**
+ * Print rows as a formatted table (or JSON if --output=json).
+ *
+ * Table mode uses 2-space gap between columns, dim header line, no
+ * vertical separators (keeps copy-paste clean). Empty cells render as
+ * `c.dim("—")`.
+ */
+export function printRows<T>(
+  rows: T[],
+  columns: Column<T>[],
+  flags: Record<string, string | boolean>,
+): void {
+  const output =
+    typeof flags.output === "string" ? flags.output.toLowerCase() : "table"
+  if (output === "json") {
+    // For JSON we dump the raw row objects, not the column projection —
+    // scripts may want fields beyond what we show in the table.
+    process.stdout.write(JSON.stringify(rows, null, 2) + "\n")
+    return
+  }
+  if (rows.length === 0) {
+    process.stdout.write(c.dim("(no results)") + "\n")
+    return
+  }
+  // Compute string cells + widths
+  const cells: string[][] = rows.map((row) =>
+    columns.map((col) => {
+      const v = col.get(row)
+      if (v === null || v === undefined || v === "") return ""
+      const s = String(v)
+      const max = col.maxWidth ?? 40
+      if (s.length > max) return s.slice(0, max - 1) + "…"
+      return s
+    }),
+  )
+  const widths = columns.map((col, i) => {
+    const headerWidth = col.header.length
+    const rowMax = cells.reduce((m, r) => Math.max(m, (r[i] ?? "").length), 0)
+    return Math.max(headerWidth, rowMax)
+  })
+
+  // Header
+  const headerLine = columns
+    .map((col, i) => padCell(col.header, widths[i]!, col.alignRight ?? false))
+    .join("  ")
+  process.stdout.write(c.dim(headerLine) + "\n")
+
+  // Underline
+  const underline = widths.map((w) => "─".repeat(w)).join("  ")
+  process.stdout.write(c.dim(underline) + "\n")
+
+  // Rows
+  for (const cellRow of cells) {
+    const line = columns
+      .map((col, i) => {
+        const v = cellRow[i] ?? ""
+        const padded = padCell(v || c.dim("—"), widths[i]!, col.alignRight ?? false)
+        return padded
+      })
+      .join("  ")
+    process.stdout.write(line + "\n")
+  }
+  process.stdout.write("\n" + c.dim(`${rows.length} row${rows.length === 1 ? "" : "s"}`) + "\n")
+}
+
+function padCell(text: string, width: number, alignRight: boolean): string {
+  // ANSI escape sequences mess up String.prototype.padEnd length math;
+  // strip color codes for width calculation only.
+  const visible = text.replace(/\x1b\[[0-9;]*m/g, "")
+  const pad = " ".repeat(Math.max(0, width - visible.length))
+  return alignRight ? pad + text : text + pad
+}
+
+/**
+ * Print a single object as a key/value detail panel.
+ * Used by `<group> <resource> get <id>` commands.
+ */
+export function printDetail<T extends Record<string, unknown>>(
+  obj: T,
+  flags: Record<string, string | boolean>,
+): void {
+  const output =
+    typeof flags.output === "string" ? flags.output.toLowerCase() : "table"
+  if (output === "json") {
+    process.stdout.write(JSON.stringify(obj, null, 2) + "\n")
+    return
+  }
+  const keys = Object.keys(obj)
+  if (keys.length === 0) {
+    process.stdout.write(c.dim("(empty)") + "\n")
+    return
+  }
+  const longest = keys.reduce((m, k) => Math.max(m, k.length), 0)
+  for (const k of keys) {
+    const v = obj[k]
+    const valStr =
+      v === null || v === undefined
+        ? c.dim("—")
+        : typeof v === "object"
+          ? JSON.stringify(v)
+          : String(v)
+    process.stdout.write(`${c.dim(k.padEnd(longest))}  ${valStr}\n`)
+  }
+  process.stdout.write("\n")
+}
+
+/**
+ * Localized string helper — Sentroy mail/templates fields can be either a
+ * plain string or `Record<locale, string>` (e.g. `{tr, en}`). For table
+ * display, pick "en" fallback "tr" fallback first available, otherwise
+ * the raw string.
+ */
+export function loc(value: unknown, preferred = "en"): string {
+  if (value === null || value === undefined) return ""
+  if (typeof value === "string") return value
+  if (typeof value === "object") {
+    const obj = value as Record<string, unknown>
+    const direct = obj[preferred]
+    if (typeof direct === "string") return direct
+    const tr = obj.tr
+    if (typeof tr === "string") return tr
+    for (const k of Object.keys(obj)) {
+      if (typeof obj[k] === "string") return obj[k] as string
+    }
+  }
+  return ""
+}

package/src/cli/index.ts

@@ -1,11 +1,20 @@
 /**
  * `sentroy` — CLI entry point.
  *
- * Subcommand router with no third-party deps. Today only `env` exists;
- * future subcommands (`mail`, `media`, etc.) hook in here.
+ * Subcommand router with no third-party deps. Groups:
+ *   - env       Vault sync (push/pull/list/diff) — vault-scoped token
+ *   - mail      Mail resource queries (templates/domains/mailboxes/...)
+ *   - storage   Storage resource queries (buckets/media/usage)
+ *   - ai        AI Skill install (Claude/Cursor/Windsurf/AGENTS.md)
+ *
+ * Shared helpers live in `./args` (parseFlags, resolveSharedOpts, apiFetch,
+ * c, fail, info, ok, warn) and `./format` (printRows, printDetail, loc).
  */
 
 import { cmdPush, cmdPull, cmdList, cmdDiff } from "./env"
+import { MAIL_HANDLERS } from "./mail"
+import { STORAGE_HANDLERS } from "./storage"
+import { AI_HANDLERS } from "./ai"
 
 const VERSION = "__VERSION__" // replaced at runtime via package.json read
 
@@ -33,9 +42,41 @@ const ENV_SUBCOMMANDS: Record<string, SubCommand> = {
   },
 }
 
+// MAIL/STORAGE/AI subcommands use sub-sub-command pattern:
+//   `sentroy mail templates list` → MAIL_HANDLERS["templates.list"]
+//   `sentroy mail logs get <id>`  → MAIL_HANDLERS["logs.get"]
+//
+// Router joins argv[1] + argv[2] with "." for resource+verb lookup.
+// `sentroy mail analytics` has no verb → MAIL_HANDLERS["analytics"].
+// `sentroy ai install` has no resource → AI_HANDLERS["install"].
+
+/**
+ * Maps `mail templates list` → `templatesList`, `storage buckets get` →
+ * `bucketsGet`. If verb missing, tries plain resource key (e.g. `analytics`
+ * or `usage`). Returns the handler fn + how many argv tokens it consumed
+ * past the group (2 = resource+verb, 1 = resource only) so caller can
+ * slice the rest as args.
+ */
+function resolveHandler(
+  handlers: Record<string, (args: string[]) => Promise<void> | void>,
+  resource: string,
+  verb: string | undefined,
+): { fn: (args: string[]) => Promise<void> | void; consumed: number } | null {
+  // Flag tokens are NOT verbs (e.g. `mail analytics --days=7`).
+  const verbToken = verb && !verb.startsWith("--") ? verb : undefined
+  if (verbToken) {
+    const camel =
+      resource + verbToken.charAt(0).toUpperCase() + verbToken.slice(1)
+    const h = handlers[camel]
+    if (h) return { fn: h, consumed: 3 }
+  }
+  const direct = handlers[resource]
+  if (direct) return { fn: direct, consumed: 2 }
+  return null
+}
+
 function readPackageVersion(): string {
   if (VERSION !== "__VERSION__") return VERSION
-  // Walk up from this file: dist/cli/index.js → dist/cli → dist → package.
   try {
     // eslint-disable-next-line @typescript-eslint/no-require-imports
     const { version } = require("../../package.json") as { version: string }
@@ -50,31 +91,53 @@ function showHelp(): void {
   process.stdout.write(
     `\nsentroy ${v} — Sentroy CLI\n\n` +
       `USAGE\n` +
-      `  sentroy <command> [args] [flags]\n\n` +
-      `COMMANDS\n` +
-      `  env push  [<file>]     ${ENV_SUBCOMMANDS.push.description}\n` +
-      `  env pull  [<file>]     ${ENV_SUBCOMMANDS.pull.description}\n` +
-      `  env list               ${ENV_SUBCOMMANDS.list.description}\n` +
-      `  env diff  [<file>]     ${ENV_SUBCOMMANDS.diff.description}\n\n` +
+      `  sentroy <group> <subcommand> [args] [flags]\n\n` +
+      `ENV (vault sync — requires SENTROY_ENV_API_KEY)\n` +
+      `  sentroy env push  [<file>]              ${ENV_SUBCOMMANDS.push!.description}\n` +
+      `  sentroy env pull  [<file>]              ${ENV_SUBCOMMANDS.pull!.description}\n` +
+      `  sentroy env list                        ${ENV_SUBCOMMANDS.list!.description}\n` +
+      `  sentroy env diff  [<file>]              ${ENV_SUBCOMMANDS.diff!.description}\n\n` +
+      `MAIL (requires SENTROY_API_KEY + SENTROY_COMPANY_SLUG)\n` +
+      `  sentroy mail templates list             List email templates\n` +
+      `  sentroy mail templates get <id>         Template detail\n` +
+      `  sentroy mail domains list               List sending domains\n` +
+      `  sentroy mail mailboxes list             List inbox mailboxes\n` +
+      `  sentroy mail inbox list                 Recent inbox messages (--mailbox, --folder, --unread, --q, --page, --limit)\n` +
+      `  sentroy mail suppressions list          Bounce/complaint suppressions (--domain, --reason)\n` +
+      `  sentroy mail logs list                  Delivery logs (--status, --domain, --from, --to)\n` +
+      `  sentroy mail logs get <id>              Log detail (event timeline)\n` +
+      `  sentroy mail webhooks list              Webhook endpoints (--domain)\n` +
+      `  sentroy mail analytics                  Aggregate stats (--days=7|30|90, --domain)\n\n` +
+      `STORAGE (requires SENTROY_API_KEY + SENTROY_COMPANY_SLUG)\n` +
+      `  sentroy storage buckets list            List storage buckets\n` +
+      `  sentroy storage buckets get <slug>      Bucket detail\n` +
+      `  sentroy storage media list <bucketSlug> List media in bucket (--type, --folder, --q, --sort, --dir, --limit, --skip)\n` +
+      `  sentroy storage media get <bucketSlug> <mediaId>  Media detail\n` +
+      `  sentroy storage usage                   Quota + per-bucket breakdown\n` +
+      `  sentroy storage quota                   Lightweight quota only\n\n` +
+      `AI SKILL (install the Sentroy AI agent skill into your project)\n` +
+      `  sentroy ai install                      Autodetect tools (Claude, Cursor, Windsurf) + AGENTS.md\n` +
+      `  sentroy ai install --claude             Install only into .claude/skills/sentroy/\n` +
+      `  sentroy ai install --cursor             Install only into .cursor/rules/sentroy.mdc\n` +
+      `  sentroy ai install --windsurf           Merge into .windsurfrules\n` +
+      `  sentroy ai install --agents             Merge into AGENTS.md at cwd\n` +
+      `  sentroy ai install --all                Install into every supported target\n` +
+      `  sentroy ai install --upgrade            Re-install latest, replacing existing sentinel block\n` +
+      `  sentroy ai install --check              Dry-run, show what would change\n\n` +
       `GLOBAL FLAGS\n` +
-      `  --token=stk_env_...    Vault token (default: $SENTROY_ENV_API_KEY)\n` +
-      `  --url=https://...      Sentroy core URL (default: $SENTROY_ENV_API_URL or https://sentroy.com)\n\n` +
-      `ENV PUSH FLAGS\n` +
-      `  --delete-missing       Remove vault keys not present in the local file (full sync)\n` +
-      `  --dry-run              Print the diff but do not write\n` +
-      `  --yes                  Skip the delete-confirmation prompt (CI-friendly)\n\n` +
-      `ENV PULL FLAGS\n` +
-      `  --force                Overwrite the file if it already exists\n\n` +
-      `ENV LIST FLAGS\n` +
-      `  --values               Include values (default: keys only)\n` +
-      `  --public-only          Only variables marked public\n\n` +
+      `  --token=stk_...                         Override $SENTROY_API_KEY (env vault uses $SENTROY_ENV_API_KEY)\n` +
+      `  --url=https://...                       Override base URL (default https://sentroy.com)\n` +
+      `  --company-slug=<slug>                   Override $SENTROY_COMPANY_SLUG (required for mail/storage)\n` +
+      `  --output=json|table                     Output format (default table)\n\n` +
       `EXAMPLES\n` +
       `  sentroy env push .env.production --delete-missing\n` +
-      `  sentroy env pull .env --force\n` +
-      `  sentroy env diff .env.production --delete-missing\n` +
-      `  sentroy env list --values --public-only\n\n` +
-      `Token scope (project + environment) is implicit — generate one in the\n` +
-      `Sentroy vault dashboard.\n\n`,
+      `  sentroy mail templates list --output=json | jq '.[].name'\n` +
+      `  sentroy mail logs list --status=bounced --days=7\n` +
+      `  sentroy storage buckets list\n` +
+      `  sentroy ai install\n\n` +
+      `DOCS\n` +
+      `  https://docs.sentroy.com/cli            Full CLI reference\n` +
+      `  https://docs.sentroy.com/ai-skills      AI Skill install guide\n\n`,
   )
 }
 
@@ -95,6 +158,7 @@ async function main(): Promise<void> {
   }
 
   const cmd = argv[0]
+
   if (cmd === "env") {
     const sub = argv[1]
     const handler = sub ? ENV_SUBCOMMANDS[sub] : undefined
@@ -109,6 +173,64 @@ async function main(): Promise<void> {
     return
   }
 
+  if (cmd === "mail") {
+    // `mail <resource> [verb] [args]` → handler key = resource + Capitalize(verb).
+    // Exception: `mail analytics` has no verb → handler key = "analytics".
+    const resource = argv[1]
+    const verb = argv[2]
+    if (!resource) {
+      process.stderr.write(
+        `usage: sentroy mail <resource> [verb] [args]\nresources: templates, domains, mailboxes, inbox, suppressions, logs, webhooks, analytics\n`,
+      )
+      process.exit(1)
+    }
+    const handler = resolveHandler(MAIL_HANDLERS, resource, verb)
+    if (!handler) {
+      process.stderr.write(
+        `unknown mail command: \`sentroy mail ${resource}${verb ? " " + verb : ""}\`\n` +
+          `available: ${Object.keys(MAIL_HANDLERS).join(", ")}\n`,
+      )
+      process.exit(1)
+    }
+    await handler.fn(argv.slice(handler.consumed))
+    return
+  }
+
+  if (cmd === "storage") {
+    const resource = argv[1]
+    const verb = argv[2]
+    if (!resource) {
+      process.stderr.write(
+        `usage: sentroy storage <resource> [verb] [args]\nresources: buckets, media, usage, quota\n`,
+      )
+      process.exit(1)
+    }
+    const handler = resolveHandler(STORAGE_HANDLERS, resource, verb)
+    if (!handler) {
+      process.stderr.write(
+        `unknown storage command: \`sentroy storage ${resource}${verb ? " " + verb : ""}\`\n` +
+          `available: ${Object.keys(STORAGE_HANDLERS).join(", ")}\n`,
+      )
+      process.exit(1)
+    }
+    await handler.fn(argv.slice(handler.consumed))
+    return
+  }
+
+  if (cmd === "ai") {
+    const sub = argv[1]
+    const handler = sub ? AI_HANDLERS[sub as keyof typeof AI_HANDLERS] : undefined
+    if (!handler) {
+      process.stderr.write(
+        `unknown ai subcommand: ${sub ?? "<missing>"}\n` +
+          `available: ${Object.keys(AI_HANDLERS).join(", ")}\n`,
+      )
+      process.exit(1)
+    }
+    await handler(argv.slice(2))
+    return
+  }
+
   process.stderr.write(
     `unknown command: ${cmd}\nrun \`sentroy --help\` for usage.\n`,
   )