shipmail-cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 ShipMail
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,77 @@
+# ShipMail CLI
+
+Official command line interface for the ShipMail API.
+
+```bash
+npx -y shipmail-cli --help
+```
+
+## Authentication
+
+Most commands require an API key. Create one in the ShipMail dashboard and export it:
+
+```bash
+export SHIPMAIL_API_KEY="sm_live_..."
+```
+
+You can also pass `--api-key` to any command. Use `SHIPMAIL_BASE_URL` or `--base-url` when targeting a non-production API.
+
+## Common Commands
+
+```bash
+# Check public API health
+shipmail status
+
+# Create a domain and verify DNS
+shipmail domains create example.com
+shipmail domains verify dom_123
+
+# Create a mailbox
+shipmail mailboxes create --domain-id dom_123 --address hello --display-name "Hello"
+
+# Send email
+shipmail messages send \
+  --mailbox-id mbx_123 \
+  --to user@example.com \
+  --subject "Hello" \
+  --text "It works."
+
+# Read inbound mail
+shipmail inbox list mbx_123 --folder-role inbox --limit 25
+shipmail inbox thread mbx_123 thr_123
+
+# Manage webhooks
+shipmail webhooks create \
+  --url https://example.com/shipmail/webhook \
+  --events message.received,message.bounced
+shipmail webhooks deliveries whk_123 --status failed
+```
+
+## Generic API Command
+
+The `api` command reaches every ShipMail REST endpoint, including endpoints that do not have a shorthand command yet.
+
+```bash
+shipmail api GET /domains
+
+shipmail api PATCH /mailboxes/mbx_123/spam-filter \
+  --data '{"threshold":6}'
+
+shipmail api PUT /mailboxes/mbx_123/rules \
+  --data @rules.json
+```
+
+Use repeatable `--header "Name: value"` flags for request headers. Use `--output path` to write non-JSON responses, such as attachment downloads.
+
+## Command Surface
+
+- `status`
+- `api <METHOD> <PATH>`
+- `domains list|search|create|get|verify|delete`
+- `mailboxes list|create|get|folders|identities|rules`
+- `inbox list|thread|update|move`
+- `messages send|list|get`
+- `webhooks list|create|test|deliveries`
+- `suppressions list|remove`
+
+Run `shipmail --help` for flags and examples.

package/dist/cli.d.ts

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+type Output = {
+    write(chunk: string): void;
+};
+type CliEnv = Record<string, string | undefined>;
+type RunCliOptions = {
+    readonly env?: CliEnv | undefined;
+    readonly stdout?: Output | undefined;
+    readonly stderr?: Output | undefined;
+    readonly fetch?: typeof fetch | undefined;
+};
+declare function runCli(argv: readonly string[], options?: RunCliOptions): Promise<number>;
+
+export { runCli };

package/dist/cli.js

@@ -0,0 +1,651 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { readFile, writeFile } from "fs/promises";
+import { env as processEnv, exit, stderr, stdout } from "process";
+import { pathToFileURL } from "url";
+import {
+  ShipMailClient,
+  ShipMailError,
+  WEBHOOK_EVENT_TYPES
+} from "shipmail";
+
+// src/version.ts
+var VERSION = "0.1.0";
+
+// src/cli.ts
+var DEFAULT_BASE_URL = "https://shipmail.to/api/v1";
+var WEBHOOK_EVENT_TYPE_SET = new Set(WEBHOOK_EVENT_TYPES);
+var CliUsageError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "CliUsageError";
+  }
+};
+var CliHttpError = class extends Error {
+  constructor(status, body) {
+    super(`Request failed with status ${status}`);
+    this.status = status;
+    this.body = body;
+    this.name = "CliHttpError";
+  }
+};
+function parseCliArgs(argv) {
+  const positional = [];
+  const options = {};
+  for (let i = 0; i < argv.length; i += 1) {
+    const token = argv[i];
+    if (token === "--") {
+      positional.push(...argv.slice(i + 1));
+      break;
+    }
+    if (!token.startsWith("--") || token === "--") {
+      positional.push(token);
+      continue;
+    }
+    const raw = token.slice(2);
+    const inlineIndex = raw.indexOf("=");
+    const key = inlineIndex >= 0 ? raw.slice(0, inlineIndex) : raw;
+    const inlineValue = inlineIndex >= 0 ? raw.slice(inlineIndex + 1) : void 0;
+    const next = argv[i + 1];
+    let value;
+    if (inlineValue !== void 0) {
+      value = inlineValue;
+    } else if (next !== void 0 && !next.startsWith("--")) {
+      value = next;
+      i += 1;
+    } else {
+      value = true;
+    }
+    const existing = options[key];
+    if (existing === void 0) {
+      options[key] = value;
+    } else if (Array.isArray(existing)) {
+      options[key] = [...existing, String(value)];
+    } else {
+      options[key] = [String(existing), String(value)];
+    }
+  }
+  return { positional, options };
+}
+function optionValue(options, key) {
+  return options[key];
+}
+function isStringArray(value) {
+  return Array.isArray(value);
+}
+function getString(options, key) {
+  const value = optionValue(options, key);
+  if (value === void 0) return void 0;
+  if (isStringArray(value)) return value.at(-1);
+  if (typeof value === "boolean") return value ? "true" : "false";
+  return value;
+}
+function getRequiredString(options, key) {
+  const value = getString(options, key);
+  if (!value) throw new CliUsageError(`Missing --${key}.`);
+  return value;
+}
+function getNumber(options, key) {
+  const value = getString(options, key);
+  if (value === void 0) return void 0;
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed)) throw new CliUsageError(`--${key} must be an integer.`);
+  return parsed;
+}
+function getBoolean(options, key) {
+  const value = optionValue(options, key);
+  if (value === void 0) return void 0;
+  const raw = isStringArray(value) ? value.at(-1) : value;
+  if (raw === true) return true;
+  if (raw === false) return false;
+  if (raw === "true" || raw === "1" || raw === "yes") return true;
+  if (raw === "false" || raw === "0" || raw === "no") return false;
+  throw new CliUsageError(`--${key} must be true or false.`);
+}
+function splitValues(value) {
+  if (typeof value === "boolean") return [];
+  return value.split(",").map((item) => item.trim()).filter(Boolean);
+}
+function getStringList(options, key) {
+  const value = optionValue(options, key);
+  if (value === void 0) return [];
+  if (isStringArray(value)) return value.flatMap(splitValues);
+  return splitValues(value);
+}
+function normalizeBaseUrl(value) {
+  return (value ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+}
+function apiKey(parsed, env) {
+  return getString(parsed.options, "api-key") ?? env["SHIPMAIL_API_KEY"];
+}
+function baseUrl(parsed, env) {
+  return normalizeBaseUrl(getString(parsed.options, "base-url") ?? env["SHIPMAIL_BASE_URL"]);
+}
+function requireApiKey(parsed, env) {
+  const key = apiKey(parsed, env);
+  if (!key) {
+    throw new CliUsageError("Missing API key. Set SHIPMAIL_API_KEY or pass --api-key sm_live_...");
+  }
+  return key;
+}
+function createClient(parsed, options) {
+  const env = options.env ?? processEnv;
+  const config = {
+    apiKey: requireApiKey(parsed, env),
+    baseUrl: baseUrl(parsed, env),
+    ...options.fetch ? { fetch: options.fetch } : {}
+  };
+  return new ShipMailClient(config);
+}
+function writeJson(out, value) {
+  out.write(`${JSON.stringify(value, null, 2)}
+`);
+}
+async function readJsonInput(value) {
+  if (value === void 0) return void 0;
+  const raw = value.startsWith("@") ? await readFile(value.slice(1), "utf8") : value;
+  try {
+    return JSON.parse(raw);
+  } catch {
+    throw new CliUsageError("--data must be valid JSON or @path/to/file.json.");
+  }
+}
+function apiPath(rawPath) {
+  if (!rawPath) throw new CliUsageError("Missing API path.");
+  if (!rawPath.startsWith("/")) throw new CliUsageError("API path must start with '/'.");
+  return rawPath;
+}
+function parseHeaders(values) {
+  const headers = {};
+  for (const value of values) {
+    const index = value.indexOf(":");
+    if (index <= 0) throw new CliUsageError("--header must use 'Name: value' format.");
+    headers[value.slice(0, index).trim()] = value.slice(index + 1).trim();
+  }
+  return headers;
+}
+async function rawApiRequest(parsed, runOptions, method, path, body, authRequired) {
+  const env = runOptions.env ?? processEnv;
+  const headers = {
+    Accept: "application/json",
+    ...parseHeaders(getStringList(parsed.options, "header"))
+  };
+  if (authRequired) {
+    headers["Authorization"] = `Bearer ${requireApiKey(parsed, env)}`;
+  } else {
+    const key = apiKey(parsed, env);
+    if (key) headers["Authorization"] = `Bearer ${key}`;
+  }
+  let requestBody;
+  if (body !== void 0) {
+    headers["Content-Type"] = "application/json";
+    requestBody = JSON.stringify(body);
+  }
+  const response = await (runOptions.fetch ?? fetch)(`${baseUrl(parsed, env)}${path}`, {
+    method,
+    headers,
+    body: requestBody
+  });
+  if (!response.ok) {
+    const contentType = response.headers.get("content-type") ?? "";
+    const errorBody = contentType.includes("application/json") ? await response.json().catch(() => null) : await response.text().catch(() => "");
+    throw new CliHttpError(response.status, errorBody);
+  }
+  return response;
+}
+async function writeRawResponse(parsed, io, response) {
+  const outputPath = getString(parsed.options, "output");
+  if (outputPath) {
+    await writeFile(outputPath, Buffer.from(await response.arrayBuffer()));
+    io.stdout.write(`${outputPath}
+`);
+    return;
+  }
+  if (response.status === 204) {
+    writeJson(io.stdout, { ok: true, status: response.status });
+    return;
+  }
+  const contentType = response.headers.get("content-type") ?? "";
+  if (contentType.includes("application/json")) {
+    writeJson(io.stdout, await response.json());
+    return;
+  }
+  io.stdout.write(`${await response.text()}
+`);
+}
+function usage() {
+  return `shipmail-cli v${VERSION}
+
+Usage:
+  shipmail status
+  shipmail api <METHOD> <PATH> [--data JSON|@file] [--output file]
+  shipmail domains list [--limit 25] [--cursor cur]
+  shipmail domains search <keyword>
+  shipmail domains create <name>
+  shipmail domains get <id>
+  shipmail domains verify <id>
+  shipmail domains delete <id>
+  shipmail mailboxes list [--domain-id dom] [--limit 25] [--cursor cur]
+  shipmail mailboxes create --domain-id dom --address hello [--display-name "Hello"]
+  shipmail mailboxes get <id>
+  shipmail mailboxes folders <id>
+  shipmail mailboxes identities <id>
+  shipmail mailboxes rules <id>
+  shipmail inbox list <mailbox-id> [--folder-role inbox] [--limit 25]
+  shipmail inbox thread <mailbox-id> <thread-id>
+  shipmail inbox update <mailbox-id> <message-id> [--read true] [--starred false]
+  shipmail inbox move <mailbox-id> <message-id> (--target-role archive | --target-folder-id fld)
+  shipmail messages send --mailbox-id mbx --to user@example.com --subject "Hi" --text "Hello"
+  shipmail webhooks list
+  shipmail webhooks create --url https://example.com/hook --events message.received,message.bounced
+  shipmail suppressions list
+  shipmail suppressions remove <email>
+
+Global options:
+  --api-key <key>       API key. Defaults to SHIPMAIL_API_KEY.
+  --base-url <url>      API base URL. Defaults to SHIPMAIL_BASE_URL or ${DEFAULT_BASE_URL}.
+  --header "K: V"       Extra header for the generic api command. Repeatable.
+
+Environment:
+  SHIPMAIL_API_KEY      API key for authenticated commands.
+  SHIPMAIL_BASE_URL     Optional API base URL.
+`;
+}
+function requirePositional(positional, index, label) {
+  const value = positional[index];
+  if (!value) throw new CliUsageError(`Missing ${label}.`);
+  return value;
+}
+function inboxListParams(options) {
+  const params = {};
+  const folderId = getString(options, "folder-id");
+  const folderRole = getString(options, "folder-role");
+  const searchText = getString(options, "search");
+  const position = getNumber(options, "position");
+  const limit = getNumber(options, "limit");
+  const hasKeyword = getString(options, "has-keyword");
+  const notKeyword = getString(options, "not-keyword");
+  if (folderId) params.folder_id = folderId;
+  if (folderRole) params.folder_role = folderRole;
+  if (searchText) params.search_text = searchText;
+  if (position !== void 0) params.position = position;
+  if (limit !== void 0) params.limit = limit;
+  if (hasKeyword) params.has_keyword = hasKeyword;
+  if (notKeyword) params.not_keyword = notKeyword;
+  return params;
+}
+function messageRecipients(options, key) {
+  return getStringList(options, key);
+}
+function webhookEvents(options) {
+  const events = getStringList(options, "events");
+  if (events.length === 0) throw new CliUsageError("Provide at least one --events value.");
+  const invalid = events.filter((event) => !WEBHOOK_EVENT_TYPE_SET.has(event));
+  if (invalid.length > 0) {
+    throw new CliUsageError(`Invalid webhook event type: ${invalid.join(", ")}.`);
+  }
+  return events;
+}
+function webhookDeliveryParams(options) {
+  const status = getString(options, "status");
+  const eventType = getString(options, "event-type");
+  return {
+    cursor: getString(options, "cursor"),
+    limit: getNumber(options, "limit"),
+    ...status ? { status } : {},
+    ...eventType ? { event_type: eventType } : {}
+  };
+}
+function sendMessageParams(options) {
+  const mailboxId = getString(options, "mailbox-id");
+  const from = getString(options, "from");
+  const to = messageRecipients(options, "to");
+  const cc = messageRecipients(options, "cc");
+  const bcc = messageRecipients(options, "bcc");
+  const replyTo = getString(options, "reply-to");
+  const subject = getRequiredString(options, "subject");
+  const text = getString(options, "text");
+  const html = getString(options, "html");
+  if (!mailboxId && !from) throw new CliUsageError("Provide --mailbox-id or --from.");
+  if (to.length === 0) throw new CliUsageError("Provide at least one --to recipient.");
+  if (!text && !html) throw new CliUsageError("Provide --text or --html.");
+  return {
+    ...mailboxId ? { mailbox_id: mailboxId } : {},
+    ...from ? { from } : {},
+    to,
+    ...cc.length > 0 ? { cc } : {},
+    ...bcc.length > 0 ? { bcc } : {},
+    ...replyTo ? { reply_to: replyTo } : {},
+    subject,
+    ...html ? { html } : {},
+    ...text ? { text } : {}
+  };
+}
+async function runDomains(client, parsed, out) {
+  const subcommand = parsed.positional[1];
+  if (subcommand === "list") {
+    writeJson(
+      out,
+      await client.domains.list({
+        cursor: getString(parsed.options, "cursor"),
+        limit: getNumber(parsed.options, "limit")
+      })
+    );
+    return;
+  }
+  if (subcommand === "search") {
+    writeJson(
+      out,
+      await client.domains.search({ keyword: requirePositional(parsed.positional, 2, "keyword") })
+    );
+    return;
+  }
+  if (subcommand === "create") {
+    writeJson(
+      out,
+      await client.domains.create({ name: requirePositional(parsed.positional, 2, "domain name") })
+    );
+    return;
+  }
+  if (subcommand === "get") {
+    writeJson(out, await client.domains.get(requirePositional(parsed.positional, 2, "domain id")));
+    return;
+  }
+  if (subcommand === "verify") {
+    writeJson(
+      out,
+      await client.domains.verify(requirePositional(parsed.positional, 2, "domain id"))
+    );
+    return;
+  }
+  if (subcommand === "delete") {
+    const id = requirePositional(parsed.positional, 2, "domain id");
+    await client.domains.delete(id);
+    writeJson(out, { ok: true, id });
+    return;
+  }
+  throw new CliUsageError("Unknown domains command.");
+}
+async function runMailboxes(client, parsed, out) {
+  const subcommand = parsed.positional[1];
+  if (subcommand === "list") {
+    writeJson(
+      out,
+      await client.mailboxes.list({
+        domain_id: getString(parsed.options, "domain-id"),
+        cursor: getString(parsed.options, "cursor"),
+        limit: getNumber(parsed.options, "limit")
+      })
+    );
+    return;
+  }
+  if (subcommand === "create") {
+    const displayName = getString(parsed.options, "display-name");
+    writeJson(
+      out,
+      await client.mailboxes.create({
+        domain_id: getRequiredString(parsed.options, "domain-id"),
+        address: getRequiredString(parsed.options, "address"),
+        ...displayName ? { display_name: displayName } : {}
+      })
+    );
+    return;
+  }
+  if (subcommand === "get") {
+    writeJson(
+      out,
+      await client.mailboxes.get(requirePositional(parsed.positional, 2, "mailbox id"))
+    );
+    return;
+  }
+  if (subcommand === "folders") {
+    writeJson(
+      out,
+      await client.mailboxes.listFolders(requirePositional(parsed.positional, 2, "mailbox id"))
+    );
+    return;
+  }
+  if (subcommand === "identities") {
+    writeJson(
+      out,
+      await client.mailboxes.listIdentities(requirePositional(parsed.positional, 2, "mailbox id"))
+    );
+    return;
+  }
+  if (subcommand === "rules") {
+    writeJson(
+      out,
+      await client.mailboxes.getRules(requirePositional(parsed.positional, 2, "mailbox id"))
+    );
+    return;
+  }
+  throw new CliUsageError("Unknown mailboxes command.");
+}
+async function runInbox(client, parsed, out) {
+  const subcommand = parsed.positional[1];
+  if (subcommand === "list") {
+    writeJson(
+      out,
+      await client.mailboxes.listInboxMessages(
+        requirePositional(parsed.positional, 2, "mailbox id"),
+        inboxListParams(parsed.options)
+      )
+    );
+    return;
+  }
+  if (subcommand === "thread") {
+    writeJson(
+      out,
+      await client.mailboxes.getInboxThread(
+        requirePositional(parsed.positional, 2, "mailbox id"),
+        requirePositional(parsed.positional, 3, "thread id")
+      )
+    );
+    return;
+  }
+  if (subcommand === "update") {
+    const read = getBoolean(parsed.options, "read");
+    const starred = getBoolean(parsed.options, "starred");
+    if (read === void 0 && starred === void 0) {
+      throw new CliUsageError("Provide --read or --starred.");
+    }
+    writeJson(
+      out,
+      await client.mailboxes.updateInboxMessage(
+        requirePositional(parsed.positional, 2, "mailbox id"),
+        requirePositional(parsed.positional, 3, "message id"),
+        {
+          ...read !== void 0 ? { read } : {},
+          ...starred !== void 0 ? { starred } : {}
+        }
+      )
+    );
+    return;
+  }
+  if (subcommand === "move") {
+    const targetRole = getString(parsed.options, "target-role");
+    const targetFolderId = getString(parsed.options, "target-folder-id");
+    if (Boolean(targetRole) === Boolean(targetFolderId)) {
+      throw new CliUsageError("Provide exactly one of --target-role or --target-folder-id.");
+    }
+    writeJson(
+      out,
+      await client.mailboxes.moveInboxMessage(
+        requirePositional(parsed.positional, 2, "mailbox id"),
+        requirePositional(parsed.positional, 3, "message id"),
+        {
+          ...getString(parsed.options, "from-folder-id") ? { from_folder_id: getString(parsed.options, "from-folder-id") } : {},
+          ...targetRole ? { target_role: targetRole } : {},
+          ...targetFolderId ? { target_folder_id: targetFolderId } : {}
+        }
+      )
+    );
+    return;
+  }
+  throw new CliUsageError("Unknown inbox command.");
+}
+async function runMessages(client, parsed, out) {
+  const subcommand = parsed.positional[1];
+  if (subcommand === "send") {
+    writeJson(out, await client.messages.send(sendMessageParams(parsed.options)));
+    return;
+  }
+  if (subcommand === "list") {
+    writeJson(
+      out,
+      await client.messages.list({
+        mailbox_id: getRequiredString(parsed.options, "mailbox-id"),
+        cursor: getString(parsed.options, "cursor"),
+        limit: getNumber(parsed.options, "limit")
+      })
+    );
+    return;
+  }
+  if (subcommand === "get") {
+    writeJson(
+      out,
+      await client.messages.get(requirePositional(parsed.positional, 2, "message id"))
+    );
+    return;
+  }
+  throw new CliUsageError("Unknown messages command.");
+}
+async function runWebhooks(client, parsed, out) {
+  const subcommand = parsed.positional[1];
+  if (subcommand === "list") {
+    writeJson(
+      out,
+      await client.webhooks.list({
+        cursor: getString(parsed.options, "cursor"),
+        limit: getNumber(parsed.options, "limit")
+      })
+    );
+    return;
+  }
+  if (subcommand === "create") {
+    const description = getString(parsed.options, "description");
+    writeJson(
+      out,
+      await client.webhooks.create({
+        url: getRequiredString(parsed.options, "url"),
+        events: webhookEvents(parsed.options),
+        ...description ? { description } : {}
+      })
+    );
+    return;
+  }
+  if (subcommand === "test") {
+    writeJson(
+      out,
+      await client.webhooks.test(requirePositional(parsed.positional, 2, "webhook id"))
+    );
+    return;
+  }
+  if (subcommand === "deliveries") {
+    writeJson(
+      out,
+      await client.webhooks.listDeliveries(
+        requirePositional(parsed.positional, 2, "webhook id"),
+        webhookDeliveryParams(parsed.options)
+      )
+    );
+    return;
+  }
+  throw new CliUsageError("Unknown webhooks command.");
+}
+async function runSuppressions(client, parsed, out) {
+  const subcommand = parsed.positional[1];
+  if (subcommand === "list") {
+    writeJson(
+      out,
+      await client.suppressions.list({
+        cursor: getString(parsed.options, "cursor"),
+        limit: getNumber(parsed.options, "limit")
+      })
+    );
+    return;
+  }
+  if (subcommand === "remove") {
+    const email = requirePositional(parsed.positional, 2, "email");
+    await client.suppressions.remove(email);
+    writeJson(out, { ok: true, email });
+    return;
+  }
+  throw new CliUsageError("Unknown suppressions command.");
+}
+function writeError(err, errOut) {
+  if (err instanceof CliUsageError) {
+    errOut.write(`Error: ${err.message}
+
+${usage()}`);
+    return;
+  }
+  if (err instanceof CliHttpError) {
+    errOut.write(`Error: HTTP ${err.status}
+${JSON.stringify(err.body, null, 2)}
+`);
+    return;
+  }
+  if (err instanceof ShipMailError) {
+    const status = err.status !== void 0 ? ` (HTTP ${err.status})` : "";
+    const requestId = err.requestId ? ` request_id=${err.requestId}` : "";
+    errOut.write(`Error: ${err.message}${status}${requestId}
+`);
+    return;
+  }
+  errOut.write(`Error: ${err instanceof Error ? err.message : String(err)}
+`);
+}
+async function runCli(argv, options = {}) {
+  const parsed = parseCliArgs(argv);
+  const out = options.stdout ?? stdout;
+  const errOut = options.stderr ?? stderr;
+  const command = parsed.positional[0];
+  try {
+    if (command === "version" || optionValue(parsed.options, "version")) {
+      out.write(`${VERSION}
+`);
+      return 0;
+    }
+    if (!command || command === "help" || command === "-h" || optionValue(parsed.options, "help")) {
+      out.write(usage());
+      return 0;
+    }
+    if (command === "status") {
+      const response = await rawApiRequest(parsed, options, "GET", "/status", void 0, false);
+      await writeRawResponse(parsed, { stdout: out }, response);
+      return 0;
+    }
+    if (command === "api") {
+      const method = requirePositional(parsed.positional, 1, "method").toUpperCase();
+      const path = apiPath(requirePositional(parsed.positional, 2, "path"));
+      const body = await readJsonInput(getString(parsed.options, "data"));
+      const response = await rawApiRequest(parsed, options, method, path, body, path !== "/status");
+      await writeRawResponse(parsed, { stdout: out }, response);
+      return 0;
+    }
+    const client = createClient(parsed, options);
+    if (command === "domains") await runDomains(client, parsed, out);
+    else if (command === "mailboxes") await runMailboxes(client, parsed, out);
+    else if (command === "inbox") await runInbox(client, parsed, out);
+    else if (command === "messages") await runMessages(client, parsed, out);
+    else if (command === "webhooks") await runWebhooks(client, parsed, out);
+    else if (command === "suppressions") await runSuppressions(client, parsed, out);
+    else throw new CliUsageError(`Unknown command: ${command}.`);
+    return 0;
+  } catch (err) {
+    writeError(err, errOut);
+    return 1;
+  }
+}
+async function main() {
+  const code = await runCli(process.argv.slice(2));
+  exit(code);
+}
+if (import.meta.url === pathToFileURL(process.argv[1] ?? "").href) {
+  void main();
+}
+export {
+  runCli
+};

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "shipmail-cli",
+  "version": "0.1.0",
+  "description": "Official CLI for the ShipMail API",
+  "type": "module",
+  "bin": {
+    "shipmail": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup src/cli.ts --format esm --dts --clean",
+    "dev": "tsx src/cli.ts",
+    "prepack": "bun run build",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "shipmail",
+    "email",
+    "cli",
+    "email-api",
+    "domain",
+    "terminal"
+  ],
+  "author": "ShipMail",
+  "license": "MIT",
+  "homepage": "https://shipmail.to/docs/cli",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jcoulaud/ShipMail.git",
+    "directory": "packages/shipmail-cli"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "shipmail": "0.1.21"
+  },
+  "devDependencies": {
+    "tsup": "^8.4.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.8.3"
+  }
+}