sanctum-cli 0.1.0

package/DEMO.md

@@ -0,0 +1,172 @@
+# Sanctum CLI — Demo
+
+A complete walkthrough of the developer workflow: from a bare machine to an app
+running with injected secrets. No `.env` files involved.
+
+## 0. Prerequisites
+
+```bash
+npm install -g @sanctum/cli
+sanctum --help
+```
+
+## 1. Log in (once per machine)
+
+Machine identity (recommended for CI and dev machines):
+
+```bash
+sanctum login \
+  --client-id d8421d28-3f27-4f44-944d-476ba61063da \
+  --client-secret <your-secret> \
+  --base-url https://sanctum.example.com
+```
+
+```
+Logged in with Universal Auth (https://sanctum.example.com) as profile "default".
+```
+
+Or a user token:
+
+```bash
+sanctum login --token <token> --base-url https://sanctum.example.com
+```
+
+Credentials land in `~/.sanctum/credentials.json` (mode 600). Nothing is
+written to your project yet.
+
+Need a second identity on the same machine? Add a named profile:
+
+```bash
+sanctum login --client-id <ci-bot-id> --client-secret <ci-bot-secret> --profile ci-bot
+sanctum profiles
+```
+
+```
+* default              https://sanctum.example.com
+  ci-bot               https://sanctum.example.com
+```
+
+## 2. Discover what you can access
+
+```bash
+sanctum projects list
+```
+
+```
+rim-api-mf6-x                    RimAPI  ef120ef1-8ae8-4c6b-8547-eb010073fb4f
+```
+
+## 3. Link a folder to a project (once per repo/app)
+
+```bash
+cd ~/work/rim-api
+sanctum init --project rim-api-mf6-x --env dev --path /
+```
+
+```
+Wrote /home/you/work/rim-api/sanctum-config.json
+  project:     rim-api-mf6-x
+  environment: dev
+  secretPath:  /
+```
+
+`sanctum-config.json`:
+
+```json
+{
+  "projectSlug": "rim-api-mf6-x",
+  "environment": "dev",
+  "secretPath": "/"
+}
+```
+
+**Commit this file.** It contains no secrets — just routing. Every developer
+or CI agent that clones the repo gets the same wiring and supplies their own
+credentials.
+
+## 4. Day-to-day usage
+
+```bash
+sanctum envs                      # dev, staging, prod
+sanctum secrets list              # keys only, never values
+sanctum secrets set DB_URL=postgres://localhost:5432/app
+sanctum secrets get DB_URL        # prints the value
+sanctum secrets rm DB_URL
+```
+
+### Run your app with secrets injected
+
+```bash
+sanctum run -- npm run dev
+sanctum run -- node server.js
+sanctum run --env staging -- ./deploy.sh
+```
+
+Your app reads `process.env.DB_URL` like normal. Secrets exist only in the
+child process environment — nothing touches disk.
+
+### Export when you actually need a file
+
+```bash
+sanctum export                     # dotenv to stdout
+sanctum export --format json
+sanctum export --out .env.local    # opt-in, not the default flow
+```
+
+### Push an existing .env up
+
+```bash
+sanctum push .env
+```
+
+```
+Pushed 14 secrets to /
+```
+
+## 5. Monorepo layout
+
+```
+my-mono/
+├── sanctum-config.json        # { projectSlug: "my-mono", secretPath: "/shared" }
+├── apps/
+│   ├── api/
+│   │   └── sanctum-config.json    # { secretPath: "/apps/api", imports: [] }
+│   └── web/
+│       └── sanctum-config.json    # { secretPath: "/apps/web" }
+└── .env.example
+```
+
+Commands walk up from `cwd` and merge root → leaf. Inside `apps/api`, the CLI
+fetches `/shared` first, then `/apps/api` — the deeper path wins on key
+conflicts. Project/env inherit from the nearest config.
+
+## 6. CI / machines
+
+No credentials file needed — use env vars:
+
+```bash
+export SANCTUM_CLIENT_ID=...
+export SANCTUM_CLIENT_SECRET=...
+export SANCTUM_BASE_URL=https://sanctum.example.com
+# or a raw token: export SANCTUM_TOKEN=...
+
+sanctum run -- npm start
+```
+
+Or target a stored profile:
+
+```bash
+sanctum secrets list --profile ci-bot
+```
+
+Profile resolution order: `--profile` flag > `SANCTUM_PROFILE` env >
+`"profile"` in `sanctum-config.json` > `"default"`.
+
+## 7. Troubleshooting
+
+| Symptom | Fix |
+| --- | --- |
+| `error: Not logged in...` | `sanctum login` or set `SANCTUM_TOKEN` / `SANCTUM_CLIENT_*` |
+| `Folder with path '/x' was not found` | Create the folder in the UI, or `--path /` |
+| Wrong project | `cd` into the folder with the right `sanctum-config.json` |
+| Check who you're acting as | `sanctum whoami` |

package/README.md

@@ -0,0 +1,110 @@
+# @sanctum/cli
+
+Command-line client for the Sanctum secrets platform.
+
+## Install
+
+```bash
+cd packages/sdk && npm install && npm run build
+cd ../cli && npm install && npm run build
+npm link            # puts `sanctum` on your PATH
+```
+
+## Quick start
+
+```bash
+# 1. log in — interactive wizard, or pass credentials
+sanctum login
+sanctum login --client-id <id> --client-secret <secret> [--profile name]
+
+# 2. link the current directory — pick a project or create one
+cd my-app
+sanctum init
+
+# 3. use it
+sanctum secrets list
+sanctum secrets set API_KEY=abc123
+sanctum run -- npm run dev
+```
+
+## Commands
+
+| Command | Description |
+| --- | --- |
+| `sanctum login` | 4-step wizard (URL → method → credentials → profile) or `--token` / `--client-id` + `--client-secret` flags |
+| `sanctum profiles` | List saved credential profiles |
+| `sanctum whoami` | Show profile, identity, org, and token validity |
+| `sanctum --version` | Print CLI version |
+| `sanctum init [--project x] [--env x] [--path x] [--imports a,b] [--profile x] [--force]` | Write `sanctum-config.json`; interactive picker when flags omitted; refuses to overwrite without `--force` |
+| `sanctum status` | Show resolved config + linked monorepo projects |
+| `sanctum agents` | Append a Sanctum usage section to `./AGENTS.md` |
+| `sanctum projects list` | List accessible projects |
+| `sanctum envs` | List environments of the configured project |
+| `sanctum secrets list\|get\|set\|rm` | Read/write secrets (`--env`, `--path`, `--profile`); reports queued-for-approval writes |
+| `sanctum export [--env x] [--format dotenv\|json] [--out file]` | Dump merged secrets |
+| `sanctum diff [file] [--env x] [--values] [--all]` | Masked local-vs-remote comparison; monorepo picker at repo root |
+| `sanctum pull [file] [--env x] [--all] [--yes]` | Merge remote secrets into a local file (updates in place, appends new, keeps local-only) |
+| `sanctum push [file] [--env x] [--dry-run] [--yes]` | Preview-then-push `.env` keys into your `secretPath` |
+| `sanctum run [--env x] -- <cmd>` | Run a command with secrets injected as env vars |
+
+## Config discovery
+
+Commands find the nearest `sanctum-config.json` walking up from the current
+directory. Ancestor configs merge in root → leaf order, so a monorepo can keep
+shared secrets at the root and per-app folders in subdirectories:
+
+```json
+{
+  "projectSlug": "my-mono",
+  "environment": "dev",
+  "secretPath": "/apps/api",
+  "imports": ["/shared"],
+  "profile": "deploy-bot"
+}
+```
+
+Merge precedence for keys: root paths first, leaf paths last (deepest wins).
+
+### Monorepo tracking
+
+Run `sanctum init` in a subdirectory of a linked repo and the outermost config
+gains a `projects` index:
+
+```json
+{
+  "projectSlug": "my-mono",
+  "secretPath": "/shared",
+  "projects": {
+    "apps/api": "apps/api/sanctum-config.json",
+    "apps/web": "apps/web/sanctum-config.json"
+  }
+}
+```
+
+`sanctum status` at the root lists every linked project; `sanctum diff` and
+`sanctum pull` offer a picker (`All` / per-child) or take `--all`.
+
+## CI / non-interactive
+
+All wizards skip prompts when stdin is not a TTY. Pass flags instead, and use
+`--yes`/`--force` for confirmation gates (`push`, `pull` into an existing file,
+`init` overwrite).
+
+## Credentials
+
+Secrets never go in `sanctum-config.json` — it is safe to commit. Credentials
+live in `~/.sanctum/credentials.json` (mode 600), keyed by profile:
+
+```json
+{
+  "default": "default",
+  "profiles": {
+    "default": { "baseUrl": "http://localhost:4000", "accessToken": "..." },
+    "deploy-bot": { "baseUrl": "...", "clientId": "...", "clientSecret": "..." }
+  }
+}
+```
+
+Resolution order: `--profile` flag > `SANCTUM_PROFILE` env > `sanctum-config.json` `"profile"` > `"default"`.
+
+Env-var auth (CI): `SANCTUM_TOKEN`, or `SANCTUM_CLIENT_ID` + `SANCTUM_CLIENT_SECRET` (+ `SANCTUM_BASE_URL`).

package/dist/cli.js

@@ -0,0 +1,735 @@
+#!/usr/bin/env node
+import { spawn } from "node:child_process";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { basename, dirname, join } from "node:path";
+import { SanctumApiError, SanctumSdk } from "sanctum-sdk";
+import { listProfiles, loadCredentials, registerChildConfig, resolveConfig, saveCredentials, writeProjectConfig } from "./config.js";
+import { input, password, select } from "./prompt.js";
+const require = createRequire(import.meta.url);
+const VERSION = require("../package.json").version;
+const useColor = process.stdout.isTTY && !process.env.NO_COLOR;
+const c = (code, s) => (useColor ? `[${code}m${s}` : String(s));
+const bold = (s) => c("1", s);
+const dim = (s) => c("2", s);
+const green = (s) => c("32", s);
+const yellow = (s) => c("33", s);
+const red = (s) => c("31", s);
+const cyan = (s) => c("36", s);
+const die = (message, code = 1) => {
+    console.error(`${red("✗")} ${message}`);
+    process.exit(code);
+};
+const ok = (message) => console.log(`${green("✓")} ${message}`);
+/** Decode a JWT payload without verification — display only. */
+const decodeJwtPayload = (token) => {
+    try {
+        const part = token.split(".")[1];
+        return JSON.parse(Buffer.from(part, "base64url").toString("utf8"));
+    }
+    catch {
+        return null;
+    }
+};
+const takeFlag = (args, name) => {
+    const idx = args.indexOf(name);
+    if (idx === -1)
+        return undefined;
+    const value = args[idx + 1];
+    args.splice(idx, 2);
+    return value;
+};
+const hasFlag = (args, name) => {
+    const idx = args.indexOf(name);
+    if (idx === -1)
+        return false;
+    args.splice(idx, 1);
+    return true;
+};
+const getClient = async (profile) => {
+    const credentials = loadCredentials(profile);
+    if (!credentials) {
+        return die("Not logged in. Run `sanctum login`, or set SANCTUM_TOKEN / SANCTUM_CLIENT_ID + SANCTUM_CLIENT_SECRET.");
+    }
+    const sdk = new SanctumSdk({
+        baseUrl: credentials.baseUrl,
+        accessToken: credentials.accessToken,
+        clientId: credentials.clientId,
+        clientSecret: credentials.clientSecret
+    });
+    if (!sdk.accessToken) {
+        await sdk.authenticate();
+    }
+    return sdk;
+};
+const scopeQuery = (config, secretPath, env) => ({
+    workspaceId: config.projectId,
+    workspaceSlug: config.projectSlug,
+    projectSlug: config.projectSlug,
+    environment: env ?? config.environment ?? "dev",
+    secretPath
+});
+/** Fetch and merge secrets across all resolved paths; last path wins on conflicts. */
+const fetchMergedSecrets = async (sdk, config, env) => {
+    const merged = {};
+    for (const path of config.paths) {
+        const { secrets, imports } = await sdk.secrets.list({
+            ...scopeQuery(config, path, env),
+            viewSecretValue: true,
+            expandSecretReferences: true,
+            include_imports: true
+        });
+        for (const imp of imports ?? []) {
+            for (const s of imp.secrets)
+                merged[s.secretKey] = s.secretValue ?? "";
+        }
+        for (const s of secrets)
+            merged[s.secretKey] = s.secretValue ?? "";
+    }
+    return merged;
+};
+// ---------- commands ----------
+const cmdLogin = async (args) => {
+    let baseUrl = takeFlag(args, "--base-url");
+    let token = takeFlag(args, "--token");
+    let clientId = takeFlag(args, "--client-id");
+    let clientSecret = takeFlag(args, "--client-secret");
+    let profile = takeFlag(args, "--profile");
+    if (!token && !(clientId && clientSecret)) {
+        if (!process.stdin.isTTY) {
+            die("Provide --token, or --client-id + --client-secret.");
+        }
+        const step = (n, total, label) => console.log(`\n[${n}/${total}] ${label}`);
+        step(1, 4, "Sanctum instance");
+        baseUrl = baseUrl ?? (await input("URL", "http://localhost:4000"));
+        step(2, 4, "Login method");
+        const method = await select("How do you want to log in?", [
+            { label: "Machine identity", value: "ua", hint: "clientId + clientSecret — recommended for dev/CI" },
+            { label: "Access token", value: "token", hint: "paste a user or identity token" }
+        ]);
+        step(3, 4, "Credentials");
+        if (method === "ua") {
+            clientId = await input("Client ID");
+            clientSecret = await password("Client secret");
+        }
+        else {
+            token = await password("Access token");
+        }
+        if (!token && !(clientId && clientSecret))
+            die("Login aborted.");
+        step(4, 4, "Profile name");
+        profile = profile ?? (await input("Profile", "default"));
+    }
+    baseUrl = baseUrl ?? "http://localhost:4000";
+    profile = profile ?? "default";
+    const credentials = { baseUrl, accessToken: token, clientId, clientSecret };
+    if (clientId && clientSecret) {
+        const sdk = new SanctumSdk({ baseUrl, clientId, clientSecret });
+        const tokens = await sdk.authenticate();
+        saveCredentials({ ...credentials, accessToken: tokens.accessToken }, profile);
+        console.log(`Logged in with Universal Auth (${baseUrl}) as profile "${profile}".`);
+    }
+    else {
+        saveCredentials(credentials, profile);
+        console.log(`Token saved (${baseUrl}) as profile "${profile}".`);
+    }
+};
+/** Normalize a name for fuzzy matching: lowercase, strip non-alphanumerics. */
+const normalize = (s) => s.toLowerCase().replace(/[^a-z0-9]/g, "");
+/** Best-effort local project name: package.json "name" > git remote repo name > directory name. */
+const detectLocalName = () => {
+    try {
+        const pkg = join(process.cwd(), "package.json");
+        if (existsSync(pkg)) {
+            const name = JSON.parse(readFileSync(pkg, "utf8")).name;
+            if (name)
+                return name.replace(/^@[^/]+\//, "");
+        }
+    }
+    catch { /* fall through */ }
+    try {
+        const gitConfig = join(process.cwd(), ".git", "config");
+        if (existsSync(gitConfig)) {
+            const m = readFileSync(gitConfig, "utf8").match(/url\s*=\s*.+\/([^/\s]+?)(?:\.git)?\s*$/m);
+            if (m?.[1])
+                return m[1];
+        }
+    }
+    catch { /* fall through */ }
+    return basename(process.cwd());
+};
+const cmdInit = async (args) => {
+    let project = takeFlag(args, "--project");
+    let environment = takeFlag(args, "--env");
+    let secretPath = takeFlag(args, "--path");
+    const profile = takeFlag(args, "--profile");
+    const imports = (takeFlag(args, "--imports") ?? "")
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean);
+    // non-interactive path: --project is enough to write the config
+    if (project && !environment)
+        environment = "dev";
+    if (project && !secretPath)
+        secretPath = "/";
+    const interactive = process.stdin.isTTY && (!project || !environment || !secretPath);
+    if (interactive) {
+        const sdk = await getClient(profile);
+        if (!project) {
+            const { projects } = await sdk.projects.list();
+            const mode = await select("Project", [
+                { label: "Link to an existing project", value: "link" },
+                { label: "Create a new project", value: "new" }
+            ]);
+            if (mode === "new") {
+                const name = await input("New project name", detectLocalName() ?? undefined);
+                const { project: created } = await sdk.projects.create({ projectName: name });
+                console.log(`Created project '${created.name}' (${created.slug})`);
+                project = created.slug;
+            }
+            else {
+                if (!projects.length)
+                    return die("No projects accessible with this credential.");
+                const localName = normalize(detectLocalName() ?? "");
+                const choices = projects.map((p) => ({
+                    label: `${p.name}  (${p.slug})`,
+                    value: p.slug,
+                    hint: localName && (normalize(p.slug).includes(localName) || normalize(p.name).includes(localName) || localName.includes(normalize(p.slug)))
+                        ? "detected"
+                        : undefined
+                }));
+                choices.sort((a, b) => Number(Boolean(b.hint)) - Number(Boolean(a.hint)));
+                project = await select("Select a project", choices);
+            }
+        }
+        if (!environment) {
+            const projectId = project.includes("-") && project.length > 20
+                ? project
+                : (await sdk.projects.getBySlug(project)).id;
+            const { environments } = await sdk.projects.listEnvironments(projectId);
+            environment = environments.length
+                ? await select("Environment", environments.map((e) => ({ label: `${e.name}  (${e.slug})`, value: e.slug })))
+                : await input("Environment", "dev");
+        }
+        if (!secretPath)
+            secretPath = await input("Secret path", "/");
+    }
+    if (!project || !environment || !secretPath) {
+        return die("Usage: sanctum init --project <id-or-slug> [--env dev] [--path /apps/api] [--imports /shared] [--profile name]");
+    }
+    const config = {
+        [project.includes("-") && project.length > 20 ? "projectId" : "projectSlug"]: project,
+        environment,
+        secretPath,
+        ...(imports.length ? { imports } : {}),
+        ...(profile ? { profile } : {})
+    };
+    const configFile = join(process.cwd(), "sanctum-config.json");
+    const force = hasFlag(args, "--force");
+    if (existsSync(configFile) && !force) {
+        if (!process.stdin.isTTY) {
+            die("sanctum-config.json already exists. Re-run with --force to overwrite.");
+        }
+        const existing = JSON.parse(readFileSync(configFile, "utf8"));
+        console.log(`${yellow("!")} existing config: ${existing.projectSlug ?? existing.projectId} @ ${existing.environment ?? "dev"} ${existing.secretPath ?? "/"}`);
+        const overwrite = await select("Overwrite it?", [
+            { label: "Yes", value: true },
+            { label: "No", value: false }
+        ]);
+        if (!overwrite) {
+            console.log("Keeping existing config.");
+            return;
+        }
+    }
+    const file = writeProjectConfig(process.cwd(), config);
+    const rootFile = registerChildConfig(process.cwd());
+    console.log(`Wrote ${file}`);
+    if (rootFile)
+        console.log(`Registered in ${rootFile}`);
+    console.log(`  project:     ${project}`);
+    console.log(`  environment: ${environment}`);
+    console.log(`  secretPath:  ${secretPath}${imports.length ? ` (+ imports: ${imports.join(", ")})` : ""}${profile ? `, profile: ${profile}` : ""}`);
+};
+const cmdStatus = () => {
+    const config = resolveConfig();
+    console.log(`${cyan("●")} ${bold(config.projectSlug ?? config.projectId ?? "?")} ${dim(`@ ${config.environment ?? "dev"}`)}\n`);
+    console.log(`  ${dim("config")}    ${config.configFile}`);
+    console.log(`  ${dim("paths")}     ${config.paths.join(", ")}`);
+    if (config.profile)
+        console.log(`  ${dim("profile")}   ${config.profile}`);
+    if (config.projects) {
+        console.log(`\n  ${dim("linked projects")}`);
+        for (const [dir, entry] of Object.entries(config.projects)) {
+            const detail = typeof entry === "string" ? entry : `${entry.projectSlug ?? ""} ${entry.secretPath ?? ""}`.trim();
+            console.log(`    ${dir.padEnd(24)} ${dim(detail)}`);
+        }
+    }
+};
+const cmdProfiles = () => {
+    const profiles = listProfiles();
+    if (!profiles.length)
+        die("No profiles. Run `sanctum login` first.");
+    for (const p of profiles) {
+        console.log(`${p.isDefault ? "*" : " "} ${p.name.padEnd(20)} ${p.baseUrl}`);
+    }
+};
+const cmdProjects = async (args) => {
+    const sub = args[0] ?? "list";
+    const profile = takeFlag(args, "--profile");
+    const sdk = await getClient(profile);
+    if (sub === "list") {
+        const { projects } = await sdk.projects.list();
+        for (const p of projects)
+            console.log(`${p.slug.padEnd(32)} ${p.name}  ${p.id}`);
+    }
+    else {
+        die(`Unknown subcommand: projects ${sub}`);
+    }
+};
+const cmdEnvs = async (args) => {
+    const config = resolveConfig();
+    const profile = takeFlag(args, "--profile") ?? config.profile;
+    const sdk = await getClient(profile);
+    const projectId = config.projectId ?? (await sdk.projects.getBySlug(config.projectSlug)).id;
+    const { environments } = await sdk.projects.listEnvironments(projectId);
+    for (const e of environments)
+        console.log(`${e.slug.padEnd(16)} ${e.name}`);
+};
+/** Create a secret, falling back to update only when the server says it already exists. */
+const upsertSecret = async (sdk, key, secretValue, scope) => {
+    try {
+        const r = await sdk.secrets.create(key, { ...scope, secretValue });
+        return { verb: "Created", approval: r.approval };
+    }
+    catch (err) {
+        const conflict = err instanceof SanctumApiError && /exist|conflict/i.test(err.message);
+        if (!conflict)
+            throw err;
+        const r = await sdk.secrets.update(key, { ...scope, secretValue });
+        return { verb: "Updated", approval: r.approval };
+    }
+};
+const cmdSecrets = async (args) => {
+    const sub = args.shift();
+    const env = takeFlag(args, "--env");
+    const path = takeFlag(args, "--path");
+    const config = resolveConfig();
+    const profile = takeFlag(args, "--profile") ?? config.profile;
+    const sdk = await getClient(profile);
+    const scope = (p) => scopeQuery(config, p ?? path ?? config.secretPath ?? "/", env);
+    switch (sub) {
+        case "list": {
+            const merged = await fetchMergedSecrets(sdk, config, env);
+            const keys = Object.keys(merged).sort();
+            for (const k of keys)
+                console.log(k);
+            console.log(dim(`\n${keys.length} secrets`));
+            break;
+        }
+        case "get": {
+            const key = args[0];
+            if (!key)
+                die("Usage: sanctum secrets get <KEY>");
+            const { secret } = await sdk.secrets.get(key, scope());
+            console.log(secret.secretValue ?? "");
+            break;
+        }
+        case "set": {
+            const pair = args[0];
+            if (!pair?.includes("="))
+                die("Usage: sanctum secrets set <KEY>=<value>");
+            const [key, ...rest] = pair.split("=");
+            const value = rest.join("=");
+            const result = await upsertSecret(sdk, key, value, scope());
+            if (result.approval)
+                console.log(`${yellow("?")} ${key} queued for approval${result.approval.slug ? ` (${result.approval.slug})` : ""}`);
+            else
+                ok(`${result.verb} ${key}`);
+            break;
+        }
+        case "rm":
+        case "delete": {
+            const key = args[0];
+            if (!key)
+                die("Usage: sanctum secrets rm <KEY>");
+            const result = await sdk.secrets.delete(key, scope());
+            if (result.approval)
+                console.log(`${yellow("?")} deletion of ${key} queued for approval${result.approval.slug ? ` (${result.approval.slug})` : ""}`);
+            else
+                ok(`Deleted ${key}`);
+            break;
+        }
+        default:
+            die("Usage: sanctum secrets <list|get|set|rm>");
+    }
+};
+const maskValue = (v) => (v.length <= 4 ? "****" : `${v.slice(0, 2)}***${v.slice(-2)}`);
+const diffOne = async (sdk, config, file, env, showValues) => {
+    const local = existsSync(file) ? sdk.dotenv.parseDotenv(readFileSync(file, "utf8")) : {};
+    const remote = await fetchMergedSecrets(sdk, config, env);
+    const localKeys = new Set(Object.keys(local));
+    const remoteKeys = new Set(Object.keys(remote));
+    const allKeys = [...new Set([...localKeys, ...remoteKeys])].sort();
+    const added = [];
+    const changed = [];
+    const removed = [];
+    let unchanged = 0;
+    for (const key of allKeys) {
+        if (localKeys.has(key) && !remoteKeys.has(key))
+            added.push(key);
+        else if (!localKeys.has(key) && remoteKeys.has(key))
+            removed.push(key);
+        else if (local[key] !== remote[key])
+            changed.push(key);
+        else
+            unchanged += 1;
+    }
+    const renderValue = (v) => (showValues ? v : maskValue(v));
+    for (const k of added)
+        console.log(`${green("+")} ${k}  ${dim("local only")}${showValues ? `: ${local[k]}` : ""}`);
+    for (const k of changed) {
+        console.log(`${yellow("~")} ${k}  local=${renderValue(local[k])}  remote=${renderValue(remote[k])}`);
+    }
+    for (const k of removed)
+        console.log(`${red("-")} ${k}  ${dim("remote only")}`);
+    console.log(`\n${added.length} to add, ${changed.length} to update, ${removed.length} remote-only, ${unchanged} unchanged` +
+        (existsSync(file) ? `  [${file} vs ${config.projectSlug ?? config.projectId}/${config.environment ?? "dev"}]` : `  [no ${file} — showing remote-only]`));
+};
+const cmdDiff = async (args) => {
+    const env = takeFlag(args, "--env");
+    const showValues = hasFlag(args, "--values");
+    const all = hasFlag(args, "--all");
+    const config = resolveConfig();
+    const profile = takeFlag(args, "--profile") ?? config.profile;
+    const file = args[0] ?? ".env";
+    const sdk = await getClient(profile);
+    // monorepo: root config registers linked children — offer a scope pick
+    if (config.projects && Object.keys(config.projects).length) {
+        const rootDir = dirname(config.configFile);
+        const entries = Object.keys(config.projects);
+        let selected = all ? entries : null;
+        if (!selected && process.stdin.isTTY && !args[0]) {
+            const choice = await select("Diff which project?", [
+                { label: "All", value: "__all__" },
+                { label: "(this directory)", value: "__here__" },
+                ...entries.map((e) => ({ label: e, value: e }))
+            ]);
+            if (choice === "__all__")
+                selected = entries;
+            else if (choice === "__here__")
+                selected = [];
+            else
+                selected = [choice];
+        }
+        if (!selected)
+            selected = [];
+        for (const rel of selected) {
+            console.log(`\n== ${rel} ==`);
+            const childDir = join(rootDir, rel);
+            const childConfig = resolveConfig(childDir);
+            await diffOne(sdk, childConfig, join(childDir, file), env, showValues);
+        }
+        if (selected.length)
+            return;
+    }
+    await diffOne(sdk, config, file, env, showValues);
+};
+const cmdExport = async (args) => {
+    const env = takeFlag(args, "--env");
+    const format = takeFlag(args, "--format") ?? "dotenv";
+    const outFile = takeFlag(args, "--out");
+    const config = resolveConfig();
+    const profile = takeFlag(args, "--profile") ?? config.profile;
+    const sdk = await getClient(profile);
+    const merged = await fetchMergedSecrets(sdk, config, env);
+    let output;
+    if (format === "json") {
+        output = JSON.stringify(merged, null, 2);
+    }
+    else {
+        output = sdk.dotenv.renderDotenv(merged);
+    }
+    if (outFile) {
+        writeFileSync(outFile, output + "\n");
+        console.log(`Wrote ${Object.keys(merged).length} secrets to ${outFile}`);
+    }
+    else {
+        console.log(output);
+    }
+};
+/** Merge remote secrets into existing dotenv text: update values in place, append new keys, keep everything else. */
+const mergeDotenv = (existing, remote) => {
+    const applied = new Set();
+    let updated = 0;
+    const lines = existing.split(/\r?\n/).map((line) => {
+        const m = line.match(/^(\s*(?:export\s+)?)([A-Za-z_][A-Za-z0-9_]*)=(.*)$/);
+        if (!m)
+            return line;
+        const key = m[2];
+        if (!(key in remote))
+            return line;
+        applied.add(key);
+        if (m[3] === remote[key])
+            return line;
+        updated += 1;
+        return `${m[1]}${key}=${remote[key]}`;
+    });
+    const appended = Object.keys(remote).filter((k) => !applied.has(k));
+    const out = [...lines];
+    if (out.length && out[out.length - 1] === "")
+        out.pop();
+    for (const k of appended)
+        out.push(`${k}=${remote[k]}`);
+    return { text: out.join("\n"), updated, added: appended.length };
+};
+const pullOne = async (sdk, config, outFile, env, skipConfirm = false) => {
+    const merged = await fetchMergedSecrets(sdk, config, env);
+    if (existsSync(outFile)) {
+        const { text, updated, added } = mergeDotenv(readFileSync(outFile, "utf8"), merged);
+        if (!updated && !added) {
+            ok(`${outFile} already in sync — no changes.`);
+            return;
+        }
+        if (!skipConfirm && process.stdin.isTTY) {
+            const proceed = await select(`${outFile}: update ${updated}, add ${added} — apply?`, [
+                { label: "Yes", value: true },
+                { label: "No", value: false }
+            ]);
+            if (!proceed) {
+                console.log("Skipped.");
+                return;
+            }
+        }
+        writeFileSync(outFile, text.endsWith("\n") ? text : text + "\n");
+        ok(`Updated ${updated}, added ${added} in ${outFile}`);
+        return;
+    }
+    writeFileSync(outFile, sdk.dotenv.renderDotenv(merged) + "\n");
+    ok(`Pulled ${Object.keys(merged).length} secrets to ${outFile}`);
+};
+const cmdPull = async (args) => {
+    const env = takeFlag(args, "--env");
+    const all = hasFlag(args, "--all");
+    const yes = hasFlag(args, "--yes") || hasFlag(args, "-y") || hasFlag(args, "--force");
+    const outFlag = takeFlag(args, "--out");
+    const config = resolveConfig();
+    const profile = takeFlag(args, "--profile") ?? config.profile;
+    const file = outFlag ?? args[0] ?? ".env";
+    const sdk = await getClient(profile);
+    if (config.projects && Object.keys(config.projects).length) {
+        const rootDir = dirname(config.configFile);
+        const entries = Object.keys(config.projects);
+        let selected = all ? entries : null;
+        if (!selected && process.stdin.isTTY && !args[0] && !outFlag) {
+            const choice = await select("Pull which project?", [
+                { label: "All", value: "__all__" },
+                { label: "(this directory)", value: "__here__" },
+                ...entries.map((e) => ({ label: e, value: e }))
+            ]);
+            if (choice === "__all__")
+                selected = entries;
+            else if (choice === "__here__")
+                selected = [];
+            else
+                selected = [choice];
+        }
+        if (!selected)
+            selected = [];
+        for (const rel of selected) {
+            const childDir = join(rootDir, rel);
+            console.log(`\n== ${rel} ==`);
+            await pullOne(sdk, resolveConfig(childDir), join(childDir, file), env, yes);
+        }
+        if (selected.length) {
+            console.log("note: pulled files contain real secret values — keep them out of git.");
+            return;
+        }
+    }
+    await pullOne(sdk, config, file, env, yes);
+    console.log("note: pulled files contain real secret values — keep them out of git.");
+};
+const cmdRun = async (args) => {
+    const separator = args.indexOf("--");
+    const head = separator === -1 ? args : args.slice(0, separator);
+    const env = takeFlag(head, "--env");
+    const profileFlag = takeFlag(head, "--profile");
+    const command = separator === -1 ? head : args.slice(separator + 1);
+    if (!command.length)
+        die("Usage: sanctum run [--env dev] [--profile x] -- <command> [args...]");
+    const config = resolveConfig();
+    const profile = profileFlag ?? config.profile;
+    const sdk = await getClient(profile);
+    const merged = await fetchMergedSecrets(sdk, config, env);
+    if (!Object.keys(merged).length) {
+        console.error(`warning: no secrets resolved for ${config.projectSlug ?? config.projectId}/${config.environment ?? "dev"} ` +
+            `(paths: ${config.paths.join(", ")}) — check the environment and paths exist.`);
+    }
+    const child = spawn(command[0], command.slice(1), {
+        env: { ...process.env, ...merged },
+        stdio: "inherit",
+        shell: process.platform === "win32"
+    });
+    child.on("exit", (code) => process.exit(code ?? 0));
+};
+const cmdEnvFile = async (args) => {
+    const dryRun = hasFlag(args, "--dry-run");
+    const assumeYes = hasFlag(args, "--yes") || hasFlag(args, "-y");
+    const env = takeFlag(args, "--env");
+    const file = args[0] ?? ".env";
+    if (!existsSync(file))
+        die(`${file} not found. Create it, or fetch remote secrets first with \`sanctum pull ${file}\`.`);
+    const config = resolveConfig();
+    const profile = takeFlag(args, "--profile") ?? config.profile;
+    const sdk = await getClient(profile);
+    const values = sdk.dotenv.parseDotenv(readFileSync(file, "utf8"));
+    const keys = Object.keys(values);
+    if (!keys.length)
+        die(`No KEY=value pairs found in ${file}. Nothing to push.`);
+    // preview against remote so the user sees exactly what changes
+    const remote = await fetchMergedSecrets(sdk, config, env);
+    const toAdd = keys.filter((k) => !(k in remote));
+    const toUpdate = keys.filter((k) => k in remote && remote[k] !== values[k]);
+    const same = keys.length - toAdd.length - toUpdate.length;
+    const remoteOnly = Object.keys(remote).filter((k) => !(k in values));
+    console.log(`${dim(file)} -> ${bold(config.projectSlug ?? config.projectId ?? "?")}/${env ?? config.environment ?? "dev"}${config.secretPath ?? "/"}`);
+    for (const k of toAdd)
+        console.log(`${green("+")} ${k}  ${dim("new")}`);
+    for (const k of toUpdate)
+        console.log(`${yellow("~")} ${k}  ${dim(maskValue(values[k]))}`);
+    console.log(`${toAdd.length} to add, ${toUpdate.length} to update, ${same} unchanged, ${remoteOnly.length} remote-only (kept)`);
+    if (dryRun)
+        return;
+    if (!toAdd.length && !toUpdate.length) {
+        console.log("Nothing to push.");
+        return;
+    }
+    if (!assumeYes && process.stdin.isTTY) {
+        const ok = await select("Apply these changes?", [
+            { label: "Yes", value: true },
+            { label: "No", value: false }
+        ]);
+        if (!ok) {
+            console.log("Aborted.");
+            return;
+        }
+    }
+    const scope = { ...scopeQuery(config, config.secretPath ?? "/", env), secretPath: config.secretPath ?? "/" };
+    let pushed = 0;
+    let approvals = 0;
+    for (const key of [...toAdd, ...toUpdate]) {
+        const result = await upsertSecret(sdk, key, values[key], scope);
+        if (result.approval) {
+            approvals += 1;
+            console.log(`${yellow("?")} ${key}  ${dim(`queued for approval${result.approval.slug ? ` (${result.approval.slug})` : ""}`)}`);
+        }
+        else {
+            pushed += 1;
+        }
+    }
+    ok(`Pushed ${pushed} secrets to ${config.secretPath ?? "/"}${approvals ? `, ${approvals} pending approval` : ""}`);
+};
+const AGENTS_SNIPPET = `
+## Secrets management (Sanctum)
+
+This project uses the Sanctum CLI for secrets — do NOT create or commit .env files
+with real values.
+
+- \`sanctum-config.json\` links this directory to a Sanctum project/environment/secret
+  path. It is committed and contains no secrets.
+- Run the app with \`sanctum run -- <command>\` (e.g. \`sanctum run -- npm run dev\`) —
+  secrets are injected as env vars at launch.
+- \`sanctum secrets list\` / \`get <KEY>\` / \`set <KEY>=<v>\` read and write remote secrets.
+- \`sanctum diff\` compares a local file against remote; \`sanctum push\` uploads with a
+  preview. Never paste secret values into chat, commits, or docs.
+`;
+const cmdAgents = () => {
+    const target = join(process.cwd(), "AGENTS.md");
+    const existing = existsSync(target) ? readFileSync(target, "utf8") : "";
+    if (existing.includes("Secrets management (Sanctum)")) {
+        console.log("AGENTS.md already has a Sanctum section.");
+        return;
+    }
+    writeFileSync(target, existing.trimEnd() + "\n" + AGENTS_SNIPPET);
+    console.log(`Appended Sanctum section to ${target}`);
+};
+const HELP = `sanctum — CLI for the Sanctum secrets platform
+
+Usage:
+  sanctum login --token <token> | --client-id <id> --client-secret <secret> [--base-url <url>] [--profile name]
+  sanctum profiles                                   list saved credential profiles
+  sanctum init [--project <id-or-slug>] [--env dev] [--path /apps/api] [--imports /shared] [--profile name]
+                                 (interactive picker when --project is omitted)
+  sanctum projects list [--profile name]
+  sanctum status                                    show resolved config + linked monorepo projects
+  sanctum agents                                    add a Sanctum usage section to ./AGENTS.md
+  sanctum envs
+  sanctum secrets list|get <KEY>|set <KEY>=<value>|rm <KEY> [--env x] [--path /x] [--profile name]
+  sanctum export [--env x] [--format dotenv|json] [--out file]
+  sanctum diff [file] [--env x] [--values] [--all]  compare local .env against remote secrets
+  sanctum pull [file] [--env x] [--all] [--yes]     fetch remote secrets into a local .env
+  sanctum push [file] [--env x] [--dry-run] [--yes] push a .env file's keys to your configured secretPath
+  sanctum run [--env x] [--profile x] -- <cmd>
+
+Discovery: commands read the nearest sanctum-config.json upward from cwd.
+Ancestor configs merge in root->leaf order so shared folders apply repo-wide.
+The config file is safe to commit — credentials live in ~/.sanctum/credentials.json,
+keyed by profile. Profile resolution: --profile > SANCTUM_PROFILE > config "profile" > "default".
+`;
+const main = async () => {
+    const args = process.argv.slice(2);
+    const cmd = args.shift();
+    try {
+        switch (cmd) {
+            case "login": return await cmdLogin(args);
+            case "profiles": return cmdProfiles();
+            case "init": return await cmdInit(args);
+            case "projects": return await cmdProjects(args);
+            case "status": return cmdStatus();
+            case "agents": return cmdAgents();
+            case "envs": return await cmdEnvs(args);
+            case "secrets": return await cmdSecrets(args);
+            case "export": return await cmdExport(args);
+            case "diff": return await cmdDiff(args);
+            case "pull": return await cmdPull(args);
+            case "push": return await cmdEnvFile(args);
+            case "run": return await cmdRun(args);
+            case "whoami": {
+                const profileFlag = takeFlag(args, "--profile");
+                const credentials = loadCredentials(profileFlag);
+                if (!credentials)
+                    return die("Not logged in.");
+                const claims = credentials.accessToken ? decodeJwtPayload(credentials.accessToken) : null;
+                const exp = claims?.exp ? new Date(Number(claims.exp) * 1000) : null;
+                const valid = !exp || exp.getTime() > Date.now();
+                console.log(`${green("●")} ${bold("logged in")} ${dim(`as profile`)} ${cyan(profileFlag ?? process.env.SANCTUM_PROFILE ?? "default")}\n`);
+                console.log(`  ${dim("instance")}   ${credentials.baseUrl}`);
+                if (credentials.clientId)
+                    console.log(`  ${dim("clientId")}   ${credentials.clientId}`);
+                if (claims?.identityId)
+                    console.log(`  ${dim("identity")}   ${String(claims.identityId)}`);
+                if (claims?.orgId)
+                    console.log(`  ${dim("org")}        ${String(claims.orgId)}`);
+                if (exp) {
+                    const expired = exp.getTime() <= Date.now();
+                    console.log(`  ${dim("token")}      ${expired ? red("expired") : "valid until"} ${exp.toLocaleString()}`);
+                }
+                if (!valid)
+                    console.log(dim("\n  token expired — next command will re-authenticate via clientId/secret"));
+                return;
+            }
+            case "--version":
+            case "-v":
+            case "version":
+                console.log(VERSION);
+                return;
+            default:
+                console.log(HELP);
+                if (cmd && cmd !== "help" && cmd !== "--help")
+                    process.exit(1);
+        }
+    }
+    catch (err) {
+        die(err instanceof Error ? err.message : String(err));
+    }
+};
+void main();

package/dist/config.js

@@ -0,0 +1,156 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+const CONFIG_FILENAME = "sanctum-config.json";
+const CREDENTIALS_DIR = ".sanctum";
+const CREDENTIALS_FILE = "credentials.json";
+const credentialsPath = () => join(homedir(), CREDENTIALS_DIR, CREDENTIALS_FILE);
+const readStore = () => {
+    const path = credentialsPath();
+    if (!existsSync(path))
+        return { profiles: {} };
+    const raw = JSON.parse(readFileSync(path, "utf8"));
+    // migrate flat { baseUrl, accessToken, ... } shape to profiles
+    if ("baseUrl" in raw && typeof raw.baseUrl === "string") {
+        return { default: "default", profiles: { default: raw } };
+    }
+    return raw;
+};
+/**
+ * Credential resolution order:
+ *   SANCTUM_TOKEN / SANCTUM_CLIENT_* env vars  >  explicit profile  >  default profile
+ */
+export const loadCredentials = (profile) => {
+    const baseUrl = process.env.SANCTUM_BASE_URL ?? "http://localhost:4000";
+    if (process.env.SANCTUM_TOKEN) {
+        return { baseUrl, accessToken: process.env.SANCTUM_TOKEN };
+    }
+    if (process.env.SANCTUM_CLIENT_ID && process.env.SANCTUM_CLIENT_SECRET) {
+        return {
+            baseUrl,
+            clientId: process.env.SANCTUM_CLIENT_ID,
+            clientSecret: process.env.SANCTUM_CLIENT_SECRET
+        };
+    }
+    const store = readStore();
+    const name = profile ?? process.env.SANCTUM_PROFILE ?? store.default ?? "default";
+    const stored = store.profiles[name];
+    if (!stored)
+        return null;
+    return { ...stored, baseUrl: process.env.SANCTUM_BASE_URL ?? stored.baseUrl };
+};
+export const saveCredentials = (credentials, profile = "default") => {
+    const store = readStore();
+    store.profiles[profile] = credentials;
+    store.default = store.default ?? profile;
+    const path = credentialsPath();
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify(store, null, 2) + "\n", { mode: 0o600 });
+};
+export const listProfiles = () => {
+    const store = readStore();
+    return Object.entries(store.profiles).map(([name, c]) => ({
+        name,
+        isDefault: store.default === name,
+        baseUrl: c.baseUrl
+    }));
+};
+/**
+ * Walk up from `startDir` collecting every sanctum-config.json.
+ * The nearest config is authoritative for projectId/environment/secretPath.
+ * Ancestor configs contribute their secretPath + imports so shared folders
+ * declared higher in a monorepo merge in (deepest path wins on key conflicts).
+ */
+export const resolveConfig = (startDir = process.cwd()) => {
+    const configs = [];
+    let dir = resolve(startDir);
+    for (;;) {
+        const file = join(dir, CONFIG_FILENAME);
+        if (existsSync(file)) {
+            configs.push({ dir, config: JSON.parse(readFileSync(file, "utf8")) });
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    if (!configs.length) {
+        throw new Error(`No ${CONFIG_FILENAME} found in this directory or any parent. Run \`sanctum init\` first.`);
+    }
+    // If the nearest config's own projects map has an entry covering cwd,
+    // merge it as a synthetic leaf config (single-config monorepo support).
+    let primary = configs[0].config;
+    let primaryFile = join(configs[0].dir, CONFIG_FILENAME);
+    for (const { dir, config } of configs) {
+        if (!config.projects)
+            continue;
+        for (const [rel, entry] of Object.entries(config.projects)) {
+            const childDir = resolve(dir, rel);
+            if (resolve(startDir) === childDir || resolve(startDir).startsWith(childDir + "\\") || resolve(startDir).startsWith(childDir + "/")) {
+                if (typeof entry === "object") {
+                    primary = { ...config, projects: undefined, ...entry };
+                    primaryFile = join(dir, rel, CONFIG_FILENAME);
+                }
+            }
+        }
+    }
+    const paths = [];
+    // configs are collected leaf -> root; iterate root -> leaf so deeper
+    // configs (and their imports) win on key conflicts
+    for (const { config } of [...configs].reverse()) {
+        for (const imp of config.imports ?? []) {
+            if (!paths.includes(imp))
+                paths.push(imp);
+        }
+        const p = config.secretPath ?? "/";
+        if (!paths.includes(p))
+            paths.push(p);
+    }
+    if (primary !== configs[0].config) {
+        for (const imp of primary.imports ?? []) {
+            if (!paths.includes(imp))
+                paths.push(imp);
+        }
+        const p = primary.secretPath ?? "/";
+        if (!paths.includes(p))
+            paths.push(p);
+    }
+    return {
+        ...primary,
+        paths,
+        configFile: primaryFile
+    };
+};
+/**
+ * Register a child config in the outermost ancestor sanctum-config.json so a
+ * monorepo root tracks every linked app: `projects: { "apps/api": "apps/api/sanctum-config.json" }`.
+ * Returns the ancestor config file that was updated, or null if none exists.
+ */
+export const registerChildConfig = (childDir, startDir = childDir) => {
+    const parentConfigs = [];
+    let dir = dirname(resolve(startDir));
+    for (;;) {
+        const file = join(dir, CONFIG_FILENAME);
+        if (existsSync(file))
+            parentConfigs.push({ dir, file });
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    if (!parentConfigs.length)
+        return null;
+    const root = parentConfigs[parentConfigs.length - 1];
+    const config = JSON.parse(readFileSync(root.file, "utf8"));
+    const rel = resolve(childDir) === resolve(root.dir)
+        ? "."
+        : resolve(childDir).slice(resolve(root.dir).length + 1).replace(/\\/g, "/");
+    config.projects = { ...(config.projects ?? {}), [rel]: `${rel}/${CONFIG_FILENAME}` };
+    writeFileSync(root.file, JSON.stringify(config, null, 2) + "\n");
+    return root.file;
+};
+export const writeProjectConfig = (dir, config) => {
+    const file = join(dir, CONFIG_FILENAME);
+    writeFileSync(file, JSON.stringify(config, null, 2) + "\n");
+    return file;
+};

package/dist/prompt.js

@@ -0,0 +1,98 @@
+import { createInterface } from "node:readline";
+const hideCursor = () => process.stdout.write("\x1b[?25l");
+const showCursor = () => process.stdout.write("\x1b[?25h");
+export const select = async (question, choices) => {
+    if (!process.stdin.isTTY) {
+        throw new Error("Interactive prompt requires a TTY. Pass flags instead (e.g. --project, --env).");
+    }
+    return new Promise((resolve) => {
+        let index = 0;
+        let rendered = 0;
+        const render = () => {
+            if (rendered > 0)
+                process.stdout.write(`\x1b[${rendered}A`);
+            const lines = [
+                `? ${question}`,
+                ...choices.map((c, i) => ` ${i === index ? "❯" : " "} ${c.label}${i === index && c.hint ? `  ${c.hint}` : ""}`)
+            ];
+            process.stdout.write(lines.map((l) => `\x1b[2K${l}`).join("\n") + "\n");
+            rendered = lines.length;
+        };
+        const finish = () => {
+            process.stdin.setRawMode(false);
+            process.stdin.pause();
+            process.stdin.removeListener("data", onData);
+            showCursor();
+            resolve(choices[index].value);
+        };
+        const onData = (chunk) => {
+            const key = chunk.toString("utf8");
+            if (key === "\r" || key === "\n")
+                return finish();
+            if (key === "\u0003") {
+                showCursor();
+                process.exit(130);
+            }
+            if (key === "\u001b[A" || key === "k")
+                index = (index - 1 + choices.length) % choices.length;
+            else if (key === "\u001b[B" || key === "j")
+                index = (index + 1) % choices.length;
+            else if (key >= "1" && key <= "9") {
+                const n = Number(key) - 1;
+                if (n < choices.length)
+                    index = n;
+            }
+            else {
+                return;
+            }
+            render();
+        };
+        hideCursor();
+        process.stdin.setRawMode(true);
+        process.stdin.resume();
+        process.stdin.on("data", onData);
+        render();
+    });
+};
+export const input = async (question, fallback) => {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    const suffix = fallback ? ` (${fallback})` : "";
+    return new Promise((resolve) => {
+        rl.question(`? ${question}${suffix}: `, (answer) => {
+            rl.close();
+            resolve(answer.trim() || fallback || "");
+        });
+    });
+};
+export const password = async (question) => {
+    if (!process.stdin.isTTY) {
+        throw new Error("Interactive prompt requires a TTY. Pass the value via flag or env var.");
+    }
+    return new Promise((resolve) => {
+        let value = "";
+        process.stdout.write(`? ${question}: `);
+        const onData = (chunk) => {
+            const s = chunk.toString("utf8");
+            if (s === "\r" || s === "\n") {
+                process.stdin.setRawMode(false);
+                process.stdin.pause();
+                process.stdin.removeListener("data", onData);
+                process.stdout.write("\n");
+                resolve(value.trim());
+            }
+            else if (s === "\u0003") {
+                process.stdout.write("\n");
+                process.exit(130);
+            }
+            else if (s === "\b" || s === "\u007f") {
+                value = value.slice(0, -1);
+            }
+            else {
+                value += s;
+            }
+        };
+        process.stdin.setRawMode(true);
+        process.stdin.resume();
+        process.stdin.on("data", onData);
+    });
+};

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "sanctum-cli",
+  "version": "0.1.0",
+  "description": "Command-line client for the Sanctum secrets platform",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/neang-mengseang/sanctum.git",
+    "directory": "packages/cli"
+  },
+  "type": "module",
+  "bin": {
+    "sanctum": "dist/cli.js"
+  },
+  "main": "dist/cli.js",
+  "files": [
+    "dist",
+    "README.md",
+    "DEMO.md"
+  ],
+  "prepublishOnly": "npm run build",
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "typecheck": "tsc --noEmit",
+    "clean": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\""
+  },
+  "dependencies": {
+    "sanctum-sdk": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.4.0"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}