@sendpanda/cli 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dilhan Geeth Amarasinghe
+
+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

@@ -1,3 +1,44 @@
-# Temporary Holding Version
+# SendPanda CLI
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Manage every SendPanda project from a terminal or a coding agent: create projects, add and verify domains, create keys and templates, send email. Requires Node.js 22 or newer.
+
+```sh
+npx @sendpanda/cli login --token sp_pat_...   # token: dashboard → Settings → Connections → New token
+npx @sendpanda/cli whoami                     # accounts, projects, environment ids
+npx @sendpanda/cli setup --project "My App" --domain example.com --env-file .env
+```
+
+`setup` creates the project (or reuses it), adds the domain and prints the DNS records to publish, and creates a **send-only** API key (appended to `--env-file`, or printed once). After the records are live: `sendpanda domains verify <id>`.
+
+## Commands
+
+Run `sendpanda help` for the full list. Everything prints JSON on stdout (messages go to stderr), so agents can parse it.
+
+| Area          | Commands                                                    |
+| ------------- | ----------------------------------------------------------- |
+| Session       | `login`, `logout`, `whoami`, `use PROJECT`                  |
+| Projects      | `projects list / create / rename / delete --confirm "NAME"` |
+| Domains       | `domains list / add / get / verify / delete`                |
+| Keys          | `keys list / create / revoke`                               |
+| Templates     | `templates list / get / create / publish / preview`         |
+| Email         | `emails send / list / get`                                  |
+| Webhooks      | `webhooks list / create / delete`                           |
+| Anything else | `api METHOD PATH --data JSON`, `routes [FILTER]`            |
+
+Pass `--env PROJECT` (a name, project id or environment id) to act on a project other than the one chosen with `use`.
+
+## Access tokens
+
+An access token acts as you, with exactly your permissions, on every project you can reach. It cannot manage billing, sign-in, or other tokens: those need the dashboard. Tokens expire (default 90 days) and can be revoked in Settings → Connections. Treat one like a password; `SENDPANDA_TOKEN` overrides the saved login, and the saved file is readable only by you.
+
+Deleting a project is permanent and requires its exact name.
+
+## MCP
+
+The same token powers an MCP server covering all projects:
+
+```sh
+SENDPANDA_TOKEN=sp_pat_... npx -y @sendpanda/mcp
+```
+
+See `docs/agents.md` in the repository for setting up an agent end to end.

package/dist/cli.js

@@ -0,0 +1,462 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { mkdir, readFile, writeFile, chmod } from "fs/promises";
+import { homedir } from "os";
+import { dirname, join } from "path";
+var DEFAULT_API = "https://api.sendpanda.email";
+var HELP = `sendpanda: manage SendPanda from a terminal or a coding agent
+
+Setup
+  login --token <sp_pat_...> [--api URL]   Save an access token (Settings > Connections > New token)
+  logout                                   Forget the saved token
+  whoami                                   Show your accounts, projects and environment ids
+  setup --project NAME --domain DOMAIN     Create a project, add the domain, create a sending key
+        [--account ORG_ID] [--env-file .env]
+
+Projects (accounts hold projects; each project has environments such as Production)
+  projects list
+  projects create NAME [--account ORG_ID]
+  projects rename PROJECT NEW_NAME
+  projects delete PROJECT --confirm "EXACT NAME"      PERMANENT, with all its data
+  use PROJECT                                         Default environment for later commands
+
+Resources (use --env PROJECT_OR_ENVIRONMENT to override the default)
+  domains list | add NAME | get ID | verify ID | delete ID
+  keys list | create NAME [--scope send|full] | revoke ID
+  templates list | get ID | create --name N --subject S (--html-file F | --text-file F | --design-file F)
+            | publish ID [--version N] | preview ID
+  emails send --from A --to B[,C] --subject S (--html-file F | --text-file F | --template ID) | list | get ID
+  webhooks list | create URL [--events a,b] | delete ID
+
+Everything else
+  api METHOD PATH [--data JSON|@file] [--env ...]     Any API endpoint as you
+  routes [FILTER]                                     List API endpoints
+  mcp                                                 Run the MCP server for all your projects
+
+Output is JSON on stdout; messages go to stderr. SENDPANDA_TOKEN, SENDPANDA_API_URL and
+SENDPANDA_ENVIRONMENT override the saved login. Billing, sign-in and tokens need the dashboard.
+`;
+var CliError = class extends Error {
+};
+function parse(argv) {
+  const positional = [], flags = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith("--")) {
+      const [k, inline] = a.slice(2).split(/=(.*)/s, 2);
+      if (inline !== void 0) flags[k] = inline;
+      else if (argv[i + 1] !== void 0 && !argv[i + 1].startsWith("--"))
+        flags[k] = argv[++i];
+      else flags[k] = true;
+    } else positional.push(a);
+  }
+  return { positional, flags };
+}
+var str = (v) => typeof v === "string" ? v : void 0;
+async function main(argv, deps = {}) {
+  const d = {
+    fetch: deps.fetch ?? fetch,
+    env: deps.env ?? process.env,
+    out: deps.out ?? ((t) => process.stdout.write(t)),
+    err: deps.err ?? ((t) => process.stderr.write(t)),
+    readFile: deps.readFile ?? ((p) => readFile(p, "utf8"))
+  };
+  try {
+    await run(argv, d);
+    return 0;
+  } catch (e) {
+    d.err(`${e instanceof Error ? e.message : String(e)}
+`);
+    return e instanceof CliError ? 2 : 1;
+  }
+}
+function configPath(d) {
+  return join(
+    d.env.SENDPANDA_CONFIG_DIR ?? join(homedir(), ".config", "sendpanda"),
+    "config.json"
+  );
+}
+async function loadConfig(d) {
+  try {
+    return JSON.parse(await d.readFile(configPath(d)));
+  } catch {
+    return {};
+  }
+}
+async function saveConfig(d, config) {
+  const path = configPath(d);
+  await mkdir(dirname(path), { recursive: true, mode: 448 });
+  await writeFile(path, JSON.stringify(config, null, 2) + "\n", {
+    mode: 384
+  });
+  await chmod(path, 384);
+}
+async function run(argv, d) {
+  const { positional: p, flags } = parse(argv);
+  const [command, sub, ...rest] = p;
+  if (!command || command === "help" || flags.help || flags.h) {
+    d.out(HELP);
+    return;
+  }
+  const saved = await loadConfig(d);
+  const token = d.env.SENDPANDA_TOKEN ?? saved.token;
+  const api = (str(flags.api) ?? d.env.SENDPANDA_API_URL ?? saved.api ?? DEFAULT_API).replace(/\/(v1)?\/?$/, "");
+  const base = new URL(api);
+  if (base.protocol !== "https:" && !["localhost", "127.0.0.1", "[::1]"].includes(base.hostname))
+    throw new CliError("The API URL must use HTTPS");
+  const print = (value) => d.out(JSON.stringify(value, null, 2) + "\n");
+  async function call(method, path, options = {}) {
+    const secret = options.token ?? token;
+    if (!secret)
+      throw new CliError(
+        "Not signed in. Create an access token in the dashboard (Settings > Connections) and run: sendpanda login --token sp_pat_..."
+      );
+    if (!/^\/(v1|api)\//.test(path))
+      throw new CliError("Path must start with /v1/ or /api/");
+    const response = await d.fetch(new URL(path, base), {
+      method,
+      headers: {
+        Authorization: `Bearer ${secret}`,
+        ...options.env ? { "X-Environment-Id": options.env } : {},
+        ...options.body !== void 0 ? { "Content-Type": "application/json" } : {}
+      },
+      ...options.body !== void 0 ? { body: JSON.stringify(options.body) } : {},
+      redirect: "error",
+      signal: AbortSignal.timeout(3e4)
+    });
+    const data = await response.json().catch(() => null);
+    if (!response.ok)
+      throw new Error(
+        `${data?.error?.code ?? "request_failed"}: ${data?.error?.message ?? `HTTP ${response.status}`}`
+      );
+    return data;
+  }
+  const me = () => call("GET", "/api/me");
+  function findProject(all, value) {
+    const lower = value.toLowerCase();
+    const application = all.applications.find((a) => a.id === value) ?? all.applications.find((a) => a.name.toLowerCase() === lower);
+    const environment2 = all.projects.find((e) => e.id === value) ?? (application ? all.projects.find(
+      (e) => e.application_id === application.id && e.name === "Production"
+    ) ?? all.projects.find((e) => e.application_id === application.id) : void 0);
+    const owner = application ?? all.applications.find((a) => a.id === environment2?.application_id);
+    if (!owner)
+      throw new CliError(
+        `No project matches "${value}". Run: sendpanda projects list`
+      );
+    return { application: owner, environment: environment2 };
+  }
+  async function environment() {
+    const wanted = str(flags.env) ?? d.env.SENDPANDA_ENVIRONMENT ?? saved.environment;
+    if (!wanted)
+      throw new CliError(
+        "Choose a project: sendpanda use PROJECT, or pass --env PROJECT"
+      );
+    if (/^prj_[a-f0-9]+$/.test(wanted)) return wanted;
+    const found = findProject(await me(), wanted).environment;
+    if (!found) throw new CliError(`Project "${wanted}" has no environment`);
+    return found.id;
+  }
+  const inEnv = async (method, path, body) => call(method, path, { body, env: await environment() });
+  const content = async () => {
+    const out = {};
+    for (const [flag, key] of [
+      ["html-file", "html"],
+      ["text-file", "text"]
+    ])
+      if (str(flags[flag])) out[key] = await d.readFile(str(flags[flag]));
+    if (str(flags["design-file"]))
+      out.design = JSON.parse(await d.readFile(str(flags["design-file"])));
+    return out;
+  };
+  const need = (value, what) => {
+    if (!value) throw new CliError(`Missing ${what}. See: sendpanda help`);
+    return value;
+  };
+  switch (command) {
+    case "login": {
+      const given = str(flags.token) ?? d.env.SENDPANDA_TOKEN;
+      if (!given?.startsWith("sp_pat_"))
+        throw new CliError(
+          "Pass an access token: sendpanda login --token sp_pat_... (create one in the dashboard under Settings > Connections)"
+        );
+      const who = await call("GET", "/api/me", { token: given });
+      await saveConfig(d, {
+        ...saved,
+        token: given,
+        ...str(flags.api) ? { api: str(flags.api) } : {}
+      });
+      d.err(`Signed in as ${who.user.email}
+`);
+      print({ user: who.user });
+      return;
+    }
+    case "logout":
+      await saveConfig(d, { ...saved, token: void 0 });
+      d.err("Signed out. Revoke the token in the dashboard to disable it.\n");
+      return;
+    case "whoami": {
+      const all = await me();
+      print({
+        user: all.user,
+        accounts: all.organisations,
+        projects: all.applications.map((a) => ({
+          ...a,
+          environments: all.projects.filter((e) => e.application_id === a.id).map((e) => ({ id: e.id, name: e.name }))
+        })),
+        default_environment: d.env.SENDPANDA_ENVIRONMENT ?? saved.environment ?? null
+      });
+      return;
+    }
+    case "use": {
+      const found = findProject(await me(), need(sub, "project"));
+      if (!found.environment) throw new CliError("Project has no environment");
+      await saveConfig(d, { ...saved, environment: found.environment.id });
+      d.err(`Using ${found.application.name} (${found.environment.id})
+`);
+      print({ environment: found.environment.id });
+      return;
+    }
+    case "projects": {
+      if (sub === "list" || !sub) {
+        const all = await me();
+        print(
+          all.applications.map((a) => ({
+            ...a,
+            environments: all.projects.filter((e) => e.application_id === a.id).map((e) => ({ id: e.id, name: e.name }))
+          }))
+        );
+      } else if (sub === "create") {
+        const all = await me();
+        const account = str(flags.account) ?? (all.organisations.length === 1 ? all.organisations[0].id : void 0);
+        if (!account)
+          throw new CliError(
+            "Pass --account ORG_ID (you belong to several accounts; see: sendpanda whoami)"
+          );
+        print(
+          await call("POST", "/api/projects", {
+            body: {
+              name: need(rest[0], "project name"),
+              organisation_id: account
+            }
+          })
+        );
+      } else if (sub === "rename") {
+        const found = findProject(await me(), need(rest[0], "project"));
+        print(
+          await call("PATCH", `/api/projects/${found.application.id}`, {
+            body: { name: need(rest[1], "new name") }
+          })
+        );
+      } else if (sub === "delete") {
+        const found = findProject(await me(), need(rest[0], "project"));
+        if (str(flags.confirm) !== found.application.name)
+          throw new CliError(
+            `This permanently deletes "${found.application.name}" and all its data. Re-run with --confirm "${found.application.name}"`
+          );
+        print(
+          await call("POST", `/api/projects/${found.application.id}/purge`, {
+            body: { confirm_name: found.application.name }
+          })
+        );
+      } else throw new CliError("Usage: projects list|create|rename|delete");
+      return;
+    }
+    case "domains": {
+      if (sub === "list" || !sub) print(await inEnv("GET", "/v1/domains"));
+      else if (sub === "add")
+        print(
+          await inEnv("POST", "/v1/domains", { name: need(rest[0], "domain") })
+        );
+      else if (sub === "get")
+        print(await inEnv("GET", `/v1/domains/${need(rest[0], "domain id")}`));
+      else if (sub === "verify")
+        print(
+          await inEnv(
+            "POST",
+            `/v1/domains/${need(rest[0], "domain id")}/verify`
+          )
+        );
+      else if (sub === "delete")
+        print(
+          await inEnv("DELETE", `/v1/domains/${need(rest[0], "domain id")}`)
+        );
+      else throw new CliError("Usage: domains list|add|get|verify|delete");
+      return;
+    }
+    case "keys": {
+      if (sub === "list" || !sub) print(await inEnv("GET", "/v1/api-keys"));
+      else if (sub === "create")
+        print(
+          await inEnv("POST", "/v1/api-keys", {
+            name: need(rest[0], "key name"),
+            scope: str(flags.scope) ?? "send"
+          })
+        );
+      else if (sub === "revoke")
+        print(await inEnv("DELETE", `/v1/api-keys/${need(rest[0], "key id")}`));
+      else throw new CliError("Usage: keys list|create|revoke");
+      return;
+    }
+    case "templates": {
+      if (sub === "list" || !sub) print(await inEnv("GET", "/v1/templates"));
+      else if (sub === "get")
+        print(
+          await inEnv("GET", `/v1/templates/${need(rest[0], "template id")}`)
+        );
+      else if (sub === "create")
+        print(
+          await inEnv("POST", "/v1/templates", {
+            name: need(str(flags.name), "--name"),
+            subject: need(str(flags.subject), "--subject"),
+            ...await content()
+          })
+        );
+      else if (sub === "publish") {
+        const id = need(rest[0], "template id");
+        let version = Number(str(flags.version));
+        if (!version) {
+          const t = await inEnv("GET", `/v1/templates/${id}`);
+          version = Math.max(...(t.versions ?? []).map((v) => v.version), 0);
+        }
+        if (!version) throw new CliError("Template has no version to publish");
+        print(await inEnv("POST", `/v1/templates/${id}/publish`, { version }));
+      } else if (sub === "preview")
+        print(
+          await inEnv(
+            "POST",
+            `/v1/templates/${need(rest[0], "template id")}/preview`,
+            { variables: {} }
+          )
+        );
+      else
+        throw new CliError("Usage: templates list|get|create|publish|preview");
+      return;
+    }
+    case "emails": {
+      if (sub === "list" || !sub) print(await inEnv("GET", "/v1/emails"));
+      else if (sub === "get")
+        print(await inEnv("GET", `/v1/emails/${need(rest[0], "email id")}`));
+      else if (sub === "send")
+        print(
+          await inEnv("POST", "/v1/emails", {
+            from: need(str(flags.from), "--from"),
+            to: need(str(flags.to), "--to").split(",").map((v) => v.trim()),
+            ...str(flags.subject) ? { subject: str(flags.subject) } : {},
+            ...str(flags.template) ? { template_id: str(flags.template) } : {},
+            ...await content()
+          })
+        );
+      else throw new CliError("Usage: emails send|list|get");
+      return;
+    }
+    case "webhooks": {
+      if (sub === "list" || !sub) print(await inEnv("GET", "/v1/webhooks"));
+      else if (sub === "create")
+        print(
+          await inEnv("POST", "/v1/webhooks", {
+            url: need(rest[0], "URL"),
+            events: (str(flags.events) ?? "email.delivered,email.bounced,email.complained,email.failed").split(",")
+          })
+        );
+      else if (sub === "delete")
+        print(
+          await inEnv("DELETE", `/v1/webhooks/${need(rest[0], "webhook id")}`)
+        );
+      else throw new CliError("Usage: webhooks list|create|delete");
+      return;
+    }
+    case "api": {
+      const method = need(sub, "METHOD").toUpperCase();
+      if (!["GET", "POST", "PATCH", "DELETE"].includes(method))
+        throw new CliError("METHOD must be GET, POST, PATCH or DELETE");
+      let body;
+      const data = str(flags.data);
+      if (data !== void 0)
+        body = JSON.parse(
+          data.startsWith("@") ? await d.readFile(data.slice(1)) : data
+        );
+      const wantsEnv = str(flags.env) || (rest[0] ?? "").startsWith("/v1/");
+      print(
+        await call(method, need(rest[0], "PATH"), {
+          body,
+          env: wantsEnv ? await environment() : void 0
+        })
+      );
+      return;
+    }
+    case "routes": {
+      const spec = await d.fetch(new URL("/openapi.json", base)).then((r) => r.json());
+      const filter = (sub ?? "").toLowerCase();
+      print(
+        Object.entries(spec.paths).flatMap(
+          ([path, methods]) => Object.keys(methods).filter(() => path.toLowerCase().includes(filter)).map((m) => `${m.toUpperCase()} ${path}`)
+        )
+      );
+      return;
+    }
+    case "setup": {
+      const name = need(str(flags.project), "--project NAME");
+      const domain = need(str(flags.domain), "--domain DOMAIN");
+      const all = await me();
+      let found = all.applications.find(
+        (a) => a.name.toLowerCase() === name.toLowerCase()
+      );
+      let environmentId = found ? all.projects.find(
+        (e) => e.application_id === found.id && e.name === "Production"
+      )?.id : void 0;
+      if (!found) {
+        const account = str(flags.account) ?? (all.organisations.length === 1 ? all.organisations[0].id : void 0);
+        if (!account)
+          throw new CliError("Pass --account ORG_ID (see: sendpanda whoami)");
+        const created = await call("POST", "/api/projects", {
+          body: { name, organisation_id: account }
+        });
+        environmentId = created.environment_id;
+        d.err(`Created project ${name}
+`);
+      } else d.err(`Using existing project ${found.name}
+`);
+      if (!environmentId)
+        throw new CliError("Project has no Production environment");
+      const env = environmentId;
+      const domains = await call("GET", "/v1/domains", { env });
+      const existing = domains.data.find(
+        (x) => x.name === domain.toLowerCase()
+      );
+      const added = existing ? await call("GET", `/v1/domains/${existing.id}`, { env }) : await call("POST", "/v1/domains", { env, body: { name: domain } });
+      const key = await call("POST", "/v1/api-keys", {
+        env,
+        body: { name: "Created by sendpanda setup", scope: "send" }
+      });
+      const secret = key.secret ?? key.key;
+      if (str(flags["env-file"]) && secret)
+        await writeFile(
+          str(flags["env-file"]),
+          `SENDPANDA_API_KEY=${secret}
+`,
+          { flag: "a", mode: 384 }
+        );
+      await saveConfig(d, { ...saved, environment: env });
+      d.err(
+        "Add the DNS records below at your DNS provider, then run: sendpanda domains verify <id>\n" + (str(flags["env-file"]) ? `The sending key was appended to ${str(flags["env-file"])}.
+` : "The sending key is shown once below; store it in your secrets manager.\n")
+      );
+      print({
+        environment: env,
+        domain: added,
+        sending_key: str(flags["env-file"]) ? "(written to env file)" : secret
+      });
+      return;
+    }
+    case "mcp":
+      throw new CliError(
+        "Run the MCP server with: SENDPANDA_TOKEN=sp_pat_... npx -y @sendpanda/mcp"
+      );
+    default:
+      throw new CliError(`Unknown command "${command}". Run: sendpanda help`);
+  }
+}
+
+// src/cli.ts
+process.exitCode = await main(process.argv.slice(2));

package/package.json

@@ -1,6 +1,40 @@
 {
   "name": "@sendpanda/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "SendPanda command line: manage every project, domain, key, template and email from a terminal or a coding agent.",
+  "license": "MIT",
+  "engines": {
+    "node": ">=22"
+  },
+  "private": false,
+  "type": "module",
+  "bin": {
+    "sendpanda": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TheBugEater/SendPanda.git",
+    "directory": "packages/cli"
+  },
+  "homepage": "https://sendpanda.email/docs",
+  "keywords": [
+    "sendpanda",
+    "email",
+    "cli",
+    "agent"
+  ],
+  "dependencies": {},
+  "scripts": {
+    "build": "tsup src/cli.ts --format esm --clean",
+    "prepack": "npm run build"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}