vault-cortex 0.5.1 → 0.6.1

package/README.md

@@ -7,28 +7,62 @@ for your Obsidian vault in one command:
 npx vault-cortex@latest init
 ```
 
-Vault Cortex is a standalone, remote-capable MCP server for Obsidian vaults —
-Tools for hybrid search (FTS5 + vector + cross-encoder reranking, with
-tag/folder/property/date filters), notes, frontmatter, links, daily notes,
-Kanban-aware task management (query + complete/move/reprioritize, parsing Tasks-plugin emoji + Dataview inline-field formats), and
-a structured memory layer with topic recall (the current take plus the
-dated history behind it), plus guided prompts (orientation, memory
-review, daily review). It runs as a Docker
-container; this CLI scaffolds the config so you don't have to.
+Vault Cortex is a standalone, remote-capable MCP server that gives any AI
+agent hybrid search, task management, structured memory, and read/write
+access to your Obsidian vault — see the
+[full feature overview](https://github.com/aliasunder/vault-cortex#what-you-get).
+The server runs as a Docker container; this CLI scaffolds the config and
+manages the container so you don't have to.
 
-## What `init` does
+![npx vault-cortex init — the interactive setup wizard picks a mode, finds your vault, generates the config, and starts the server](https://raw.githubusercontent.com/aliasunder/vault-cortex/main/assets/demo-cli-init.gif)
+
+## Commands
+
+- [`init`](#init) — interactive setup: scaffold the config, generate the auth
+  token, start the server
+- [`upgrade`](#upgrade) — pull the latest image and re-create the container;
+  your data stays
+- [`get-sync-token`](#get-sync-token) — generate an Obsidian Sync auth token
+  for remote setups
+
+Run `npx vault-cortex <command> --help` for all flags.
+
+## init
+
+```bash
+npx vault-cortex@latest init
+```
+
+What it does:
 
 1. Asks how you want to run it:
    - **Local** — Docker on this machine, your vault folder bind-mounted
-   - **Remote** — a VPS with [Obsidian Sync](https://obsidian.md/sync), reachable from any device
+   - **Remote** — a VPS with [Obsidian Sync](https://obsidian.md/sync),
+     reachable from any device
 2. Generates a `.env` file with a securely generated `MCP_AUTH_TOKEN`
 3. Optionally starts the container and waits for the health check
 4. Prints your connection details — the MCP URL, your auth token, and how to
    connect your client
 
-Existing files are never overwritten without asking.
+Existing files are never overwritten without asking. During a remote setup,
+init offers to run [`get-sync-token`](#get-sync-token) for you when Docker is
+available.
 
-## Upgrade
+Flags:
+
+- `--mode local|remote` — skip the mode prompt
+- `--vault-path <path>` — absolute path to your vault (local mode)
+- `--dir <path>` — directory to write config files into (default
+  `./vault-cortex`)
+- `--yes` — non-interactive local setup with defaults; requires `--vault-path`
+
+Non-interactive example:
+
+```bash
+npx vault-cortex@latest init --yes --vault-path /path/to/YourVault
+```
+
+## upgrade
 
 Pull the latest image, re-create the container, and verify health:
 
@@ -40,27 +74,45 @@ Run it from the same directory where you ran `init` — it looks for your
 config in `./vault-cortex/.env` (pass `--dir <path>` if you scaffolded
 somewhere else).
 
-Your vault data, search index, and `.env` settings are preserved across
-upgrades — only the server image is replaced. Also applies `.env` changes
-(`docker restart` does not re-read env files).
+Safe by design:
+
+- Your vault data, search index, and `.env` settings are preserved across
+  upgrades — only the server image is replaced.
+- Any edits you've made to `.env` are applied on the way up (`docker restart`
+  alone does not re-read env files).
 
 Prefer Docker Compose? The CLI uses `docker run` for simplicity, but the
 [deploy guides](https://github.com/aliasunder/vault-cortex/blob/main/deploy/)
-include Compose files you can use directly.
+include Compose files you can use directly. If you set up with Compose, stick
+with Compose for updates too (`docker compose pull && docker compose up -d`)
+— the CLI and Compose manage the container independently.
+
+## get-sync-token
 
-## Non-interactive
+Generate an [Obsidian Sync](https://obsidian.md/sync) auth token — needed for
+remote setups — without leaving the CLI:
 
 ```bash
-npx vault-cortex@latest init --yes --vault-path /path/to/YourVault
+npx vault-cortex get-sync-token
+```
+
+The command opens the Obsidian login inside Docker. Once you've signed in, it
+captures your token and prints it — nothing to dig out of the login output.
+Use `--dir <path>` to write the token straight into an existing `.env`
+instead:
+
+```bash
+npx vault-cortex get-sync-token --dir ./vault-cortex
 ```
 
-Flags: `--mode local|remote`, `--vault-path <path>`, `--dir <path>` (default
-`./vault-cortex`), `--yes`.
+During `init --mode remote`, this flow is offered automatically when Docker
+is available.
 
 ## Requirements
 
 - Node.js >= 20.12 (only for this CLI — the server itself runs in Docker)
-- [Docker](https://docs.docker.com/get-docker/) (or any OCI-compatible runtime) to run the server
+- [Docker](https://docs.docker.com/get-docker/) (or any OCI-compatible
+  runtime, e.g. Podman) to run the server
 
 ## Docs
 

package/dist/docker.js

@@ -2,6 +2,36 @@ import { spawnSync } from "node:child_process";
 export const LOCAL_IMAGE = "ghcr.io/aliasunder/vault-cortex:latest";
 export const REMOTE_IMAGE = "ghcr.io/aliasunder/vault-cortex:remote";
 export const CONTAINER_NAME = "vault-cortex";
+/**
+ * Builds the `docker run` args for the Obsidian login with a volume mount
+ * that captures the auth token file. Runs `ob login` directly instead of
+ * the image's get-sync-token script: the script's additions are locating and
+ * printing the token, and the mount makes both unnecessary — the CLI reads
+ * the token file itself, and not echoing a credential keeps it out of
+ * terminal scrollback. Pure function for testability.
+ *
+ * On Linux, includes `--user uid:gid` when uid/gid are provided — Node
+ * exposes process.getuid/getgid on every POSIX platform, so in practice the
+ * flag is always set there — keeping the token file host-user-owned. macOS
+ * Docker Desktop translates UIDs automatically, so no flag is needed.
+ */
+export const buildObsidianLoginArgs = (params) => {
+    const { configMountPath, platform = process.platform, uid, gid } = params;
+    const args = [
+        "run",
+        "--rm",
+        "-it",
+        "--entrypoint",
+        "ob",
+        "-v",
+        `${configMountPath}:/home/obsidian/.config`,
+    ];
+    if (platform === "linux" && uid !== undefined && gid !== undefined) {
+        args.push("--user", `${uid}:${gid}`);
+    }
+    args.push(REMOTE_IMAGE, "login");
+    return args;
+};
 /**
  * Container-internal env vars that must override the user's .env values.
  * VAULT_PATH in .env is the host path (for the -v mount); the container
@@ -70,7 +100,11 @@ export const createDockerRunner = () => ({
         .status === 0,
     pullImage: (image) => spawnSync("docker", ["pull", image], { stdio: "inherit" }).status === 0,
     stopAndRemoveContainer: () => spawnSync("docker", ["rm", "-f", CONTAINER_NAME]).status === 0,
-    runGetToken: () => spawnSync("docker", ["run", "--rm", "-it", "--entrypoint", "get-token", REMOTE_IMAGE], { stdio: "inherit" }).status === 0,
+    runObsidianLogin: (configMountPath) => spawnSync("docker", buildObsidianLoginArgs({
+        configMountPath,
+        uid: process.getuid?.(),
+        gid: process.getgid?.(),
+    }), { stdio: "inherit" }).status === 0,
 });
 /**
  * Polls the health endpoint until it responds OK or the timeout elapses.

package/dist/env.js

@@ -1,4 +1,3 @@
-import { REMOTE_IMAGE } from "./docker.js";
 // Optional env blocks are synced from deploy/<mode>/.env.example by
 // npm run sync:cli-env-blocks. Edit the deploy/ files, then re-run the script.
 // cli/src/templates.test.ts asserts the CLI optional block vars match the
@@ -183,8 +182,7 @@ VAULT_PASSWORD=${answers.vaultPassword}`;
     const obsidianTokenComment = answers.obsidianAuthToken === ""
         ? `# Obsidian Sync auth token — FILL THIS IN before starting the server.
 # Generate once with:
-#   docker run --rm -it --entrypoint get-token \\
-#     ${REMOTE_IMAGE}`
+#   npx vault-cortex get-sync-token`
         : `# Obsidian Sync auth token.`;
     return `# vault-cortex — remote quickstart (Obsidian Sync)
 # Generated by \`npx vault-cortex init\`. Full option reference:

package/dist/get-sync-token.js

@@ -0,0 +1,150 @@
+import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { patchEnvObsidianToken } from "./scaffold.js";
+import { expandTilde } from "./vault.js";
+/** Message from an unknown throw — Error instances keep their message. */
+const describeError = (error) => error instanceof Error ? error.message : String(error);
+/**
+ * Creates the temp dir the container's config mount writes into.
+ * Returns undefined (after warning) when creation fails.
+ */
+const makeTempMountDir = (prompts) => {
+    try {
+        return mkdtempSync(join(tmpdir(), "vault-cortex-sync-token-"));
+    }
+    catch (error) {
+        prompts.warn(`Could not create a temp directory for token capture — ${describeError(error)}`);
+        return undefined;
+    }
+};
+/**
+ * Runs the interactive Obsidian login container. A throw from the Docker
+ * runner is reported and treated the same as a non-zero exit.
+ */
+const runLoginContainer = (configMountPath, deps) => {
+    const { docker, prompts } = deps;
+    try {
+        return docker.runObsidianLogin(configMountPath);
+    }
+    catch (error) {
+        prompts.warn(`Docker run failed — ${describeError(error)}`);
+        return false;
+    }
+};
+/**
+ * Reads the captured token file from the config mount. Returns undefined
+ * when the file is missing, empty, or unreadable — the caller treats all
+ * three as "no token captured".
+ */
+const readCapturedTokenFile = (configMountPath) => {
+    const tokenPath = join(configMountPath, "obsidian-headless", "auth_token");
+    try {
+        if (!existsSync(tokenPath))
+            return undefined;
+        const token = readFileSync(tokenPath, "utf8").trim();
+        return token || undefined;
+    }
+    catch {
+        return undefined;
+    }
+};
+/**
+ * Best-effort removal of the temp mount dir. Failing to remove it (e.g.
+ * root-owned files left by the container) must not turn a successful
+ * capture into a failure, so it warns instead of throwing.
+ */
+const removeTempMountDir = (configMountPath, prompts) => {
+    try {
+        rmSync(configMountPath, { recursive: true, force: true });
+    }
+    catch (error) {
+        prompts.warn(`Could not remove temp directory ${configMountPath} — ${describeError(error)}`);
+    }
+};
+/**
+ * Runs the Obsidian login (`ob login`) inside a Docker container with a
+ * volume mount that captures the auth token file. The interactive login
+ * (email, password, MFA) shows in the terminal, but the resulting token is
+ * read from the mounted config dir — never printed, so it stays out of
+ * terminal scrollback.
+ *
+ * tokenDestinationMessage finishes the handoff message by telling the user
+ * where the captured token ends up — the destination differs per flow
+ * (init stores it in the generated .env; the subcommand prints it, or
+ * writes it to an existing .env with --dir).
+ *
+ * Returns the token string on success, undefined on any failure — each
+ * fallible operation is wrapped individually by the helpers above, so no
+ * catch-all is needed here. The bare try/finally only scopes the temp dir
+ * (acquire → release); it has no catch and swallows nothing.
+ */
+export const captureObsidianToken = (deps, tokenDestinationMessage) => {
+    const { prompts } = deps;
+    const configMountPath = makeTempMountDir(prompts);
+    if (!configMountPath)
+        return undefined;
+    try {
+        prompts.log("Handing the terminal to the Obsidian login — it will ask for your " +
+            `account email, password, and MFA code. ${tokenDestinationMessage}`);
+        const loginSucceeded = runLoginContainer(configMountPath, deps);
+        if (!loginSucceeded) {
+            prompts.warn("The Obsidian login did not complete — you can run it later with:\n" +
+                "  npx vault-cortex get-sync-token");
+            return undefined;
+        }
+        const token = readCapturedTokenFile(configMountPath);
+        if (!token) {
+            prompts.warn("The Obsidian login finished, but no token was captured — the " +
+                "token file was missing, empty, or unreadable. You can retry with:\n" +
+                "  npx vault-cortex get-sync-token");
+            return undefined;
+        }
+        return token;
+    }
+    finally {
+        removeTempMountDir(configMountPath, prompts);
+    }
+};
+/**
+ * Subcommand entry: generate an Obsidian Sync token via Docker.
+ * Without --dir, prints the token to stdout.
+ * With --dir, writes it directly to `<dir>/.env`.
+ */
+export const runGetSyncToken = async (flags, deps) => {
+    const { prompts, docker } = deps;
+    if (!docker.isDaemonRunning()) {
+        prompts.error("Container runtime not running — start Docker Desktop, Colima,\n" +
+            "OrbStack, or another Docker-compatible runtime and try again.");
+        return 1;
+    }
+    prompts.intro("vault-cortex get-sync-token");
+    // Resolve the destination up front so the login handoff message can tell
+    // the user where the token will end up.
+    const envFilePath = flags.dir
+        ? join(resolve(expandTilde(flags.dir)), ".env")
+        : undefined;
+    const tokenDestinationMessage = envFilePath
+        ? `The token is captured automatically and written to ${envFilePath}.`
+        : "The token is captured automatically and printed at the end.";
+    const token = captureObsidianToken({ docker, prompts }, tokenDestinationMessage);
+    if (!token) {
+        prompts.error("Could not capture the auth token.");
+        return 1;
+    }
+    if (!envFilePath) {
+        prompts.log("Your OBSIDIAN_AUTH_TOKEN:");
+        prompts.print(`\n  ${token}\n`);
+        prompts.outro("Done.");
+        return 0;
+    }
+    const patched = patchEnvObsidianToken(envFilePath, token);
+    if (!patched) {
+        prompts.error(`Could not patch ${envFilePath} — the file is missing or has no ` +
+            "OBSIDIAN_AUTH_TOKEN line. Run init first.");
+        return 1;
+    }
+    prompts.log(`Token written to ${envFilePath}`);
+    prompts.outro("Done.");
+    return 0;
+};

package/dist/init.js

@@ -1,7 +1,8 @@
 import { join, resolve } from "node:path";
 import { buildLocalEnv, buildRemoteEnv } from "./env.js";
+import { captureObsidianToken } from "./get-sync-token.js";
 import { buildLocalConnectMessage, buildRemoteConnectMessage, } from "./messages.js";
-import { REMOTE_IMAGE, pollHealth } from "./docker.js";
+import { pollHealth } from "./docker.js";
 import { buildFilesToWrite, readEnvPort, writeFiles, } from "./scaffold.js";
 import { generateToken } from "./token.js";
 import { expandTilde, validateVaultPath } from "./vault.js";
@@ -22,26 +23,16 @@ const askMode = async (prompts) => {
     ], "local");
     return isMode(selected) ? selected : "local";
 };
-const GET_TOKEN_COMMAND = `docker run --rm -it --entrypoint get-token \\
-  ${REMOTE_IMAGE}`;
 /**
- * Offers to run the vault-cortex image's get-token flow in this terminal.
- * Returns true only when it ran to completion (and so printed a token the
- * user can scroll up to). The handoff log exists because the clack UI gives
- * way to raw docker output — image pull, then the tool's own login prompts.
+ * Offers to auto-capture the Obsidian Sync token via a Docker volume mount.
+ * Returns the captured token string, or undefined when the user declines or
+ * the capture fails (the caller falls back to a paste prompt).
  */
-const offerGetTokenRun = async (prompts, docker) => {
-    const runNow = await prompts.confirm("Run the get-token command now?", true);
+const offerSyncTokenCapture = async (prompts, docker) => {
+    const runNow = await prompts.confirm("Generate the token now?", true);
     if (!runNow)
-        return false;
-    prompts.log("Handing the terminal to get-token — it will ask for your Obsidian " +
-        "account login and print a token at the end.");
-    const tokenGenerated = docker.runGetToken();
-    if (!tokenGenerated) {
-        prompts.warn("get-token did not complete — you can run it later and edit .env.");
-        return false;
-    }
-    return true;
+        return undefined;
+    return captureObsidianToken({ docker, prompts }, "The token is captured automatically and stored in your .env — nothing to copy.");
 };
 /**
  * Asks for the vault path, recursing to re-prompt until it gets a usable
@@ -240,7 +231,7 @@ const runLocalInit = async (flags, deps) => {
     return 0;
 };
 // Remote flow (VPS + Obsidian Sync): resolve target dir → PUBLIC_URL →
-// VAULT_NAME → Obsidian Sync token (optionally running get-token via
+// VAULT_NAME → Obsidian Sync token (optionally running the Obsidian login via
 // Docker) → optional E2E vault password → generate token → write .env →
 // optionally start → print connect instructions. Always interactive —
 // the sync-token step can't be defaulted.
@@ -255,21 +246,17 @@ const runRemoteInit = async (flags, deps) => {
         }))));
     const publicUrl = await askPublicUrl(prompts);
     const vaultName = await askVaultName(prompts);
-    // The Obsidian Sync token comes from an interactive docker run (the
-    // get-token entrypoint logs into Obsidian). We print the command, offer to
-    // run it when Docker is usable, then ask the user to paste the result —
-    // get-token writes to the terminal, so it can't be captured automatically.
-    // A blank answer is allowed: the .env is written with an empty
-    // OBSIDIAN_AUTH_TOKEN and a fill-this-in comment.
-    prompts.note(GET_TOKEN_COMMAND, "Obsidian Sync token — generate once with");
-    const getTokenRan = docker.isDaemonRunning()
-        ? await offerGetTokenRun(prompts, docker)
-        : false;
-    // "printed above" is only true when get-token actually ran to completion.
-    const pastePrompt = getTokenRan
-        ? "Paste the Obsidian Sync token printed above (leave blank to fill in .env later):"
-        : "Paste the Obsidian Sync token (leave blank to fill in .env later):";
-    const obsidianAuthToken = (await prompts.text(pastePrompt, { defaultValue: "" })).trim();
+    // Auto-capture the Obsidian Sync token via a Docker volume mount when
+    // the daemon is reachable. Falls back to a paste prompt when capture
+    // fails or the user declines.
+    const capturedToken = docker.isDaemonRunning()
+        ? await offerSyncTokenCapture(prompts, docker)
+        : undefined;
+    // Masked prompt: the sync token is a credential and must not echo into
+    // the terminal or scrollback. An empty submission still means "fill in
+    // .env later" — clack's password prompt accepts blank input.
+    const obsidianAuthToken = capturedToken ??
+        (await prompts.password("Paste the Obsidian Sync token (leave blank to fill in .env later):")).trim();
     const usesEncryption = await prompts.confirm("Does your vault use end-to-end encryption?", false);
     const vaultPassword = usesEncryption
         ? await prompts.password("Vault encryption password:")

package/dist/main.js

@@ -1,4 +1,5 @@
 import { createDockerRunner } from "./docker.js";
+import { runGetSyncToken } from "./get-sync-token.js";
 import { runInit } from "./init.js";
 import { buildProgram } from "./program.js";
 import { createPrompts } from "./prompts.js";
@@ -16,6 +17,10 @@ export const run = async (version) => {
             docker: createDockerRunner(),
             fetchFn: fetch,
         }),
+        runGetSyncToken: (flags) => runGetSyncToken(flags, {
+            prompts: createPrompts(),
+            docker: createDockerRunner(),
+        }),
     });
     await program.parseAsync();
 };

package/dist/program.js

@@ -22,6 +22,13 @@ export const buildProgram = (options) => {
         .action(async (flags) => {
         process.exitCode = await options.runUpgrade(flags);
     });
+    program
+        .command("get-sync-token")
+        .description("Generate an Obsidian Sync auth token via Docker and print it or write it to .env")
+        .option("--dir <path>", "directory containing .env to update with the token")
+        .action(async (flags) => {
+        process.exitCode = await options.runGetSyncToken(flags);
+    });
     program.action(() => {
         program.help();
     });

package/dist/scaffold.js

@@ -57,6 +57,25 @@ export const detectMode = (envFilePath) => {
     const content = readFileSync(envFilePath, "utf8");
     return OBSIDIAN_AUTH_TOKEN_LINE.test(content) ? "remote" : "local";
 };
+/**
+ * Patches the OBSIDIAN_AUTH_TOKEN value in an existing .env file.
+ * Returns true when the patch succeeded, false when the file is missing
+ * or has no active OBSIDIAN_AUTH_TOKEN line (e.g. a local-mode .env).
+ */
+export const patchEnvObsidianToken = (envFilePath, token) => {
+    if (!existsSync(envFilePath))
+        return false;
+    const content = readFileSync(envFilePath, "utf8");
+    /** Matches the full OBSIDIAN_AUTH_TOKEN line for replacement. */
+    const fullTokenLine = /^OBSIDIAN_AUTH_TOKEN=.*$/m;
+    if (!fullTokenLine.test(content))
+        return false;
+    // Function replacement avoids $ pattern interpretation ($&, $', etc.)
+    // that String.prototype.replace applies to string replacements.
+    const patched = content.replace(fullTokenLine, () => `OBSIDIAN_AUTH_TOKEN=${token}`);
+    writeFileSync(envFilePath, patched);
+    return true;
+};
 /**
  * Writes the files into targetDir (created if missing). Existing files
  * are never overwritten silently: identical content is skipped, and differing

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vault-cortex",
-  "version": "0.5.1",
+  "version": "0.6.1",
   "description": "Set up a Vault Cortex MCP server for your Obsidian vault in one command: npx vault-cortex init",
   "license": "MIT",
   "type": "module",