@sentroy-co/client-sdk 2.8.0 → 2.9.0

package/dist/cli/index.js

@@ -0,0 +1,105 @@
+"use strict";
+/**
+ * `sentroy` — CLI entry point.
+ *
+ * Subcommand router with no third-party deps. Today only `env` exists;
+ * future subcommands (`mail`, `media`, etc.) hook in here.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const env_1 = require("./env");
+const VERSION = "__VERSION__"; // replaced at runtime via package.json read
+const ENV_SUBCOMMANDS = {
+    push: {
+        description: "Push a local .env file to the vault (full sync if --delete-missing)",
+        handler: env_1.cmdPush,
+    },
+    pull: {
+        description: "Fetch the vault scope and write to a local .env file",
+        handler: env_1.cmdPull,
+    },
+    list: {
+        description: "Print every key in the vault scope (--values to include values, --public-only)",
+        handler: env_1.cmdList,
+    },
+    diff: {
+        description: "Show what would change if you pushed the local .env file",
+        handler: env_1.cmdDiff,
+    },
+};
+function readPackageVersion() {
+    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");
+        return version;
+    }
+    catch {
+        return "unknown";
+    }
+}
+function showHelp() {
+    const v = readPackageVersion();
+    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` +
+        `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` +
+        `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`);
+}
+async function main() {
+    const argv = process.argv.slice(2);
+    if (argv.length === 0 ||
+        argv[0] === "-h" ||
+        argv[0] === "--help" ||
+        argv[0] === "help") {
+        showHelp();
+        return;
+    }
+    if (argv[0] === "-v" || argv[0] === "--version") {
+        process.stdout.write(`${readPackageVersion()}\n`);
+        return;
+    }
+    const cmd = argv[0];
+    if (cmd === "env") {
+        const sub = argv[1];
+        const handler = sub ? ENV_SUBCOMMANDS[sub] : undefined;
+        if (!handler) {
+            process.stderr.write(`unknown env subcommand: ${sub ?? "<missing>"}\n` +
+                `available: ${Object.keys(ENV_SUBCOMMANDS).join(", ")}\n`);
+            process.exit(1);
+        }
+        await handler.handler(argv.slice(2));
+        return;
+    }
+    process.stderr.write(`unknown command: ${cmd}\nrun \`sentroy --help\` for usage.\n`);
+    process.exit(1);
+}
+main().catch((err) => {
+    const msg = err instanceof Error ? err.message : String(err);
+    process.stderr.write(`\n\x1b[31m✗\x1b[0m ${msg}\n`);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/cli/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;AAEH,+BAA0D;AAE1D,MAAM,OAAO,GAAG,aAAa,CAAA,CAAC,4CAA4C;AAO1E,MAAM,eAAe,GAA+B;IAClD,IAAI,EAAE;QACJ,WAAW,EAAE,qEAAqE;QAClF,OAAO,EAAE,aAAO;KACjB;IACD,IAAI,EAAE;QACJ,WAAW,EAAE,sDAAsD;QACnE,OAAO,EAAE,aAAO;KACjB;IACD,IAAI,EAAE;QACJ,WAAW,EAAE,gFAAgF;QAC7F,OAAO,EAAE,aAAO;KACjB;IACD,IAAI,EAAE;QACJ,WAAW,EAAE,0DAA0D;QACvE,OAAO,EAAE,aAAO;KACjB;CACF,CAAA;AAED,SAAS,kBAAkB;IACzB,IAAI,OAAO,KAAK,aAAa;QAAE,OAAO,OAAO,CAAA;IAC7C,yEAAyE;IACzE,IAAI,CAAC;QACH,iEAAiE;QACjE,MAAM,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,oBAAoB,CAAwB,CAAA;QACxE,OAAO,OAAO,CAAA;IAChB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAA;IAClB,CAAC;AACH,CAAC;AAED,SAAS,QAAQ;IACf,MAAM,CAAC,GAAG,kBAAkB,EAAE,CAAA;IAC9B,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,aAAa,CAAC,oBAAoB;QAChC,SAAS;QACT,wCAAwC;QACxC,YAAY;QACZ,4BAA4B,eAAe,CAAC,IAAI,CAAC,WAAW,IAAI;QAChE,4BAA4B,eAAe,CAAC,IAAI,CAAC,WAAW,IAAI;QAChE,4BAA4B,eAAe,CAAC,IAAI,CAAC,WAAW,IAAI;QAChE,4BAA4B,eAAe,CAAC,IAAI,CAAC,WAAW,MAAM;QAClE,gBAAgB;QAChB,wEAAwE;QACxE,sGAAsG;QACtG,kBAAkB;QAClB,wFAAwF;QACxF,4DAA4D;QAC5D,gFAAgF;QAChF,kBAAkB;QAClB,sEAAsE;QACtE,kBAAkB;QAClB,gEAAgE;QAChE,2DAA2D;QAC3D,YAAY;QACZ,uDAAuD;QACvD,mCAAmC;QACnC,uDAAuD;QACvD,+CAA+C;QAC/C,yEAAyE;QACzE,8BAA8B,CACjC,CAAA;AACH,CAAC;AAED,KAAK,UAAU,IAAI;IACjB,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAA;IAClC,IACE,IAAI,CAAC,MAAM,KAAK,CAAC;QACjB,IAAI,CAAC,CAAC,CAAC,KAAK,IAAI;QAChB,IAAI,CAAC,CAAC,CAAC,KAAK,QAAQ;QACpB,IAAI,CAAC,CAAC,CAAC,KAAK,MAAM,EAClB,CAAC;QACD,QAAQ,EAAE,CAAA;QACV,OAAM;IACR,CAAC;IACD,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,IAAI,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,WAAW,EAAE,CAAC;QAChD,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,kBAAkB,EAAE,IAAI,CAAC,CAAA;QACjD,OAAM;IACR,CAAC;IAED,MAAM,GAAG,GAAG,IAAI,CAAC,CAAC,CAAC,CAAA;IACnB,IAAI,GAAG,KAAK,KAAK,EAAE,CAAC;QAClB,MAAM,GAAG,GAAG,IAAI,CAAC,CAAC,CAAC,CAAA;QACnB,MAAM,OAAO,GAAG,GAAG,CAAC,CAAC,CAAC,eAAe,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAA;QACtD,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,2BAA2B,GAAG,IAAI,WAAW,IAAI;gBAC/C,cAAc,MAAM,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAC5D,CAAA;YACD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;QACjB,CAAC;QACD,MAAM,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAA;QACpC,OAAM;IACR,CAAC;IAED,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,oBAAoB,GAAG,uCAAuC,CAC/D,CAAA;IACD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;AACjB,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE;IAC5B,MAAM,GAAG,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;IAC5D,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,sBAAsB,GAAG,IAAI,CAAC,CAAA;IACnD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;AACjB,CAAC,CAAC,CAAA"}

package/package.json

@@ -1,9 +1,12 @@
 {
   "name": "@sentroy-co/client-sdk",
-  "version": "2.8.0",
-  "description": "TypeScript SDK for the Sentroy platform — mail, storage, env vault + React components.",
+  "version": "2.9.0",
+  "description": "TypeScript SDK + CLI for the Sentroy platform — mail, storage, env vault + React components.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
+  "bin": {
+    "sentroy": "./bin/sentroy.js"
+  },
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -39,6 +42,7 @@
   "files": [
     "dist",
     "src",
+    "bin",
     "AGENTS.md"
   ],
   "scripts": {
@@ -57,7 +61,9 @@
     "env",
     "vault",
     "secrets",
-    "config"
+    "config",
+    "cli",
+    "dotenv"
   ],
   "repository": {
     "type": "git",

package/src/cli/dotenv.ts

@@ -0,0 +1,146 @@
+/**
+ * Minimal .env parser + serializer used by the CLI.
+ *
+ * Format conventions (mirrors apps/core/components/admin/env-vault-content.tsx
+ * developer mode):
+ *   - blank line resets pending description/public flag
+ *   - `# @public` on its own line marks the next variable as browser-readable
+ *   - `# any other text` becomes the next variable's description
+ *   - `KEY=value`               (unquoted)
+ *   - `KEY="value with spaces"` (double-quoted; supports \n, \", \\ escapes)
+ *   - `KEY='single quotes'`     (single-quoted; literal)
+ *   - `export KEY=value`        (export prefix stripped)
+ *
+ * Anything else is reported as a parse error with the offending line number.
+ */
+
+export interface DotenvEntry {
+  key: string
+  value: string
+  public: boolean
+  description: string | null
+}
+
+export interface DotenvParseResult {
+  entries: DotenvEntry[]
+  errors: { line: number; message: string }[]
+}
+
+const KEY_PATTERN = /^[A-Z_][A-Z0-9_]*$/
+
+export function parseDotenv(text: string): DotenvParseResult {
+  const lines = text.split(/\r?\n/)
+  const entries: DotenvEntry[] = []
+  const errors: DotenvParseResult["errors"] = []
+  const seen = new Set<string>()
+
+  let pendingDescription: string[] = []
+  let pendingPublic = false
+
+  for (let i = 0; i < lines.length; i++) {
+    const raw = lines[i] ?? ""
+    const line = raw.trim()
+
+    if (line === "") {
+      pendingDescription = []
+      pendingPublic = false
+      continue
+    }
+
+    if (line.startsWith("#")) {
+      const body = line.slice(1).trim()
+      if (body === "@public") {
+        pendingPublic = true
+      } else if (body) {
+        pendingDescription.push(body)
+      }
+      continue
+    }
+
+    const work = line.startsWith("export ") ? line.slice(7).trimStart() : line
+    const eq = work.indexOf("=")
+    if (eq <= 0) {
+      errors.push({
+        line: i + 1,
+        message: "invalid syntax (expected KEY=value)",
+      })
+      pendingDescription = []
+      pendingPublic = false
+      continue
+    }
+
+    const key = work.slice(0, eq).trim()
+    let value = work.slice(eq + 1)
+
+    if (!KEY_PATTERN.test(key)) {
+      errors.push({
+        line: i + 1,
+        message: "key must match [A-Z_][A-Z0-9_]*",
+      })
+      pendingDescription = []
+      pendingPublic = false
+      continue
+    }
+
+    const trimmed = value.trim()
+    if (
+      (trimmed.startsWith('"') && trimmed.endsWith('"')) ||
+      (trimmed.startsWith("'") && trimmed.endsWith("'"))
+    ) {
+      value = trimmed.slice(1, -1)
+      if (trimmed.startsWith('"')) {
+        value = value
+          .replace(/\\n/g, "\n")
+          .replace(/\\"/g, '"')
+          .replace(/\\\\/g, "\\")
+      }
+    } else {
+      value = trimmed
+    }
+
+    if (seen.has(key)) {
+      errors.push({ line: i + 1, message: `duplicate key ${key}` })
+      pendingDescription = []
+      pendingPublic = false
+      continue
+    }
+    seen.add(key)
+
+    entries.push({
+      key,
+      value,
+      public: pendingPublic,
+      description:
+        pendingDescription.length > 0 ? pendingDescription.join(" ") : null,
+    })
+
+    pendingDescription = []
+    pendingPublic = false
+  }
+
+  return { entries, errors }
+}
+
+/**
+ * Inverse of parseDotenv — emit a .env document that round-trips through it.
+ * Quotes values that contain whitespace or shell-special characters.
+ */
+export function serializeDotenv(entries: DotenvEntry[]): string {
+  const blocks: string[] = []
+  for (const e of entries) {
+    const parts: string[] = []
+    if (e.description) parts.push(`# ${e.description}`)
+    if (e.public) parts.push("# @public")
+    const value = e.value
+    const needsQuote = /[\s"'#$`\\]/.test(value) || value === ""
+    const escaped = needsQuote
+      ? `"${value
+          .replace(/\\/g, "\\\\")
+          .replace(/"/g, '\\"')
+          .replace(/\n/g, "\\n")}"`
+      : value
+    parts.push(`${e.key}=${escaped}`)
+    blocks.push(parts.join("\n"))
+  }
+  return blocks.join("\n\n") + (blocks.length > 0 ? "\n" : "")
+}

package/src/cli/env.ts

@@ -0,0 +1,402 @@
+/**
+ * `sentroy env <subcommand>` — vault sync from a local .env file.
+ *
+ * The token's (project, environment) scope is implicit; the CLI never
+ * asks for either since it can't change them.
+ */
+
+import * as fs from "fs"
+import * as path from "path"
+import * as readline from "readline"
+import {
+  parseDotenv,
+  serializeDotenv,
+  type DotenvEntry,
+} from "./dotenv"
+
+const DEFAULT_FILE = ".env"
+const DEFAULT_BASE_URL = "https://sentroy.com"
+
+interface SharedOpts {
+  token: string
+  baseUrl: string
+}
+
+interface RemoteVariable {
+  key: string
+  value: string
+  type: string
+  public: boolean
+}
+
+interface PushResponse {
+  project: string
+  environment: string
+  added: number
+  updated: number
+  unchanged: number
+  deleted: number
+  total: number
+}
+
+interface FetchResponse {
+  project: string
+  environment: string
+  variables: RemoteVariable[]
+}
+
+// ── ANSI helpers (no deps) ───────────────────────────────────────────────
+const supportsColor = process.stdout.isTTY && process.env.TERM !== "dumb"
+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),
+}
+
+function fail(msg: string): never {
+  process.stderr.write(`${c.red("✗")} ${msg}\n`)
+  process.exit(1)
+}
+
+function info(msg: string): void {
+  process.stdout.write(`${c.cyan("→")} ${msg}\n`)
+}
+
+function ok(msg: string): void {
+  process.stdout.write(`${c.green("✓")} ${msg}\n`)
+}
+
+function warn(msg: string): void {
+  process.stdout.write(`${c.yellow("⚠")} ${msg}\n`)
+}
+
+function resolveSharedOpts(rest: Record<string, string | boolean>): SharedOpts {
+  const token =
+    (typeof rest.token === "string" ? rest.token : null) ??
+    process.env.SENTROY_ENV_API_KEY ??
+    null
+  if (!token) {
+    fail(
+      "no token. Pass --token=stk_env_... or set SENTROY_ENV_API_KEY in your environment.",
+    )
+  }
+  const baseUrl =
+    (typeof rest.url === "string" ? rest.url : null) ??
+    process.env.SENTROY_ENV_API_URL ??
+    DEFAULT_BASE_URL
+  return { token, baseUrl: baseUrl.replace(/\/+$/, "") }
+}
+
+async function http<T>(
+  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) {
+    const errMsg =
+      body && typeof body === "object" && "error" in body
+        ? String((body as { error: unknown }).error)
+        : `HTTP ${res.status}`
+    throw new Error(`${path}: ${errMsg}`)
+  }
+  return (body as { data?: T })?.data as T
+}
+
+function readFileOrFail(file: string): string {
+  if (!fs.existsSync(file)) {
+    fail(`file not found: ${file}`)
+  }
+  return fs.readFileSync(file, "utf8")
+}
+
+interface Diff {
+  added: DotenvEntry[]
+  updated: { entry: DotenvEntry; remote: RemoteVariable }[]
+  unchanged: { entry: DotenvEntry; remote: RemoteVariable }[]
+  deleted: RemoteVariable[]
+}
+
+function computeDiff(
+  local: DotenvEntry[],
+  remote: RemoteVariable[],
+): Diff {
+  const remoteByKey = new Map(remote.map((v) => [v.key, v]))
+  const added: DotenvEntry[] = []
+  const updated: Diff["updated"] = []
+  const unchanged: Diff["unchanged"] = []
+  for (const e of local) {
+    const r = remoteByKey.get(e.key)
+    if (!r) {
+      added.push(e)
+      continue
+    }
+    if (r.value !== e.value || r.public !== e.public) {
+      updated.push({ entry: e, remote: r })
+    } else {
+      unchanged.push({ entry: e, remote: r })
+    }
+  }
+  const localKeys = new Set(local.map((e) => e.key))
+  const deleted = remote.filter((v) => !localKeys.has(v.key))
+  return { added, updated, unchanged, deleted }
+}
+
+function printDiff(diff: Diff, deleteMissing: boolean): void {
+  for (const e of diff.added) {
+    process.stdout.write(`  ${c.green("+")} ${e.key}\n`)
+  }
+  for (const u of diff.updated) {
+    process.stdout.write(`  ${c.yellow("~")} ${u.entry.key}\n`)
+  }
+  if (deleteMissing) {
+    for (const d of diff.deleted) {
+      process.stdout.write(`  ${c.red("-")} ${d.key}\n`)
+    }
+  } else if (diff.deleted.length > 0) {
+    process.stdout.write(
+      `  ${c.dim(`(${diff.deleted.length} key(s) only in vault, kept — pass --delete-missing to remove)`)}\n`,
+    )
+  }
+}
+
+async function confirm(question: string): Promise<boolean> {
+  if (!process.stdin.isTTY) return false
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  })
+  const answer = await new Promise<string>((resolve) => {
+    rl.question(`${question} [y/N] `, (ans) => {
+      rl.close()
+      resolve(ans.trim().toLowerCase())
+    })
+  })
+  return answer === "y" || answer === "yes"
+}
+
+// ── push ─────────────────────────────────────────────────────────────────
+
+export async function cmdPush(args: string[]): Promise<void> {
+  const { positional, flags } = parseFlags(args)
+  const file = positional[0] ?? DEFAULT_FILE
+  const dryRun = !!flags["dry-run"]
+  const deleteMissing = !!flags["delete-missing"]
+  const shared = resolveSharedOpts(flags)
+
+  const text = readFileOrFail(path.resolve(process.cwd(), file))
+  const parsed = parseDotenv(text)
+  if (parsed.errors.length > 0) {
+    process.stderr.write(`${c.red("✗")} parse errors in ${file}:\n`)
+    for (const err of parsed.errors) {
+      process.stderr.write(`    line ${err.line}: ${err.message}\n`)
+    }
+    process.exit(1)
+  }
+
+  info(`fetching current vault snapshot…`)
+  const remote = await http<FetchResponse>(shared, "/api/env-vault/fetch")
+  const diff = computeDiff(parsed.entries, remote.variables)
+
+  process.stdout.write(
+    `\n${c.bold(remote.project)} ${c.dim("/")} ${c.magenta(remote.environment)} ${c.dim(
+      `(${file} → ${shared.baseUrl})`,
+    )}\n`,
+  )
+  printDiff(diff, deleteMissing)
+  process.stdout.write(
+    `\n  ${c.dim("summary:")} ${diff.added.length} new · ${diff.updated.length} updated · ${diff.unchanged.length} unchanged${
+      deleteMissing ? ` · ${diff.deleted.length} to delete` : ""
+    }\n\n`,
+  )
+
+  if (
+    diff.added.length === 0 &&
+    diff.updated.length === 0 &&
+    (!deleteMissing || diff.deleted.length === 0)
+  ) {
+    ok("nothing to push.")
+    return
+  }
+
+  if (dryRun) {
+    info("dry run — no changes pushed.")
+    return
+  }
+
+  if (deleteMissing && diff.deleted.length > 0) {
+    if (flags.yes) {
+      info(`--yes provided, skipping confirmation for ${diff.deleted.length} delete(s).`)
+    } else if (!process.stdin.isTTY) {
+      fail(
+        `refusing to delete ${diff.deleted.length} key(s) without --yes in a non-interactive shell.`,
+      )
+    } else {
+      const proceed = await confirm(
+        `${c.yellow("⚠")} this will delete ${diff.deleted.length} key(s) from the vault. continue?`,
+      )
+      if (!proceed) {
+        warn("aborted.")
+        return
+      }
+    }
+  }
+
+  const result = await http<PushResponse>(shared, "/api/env-vault/push", {
+    method: "POST",
+    body: JSON.stringify({
+      entries: parsed.entries.map((e) => ({
+        key: e.key,
+        value: e.value,
+        public: e.public,
+        description: e.description,
+      })),
+      deleteMissing,
+    }),
+  })
+  ok(
+    `${result.added} added · ${result.updated} updated · ${result.unchanged} unchanged · ${result.deleted} deleted`,
+  )
+}
+
+// ── pull ─────────────────────────────────────────────────────────────────
+
+export async function cmdPull(args: string[]): Promise<void> {
+  const { positional, flags } = parseFlags(args)
+  const file = positional[0] ?? DEFAULT_FILE
+  const force = !!flags.force
+  const shared = resolveSharedOpts(flags)
+
+  const target = path.resolve(process.cwd(), file)
+  if (fs.existsSync(target) && !force) {
+    fail(`${file} already exists. Pass --force to overwrite.`)
+  }
+
+  info(`fetching from ${shared.baseUrl}…`)
+  const remote = await http<FetchResponse>(shared, "/api/env-vault/fetch")
+  const entries: DotenvEntry[] = remote.variables.map((v) => ({
+    key: v.key,
+    value: v.value,
+    public: v.public,
+    description: null,
+  }))
+  const text = serializeDotenv(entries)
+  fs.writeFileSync(target, text, "utf8")
+  ok(
+    `wrote ${entries.length} variable(s) to ${file} (${remote.project}/${remote.environment})`,
+  )
+}
+
+// ── list ─────────────────────────────────────────────────────────────────
+
+export async function cmdList(args: string[]): Promise<void> {
+  const { flags } = parseFlags(args)
+  const showValues = !!flags.values
+  const publicOnly = !!flags["public-only"]
+  const shared = resolveSharedOpts(flags)
+
+  const endpoint = publicOnly ? "/api/env-vault/public" : "/api/env-vault/fetch"
+  const remote = await http<FetchResponse>(shared, endpoint)
+  process.stdout.write(
+    `${c.bold(remote.project)} ${c.dim("/")} ${c.magenta(remote.environment)} ${c.dim(`(${remote.variables.length} variable(s))`)}\n`,
+  )
+  for (const v of remote.variables) {
+    const tag = v.public ? c.dim(" [public]") : ""
+    if (showValues) {
+      process.stdout.write(`  ${c.cyan(v.key)}=${v.value}${tag}\n`)
+    } else {
+      process.stdout.write(`  ${c.cyan(v.key)}${tag}\n`)
+    }
+  }
+}
+
+// ── diff ─────────────────────────────────────────────────────────────────
+
+export async function cmdDiff(args: string[]): Promise<void> {
+  const { positional, flags } = parseFlags(args)
+  const file = positional[0] ?? DEFAULT_FILE
+  const deleteMissing = !!flags["delete-missing"]
+  const shared = resolveSharedOpts(flags)
+
+  const text = readFileOrFail(path.resolve(process.cwd(), file))
+  const parsed = parseDotenv(text)
+  if (parsed.errors.length > 0) {
+    process.stderr.write(`${c.red("✗")} parse errors in ${file}:\n`)
+    for (const err of parsed.errors) {
+      process.stderr.write(`    line ${err.line}: ${err.message}\n`)
+    }
+    process.exit(1)
+  }
+  const remote = await http<FetchResponse>(shared, "/api/env-vault/fetch")
+  const diff = computeDiff(parsed.entries, remote.variables)
+
+  process.stdout.write(
+    `${c.bold(remote.project)} ${c.dim("/")} ${c.magenta(remote.environment)} ${c.dim(`(${file} vs vault)`)}\n`,
+  )
+  printDiff(diff, deleteMissing)
+  process.stdout.write(
+    `\n  ${c.dim("summary:")} ${diff.added.length} new · ${diff.updated.length} updated · ${diff.unchanged.length} unchanged · ${diff.deleted.length} only in vault\n`,
+  )
+}
+
+// ── flag parser ──────────────────────────────────────────────────────────
+
+interface ParsedArgs {
+  positional: string[]
+  flags: Record<string, string | boolean>
+}
+
+/**
+ * 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. Keeping this explicit avoids the classic argv
+ * bug where `--dry-run /path/to/file` swallows the positional.
+ */
+const VALUE_FLAGS = new Set(["token", "url"])
+
+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 }
+}