@switchboard.spot/cli 0.2.0

package/LICENSE

@@ -0,0 +1,7 @@
+Switchboard CLI Proprietary License Notice
+
+Copyright (c) Switchboard.
+
+This package is proprietary software. You may install and use it to access and
+operate Switchboard services. No other rights are granted except by a separate
+written agreement with Switchboard.

package/README.md

@@ -0,0 +1,95 @@
+# @switchboard.spot/cli
+
+Command-line management for [Switchboard](https://switchboard.spot): account
+auth, project setup, key rotation, integration setup, usage checks, and smoke
+tests.
+
+## Install
+
+```bash
+npm install -g @switchboard.spot/cli
+```
+
+You can also run commands without a global install:
+
+```bash
+npx @switchboard.spot/cli auth login
+```
+
+## Build for local testing
+
+Build an installable npm tarball from the same package files used for publish:
+
+```bash
+npm run build
+npm install -g ./dist/switchboard-cli-*.tgz
+```
+
+The build output is written to `dist/` and is safe to delete.
+
+## Publish to npm
+
+Before publishing, npm requires either an interactive account with 2FA enabled
+or a granular access token with **bypass 2FA** enabled. For token-based
+publishing, create a granular npm token with read/write access for
+`@switchboard.spot/cli`, enable bypass 2FA, then expose it only for the publish
+command:
+
+```bash
+export NPM_TOKEN=npm_...
+npmrc="$(mktemp)"
+printf '//registry.npmjs.org/:_authToken=%s\n' "$NPM_TOKEN" > "$npmrc"
+npm --userconfig "$npmrc" whoami
+npm --userconfig "$npmrc" run publish:dry-run
+npm --userconfig "$npmrc" run publish:npm
+rm "$npmrc"
+```
+
+The package is scoped and public. `publishConfig.access = public` is set in
+`package.json`, and the publish script also passes `--access public` explicitly.
+If a first publish fails, `npm view @switchboard.spot/cli` will continue to return
+404 until a publish succeeds.
+
+## Auth workflow
+
+```bash
+switchboard auth login
+switchboard setup --target client --json
+switchboard chat test --json
+```
+
+Use `--json` for automation, CI, and coding agents.
+
+CLI account login does not create Client Gateway end-user sessions. End-user sign-up, sign-in, and refresh require a real browser/mobile challenge flow; use `@switchboard/sdk` in the app, or use trusted-server/account APIs for automation.
+
+Project-owned browser challenge keys are managed through the CLI:
+
+```bash
+switchboard projects turnstile <project-id> --site-key <site-key> --secret-key <secret-key>
+switchboard projects turnstile <project-id> --clear
+```
+
+## Configuration
+
+The CLI stores non-secret settings in `~/.switchboard/config.json` by default.
+Set `SWITCHBOARD_CONFIG_DIR` to use a different directory.
+
+Environment variables:
+
+| Variable | Purpose |
+| --- | --- |
+| `SWITCHBOARD_BASE_URL` | Switchboard app origin. Defaults to `https://switchboard.spot`; set to `http://localhost:4000` for local development. |
+| `SWITCHBOARD_PROJECT_ID` | Project context for project-scoped commands. |
+| `SWITCHBOARD_API_KEY` | Secret project key for trusted-server gateway smoke tests. |
+| `SWITCHBOARD_CLIENT_URL` | Public Client Gateway URL for browser/mobile end-user auth and chat. |
+| `SWITCHBOARD_END_USER_SESSION` | Existing end-user session for Client Gateway checks; the CLI cannot mint one without browser challenge execution. |
+| `SWITCHBOARD_CONFIG_DIR` | Alternate CLI config directory. |
+
+Account sessions are stored in the OS keychain and are not read from
+environment variables.
+
+## Credential safety
+
+Do not paste `sb_sess_`, `sb_test_`, `sb_live_`, provider keys, private keys, or
+webhook secrets into frontend, mobile, or public code. Browser and mobile code
+should use `SWITCHBOARD_CLIENT_URL` plus end-user sessions.

package/bin/switchboard.js

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+/**
+ * Switchboard CLI — full dashboard parity via the account management API.
+ */
+
+import { Command } from "commander";
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+import { registerCommand as registerAuth } from "../lib/commands/auth.js";
+import { registerAccountCommands } from "../lib/commands/account.js";
+import { registerKeysCommands } from "../lib/commands/keys.js";
+import { registerProjectsCommands } from "../lib/commands/projects.js";
+import { registerWorkspacesCommands } from "../lib/commands/workspaces.js";
+import { registerOrgCommands } from "../lib/commands/org.js";
+import { registerEndUsersCommands } from "../lib/commands/endUsers.js";
+import { registerBillingCommands } from "../lib/commands/billing.js";
+import { registerEnvCommands } from "../lib/commands/env.js";
+import { registerUsageCommands } from "../lib/commands/usage.js";
+import { registerIntegrationCommands } from "../lib/commands/integration.js";
+import { registerInitCommand } from "../lib/commands/init.js";
+import { registerSetupCommand } from "../lib/commands/setup.js";
+import { registerHealthCommand } from "../lib/commands/health.js";
+import { registerDoctorCommand } from "../lib/commands/doctor.js";
+import { registerVerifyCommands } from "../lib/commands/verify.js";
+
+const program = new Command();
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const packageJson = JSON.parse(
+  fs.readFileSync(path.join(__dirname, "../package.json"), "utf8")
+);
+
+program
+  .name("switchboard")
+  .description("Switchboard CLI — manage your workspace from the terminal")
+  .option("--json", "Output JSON to stdout")
+  .option("-q, --quiet", "Suppress non-essential output")
+  .version(packageJson.version);
+
+registerInitCommand(program);
+registerSetupCommand(program);
+registerHealthCommand(program);
+registerDoctorCommand(program);
+registerVerifyCommands(program);
+registerAuth(program);
+registerAccountCommands(program);
+registerWorkspacesCommands(program);
+registerKeysCommands(program);
+registerProjectsCommands(program);
+registerOrgCommands(program);
+registerEndUsersCommands(program);
+registerBillingCommands(program);
+registerEnvCommands(program);
+registerUsageCommands(program);
+registerIntegrationCommands(program);
+
+program.parse();
+
+if (!process.argv.slice(2).length) {
+  program.outputHelp();
+}

package/lib/client.js

@@ -0,0 +1,150 @@
+/**
+ * HTTP client for Switchboard account and gateway APIs.
+ */
+
+import { accountApiUrl, resolveAccountConfig, resolveConfig } from "./config.js";
+import { emitHttpError, fail, normalizeError } from "./output.js";
+
+const PROJECT_SCOPED_ACCOUNT_PATHS = [
+  /^\/keys(?:\/|$)/,
+  /^\/end_users(?:\/|$)/,
+  /^\/billing\/(?:ledger|top_up|prepaid)(?:\/|\?|$)/,
+  /^\/usage(?:\?|$)/,
+  /^\/integration_kit(?:\?|$)/,
+];
+
+/**
+ * Performs an authenticated account API request.
+ */
+export async function accountRequest(method, path, { body, json, config, projectId } = {}) {
+  const { url, init } = await accountRequestConfig(method, path, {
+    body,
+    json,
+    config,
+    projectId,
+  });
+
+  return handleResponse(await fetch(url, init), json);
+}
+
+async function accountRequestConfig(
+  method,
+  path,
+  { body, json, config, projectId, accept = "application/json", requireProjectScope = false } = {},
+) {
+  const cfg = await loadAccountConfig(config, json);
+  const token = requireAccountToken(cfg, json);
+
+  const url = new URL(accountApiUrl(cfg) + path);
+  const selectedProjectId = projectId || cfg.projectId;
+  if (selectedProjectId) {
+    url.searchParams.set("project_id", selectedProjectId);
+  } else if (requireProjectScope || requiresProject(path)) {
+    fail(
+      "Specify a project before this command. Run: switchboard projects list, then switchboard projects use <id>.",
+      1,
+      json,
+    );
+  }
+
+  const headers = {
+    Authorization: `Bearer ${token}`,
+    Accept: accept,
+  };
+
+  if (body) {
+    headers["Content-Type"] = "application/json";
+  }
+
+  return {
+    url,
+    init: {
+      method,
+      headers,
+      body: body ? JSON.stringify(body) : undefined,
+    },
+  };
+}
+
+/**
+ * Performs a public account API request (register, login).
+ */
+export async function accountPublicRequest(method, path, { body, json, config } = {}) {
+  const cfg = config || resolveConfig();
+  const url = accountApiUrl(cfg) + path;
+
+  const res = await fetch(url, {
+    method,
+    headers: {
+      "Content-Type": "application/json",
+      Accept: "application/json",
+    },
+    body: JSON.stringify(body),
+  });
+
+  return handleResponse(res, json);
+}
+
+function requiresProject(path) {
+  return PROJECT_SCOPED_ACCOUNT_PATHS.some((pattern) => pattern.test(path));
+}
+
+async function loadAccountConfig(config, json) {
+  try {
+    return await resolveAccountConfig(config);
+  } catch (error) {
+    fail(
+      error.message || "Could not read Switchboard account session from the OS keychain",
+      2,
+      json,
+      "keychain_unavailable",
+    );
+  }
+}
+
+function requireAccountToken(cfg, json) {
+  if (!cfg.accountToken) {
+    fail(
+      "Not logged in. Run: switchboard auth login and complete sign-in in your browser.",
+      2,
+      json,
+      "authentication_required",
+    );
+  }
+
+  return cfg.accountToken;
+}
+
+/**
+ * GET /health without authentication.
+ */
+export async function healthCheck(config) {
+  const cfg = config || resolveConfig();
+  const url = `${cfg.baseUrl.replace(/\/$/, "")}/health`;
+  const res = await fetch(url);
+  const text = await res.text();
+  let data;
+  try {
+    data = JSON.parse(text);
+  } catch {
+    data = { status: text };
+  }
+  return { ok: res.ok, status: res.status, data };
+}
+
+async function handleResponse(res, jsonMode) {
+  const text = await res.text();
+  let data;
+
+  try {
+    data = text ? JSON.parse(text) : null;
+  } catch {
+    data = { raw: text };
+  }
+
+  if (!res.ok) {
+    emitHttpError(normalizeError(data, text, res.status), res.status, { json: jsonMode });
+  }
+
+  return { ok: true, status: res.status, data };
+}

package/lib/commands/account.js

@@ -0,0 +1,81 @@
+/**
+ * Authenticated account management commands.
+ */
+
+import { accountRequest } from "../client.js";
+import { fail, emit, globalFlags } from "../output.js";
+
+export function registerAccountCommands(program) {
+  const account = program.command("account").description("Account");
+
+  account
+    .command("show")
+    .description("Show the authenticated account")
+    .action(async (_opts, cmd) => {
+      const flags = globalFlags(cmd);
+      const { data } = await accountRequest("GET", "/me", { json: flags.json });
+      emit(flags.json ? data : JSON.stringify(data, null, 2), flags);
+    });
+
+  account
+    .command("update-email")
+    .description("Request an account email change")
+    .requiredOption("--email <email>")
+    .requiredOption("--current-password <password>")
+    .action(async (opts, cmd) => {
+      const flags = globalFlags(cmd);
+      const { data } = await accountRequest("PATCH", "/me", {
+        body: {
+          email: opts.email,
+          current_password: opts.currentPassword,
+        },
+        json: flags.json,
+      });
+      emit(flags.json ? data : "Email confirmation sent", flags);
+    });
+
+  account
+    .command("change-password")
+    .description("Change the account password")
+    .requiredOption("--current-password <password>")
+    .requiredOption("--password <password>")
+    .requiredOption("--password-confirmation <password>")
+    .action(async (opts, cmd) => {
+      const flags = globalFlags(cmd);
+      const { data } = await accountRequest("PATCH", "/me", {
+        body: {
+          current_password: opts.currentPassword,
+          password: opts.password,
+          password_confirmation: opts.passwordConfirmation,
+        },
+        json: flags.json,
+      });
+      emit(flags.json ? data : "Password changed", flags);
+    });
+
+  account
+    .command("delete")
+    .description("Delete the authenticated account")
+    .requiredOption("--confirm <email>")
+    .action(async (opts, cmd) => {
+      const flags = globalFlags(cmd);
+      const { data: accountData } = await accountRequest("GET", "/me", { json: flags.json });
+      const email = accountData?.user?.email;
+
+      if (opts.confirm !== email) {
+        fail("Confirmation email does not match the authenticated account.", 2, flags.json);
+      }
+
+      const { data } = await accountRequest("DELETE", "/me", { json: flags.json });
+      emit(flags.json ? data : `Deleted account ${email}`, flags);
+    });
+
+  account
+    .command("restore")
+    .description("Restore the authenticated account")
+    .action(async (_opts, cmd) => {
+      const flags = globalFlags(cmd);
+      const { data } = await accountRequest("POST", "/me/restore", { json: flags.json });
+      emit(flags.json ? data : `Restored account ${data.user.email}`, flags);
+    });
+}