vault-cortex 0.9.0-beta.45 → 0.10.0

package/README.md

@@ -25,6 +25,8 @@ manages the container so you don't have to.
   restart to apply them
 - [`upgrade`](#upgrade) — pull the latest image and re-create the container;
   your data stays
+- [`start`](#start) — start the server with your saved settings, e.g. after
+  `down`
 - [`restart`](#restart) — re-create the container so your `.env` edits take
   effect; no image pull
 - [`logs`](#logs) — show the server's logs, live or after the fact
@@ -49,16 +51,17 @@ What it does:
 2. Offers the most common optional settings — memory layer and folder,
    file tools, semantic search, port, timezone (plus sync direction for
    remote) — press enter to keep the defaults, or pick the ones you want to
-   change. Skipped when the target directory already has a `.env` (use
-   [`configure`](#configure) instead)
+   change
 3. Generates a `.env` file with a securely generated `MCP_AUTH_TOKEN`
 4. Optionally starts the container and waits for the health check
 5. Prints your connection details — the MCP URL, your auth token, and how to
    connect your client
 
-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.
+Re-running init where a setup already exists asks first — declining leaves
+everything unchanged and points you at [`configure`](#configure), the right
+tool for changing settings in place. 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.
 
 Flags:
 
@@ -115,6 +118,22 @@ 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.
 
+## start
+
+Start the server with your saved settings and verify health:
+
+```bash
+npx vault-cortex@latest start
+```
+
+This is the command the CLI's own guidance points to whenever the server
+isn't running — after [`down`](#down), or an `init` where the server wasn't
+started. It's the same cycle as [`restart`](#restart) under the name you'd
+look for: any existing container is replaced, and Docker pulls the server
+image automatically on a first start.
+
+Use `--dir <path>` if your config isn't in `./vault-cortex`.
+
 ## restart
 
 Re-create the container from your `.env` and verify health:
@@ -125,7 +144,7 @@ npx vault-cortex@latest restart
 
 Use it after editing `.env` — settings are only read when the container is
 created, so a plain `docker restart` won't pick them up, but this will. Unlike
-[`upgrade`](#upgrade), it never pulls a new image: you get the same server
+[`upgrade`](#upgrade), it never updates the server image: you get the same
 version back, with your current settings applied.
 
 Use `--dir <path>` if your config isn't in `./vault-cortex`.
@@ -159,7 +178,7 @@ npx vault-cortex@latest down
 
 Safe by design: your vault, search index, and `.env` settings all live
 outside the container, so nothing is lost. Start again any time with
-[`restart`](#restart). Running `down` when nothing is running is fine — it
+[`start`](#start). Running `down` when nothing is running is fine — it
 just tells you there's nothing to stop.
 
 Use `--dir <path>` if your config isn't in `./vault-cortex`.

package/dist/init.js

@@ -2,7 +2,7 @@ import { existsSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { buildLocalEnv, buildRemoteEnv } from "./env.js";
 import { captureObsidianToken } from "./get-sync-token.js";
-import { buildDaemonNotRunningMessage, buildDockerNotInstalledMessage, buildLocalConnectMessage, buildRemoteConnectMessage, } from "./messages.js";
+import { buildDaemonNotRunningMessage, buildDockerNotInstalledMessage, buildLocalConnectMessage, buildRemoteConnectMessage, startCommand, } from "./messages.js";
 import { pollHealth } from "./docker.js";
 import { reportPublicUrlProbe } from "./lifecycle.js";
 import { applyOptionalSettings, askOptionalSettings, derivePublicUrlOverride, } from "./optional-settings.js";
@@ -162,12 +162,12 @@ const offerDockerRun = async (params, deps) => {
     const { prompts, docker, fetchFn } = deps;
     const daemonStatus = docker.daemonStatus();
     if (daemonStatus !== "running") {
-        const upgradeHint = `npx vault-cortex@latest upgrade --dir "${targetDir}"`;
+        const startHint = startCommand(targetDir);
         prompts.warn(daemonStatus === "not-installed"
             ? buildDockerNotInstalledMessage({
-                nextStep: `\nThen start the server with:\n  ${upgradeHint}`,
+                nextStep: `\nThen start the server with:\n  ${startHint}`,
             })
-            : buildDaemonNotRunningMessage(`, then run:\n  ${upgradeHint}`));
+            : buildDaemonNotRunningMessage(`, then run:\n  ${startHint}`));
         return false;
     }
     const startNow = await prompts.confirm("Start the server now?", true);
@@ -239,18 +239,15 @@ const runLocalInit = async (flags, deps) => {
     const token = generateToken();
     // Guided optional settings: the chooser reads current values from the
     // generated defaults; enter with nothing picked keeps them all. --yes
-    // skips the chooser (non-interactive by contract), and so does an existing
-    // .env — the conflict prompt defaults to keeping it, which would discard
-    // the answers; settings on an existing deployment are configure's job.
+    // skips the chooser (non-interactive by contract). An existing .env does
+    // NOT skip it: every interactive path here passed the re-init guard, so the
+    // user asked for a full re-run — the answers land in the regenerated file
+    // when they overwrite at the conflict prompt (keeping it discards them,
+    // which the write report states). In-place edits stay configure's job.
     const defaultEnvContent = buildLocalEnv({ mcpAuthToken: token, vaultPath });
-    const envAlreadyExists = existsSync(join(targetDir, ".env"));
-    const offerSettingsChooser = !flags.yes && !envAlreadyExists;
-    if (!flags.yes && envAlreadyExists) {
-        prompts.log('Found an existing .env — settings prompts skipped. Adjust settings with "npx vault-cortex@latest configure".');
-    }
-    const optionalOverrides = offerSettingsChooser
-        ? await askOptionalSettings({ mode: "local", envContent: defaultEnvContent }, prompts)
-        : {};
+    const optionalOverrides = flags.yes
+        ? {}
+        : await askOptionalSettings({ mode: "local", envContent: defaultEnvContent }, prompts);
     const envContent = applyOptionalSettings(defaultEnvContent, derivePublicUrlOverride(defaultEnvContent, optionalOverrides));
     // Conflict policy: identical existing files are skipped silently;
     // differing ones prompt per file (default keep). --yes never overwrites —
@@ -317,8 +314,10 @@ const runRemoteInit = async (flags, deps) => {
         : undefined;
     const token = generateToken();
     // Guided optional settings, mirroring the local flow — remote also offers
-    // SYNC_MODE. Remote init is always interactive (no --yes), so only an
-    // existing .env skips the chooser here.
+    // SYNC_MODE. Remote init is always interactive (no --yes), and any existing
+    // .env passed the re-init guard — a consented re-run gets the full setup,
+    // chooser included (see the local flow's comment for the overwrite/keep
+    // semantics).
     const defaultEnvContent = buildRemoteEnv({
         mcpAuthToken: token,
         publicUrl,
@@ -326,13 +325,7 @@ const runRemoteInit = async (flags, deps) => {
         vaultName,
         vaultPassword,
     });
-    const envAlreadyExists = existsSync(join(targetDir, ".env"));
-    if (envAlreadyExists) {
-        prompts.log('Found an existing .env — settings prompts skipped. Adjust settings with "npx vault-cortex@latest configure".');
-    }
-    const optionalOverrides = envAlreadyExists
-        ? {}
-        : await askOptionalSettings({ mode: "remote", envContent: defaultEnvContent }, prompts);
+    const optionalOverrides = await askOptionalSettings({ mode: "remote", envContent: defaultEnvContent }, prompts);
     const envContent = applyOptionalSettings(defaultEnvContent, derivePublicUrlOverride(defaultEnvContent, optionalOverrides));
     const files = buildFilesToWrite(envContent);
     const results = await writeFiles({ targetDir, files }, confirmOverwrite(prompts));

package/dist/lifecycle.js

@@ -41,9 +41,7 @@ export const resolveDeployment = (dirFlag, prompts) => {
             `Add this line to your .env:\n  PUBLIC_URL=http://localhost:${port}`);
         return undefined;
     }
-    // Local's PUBLIC_URL is the derived localhost URL — probing it would
-    // duplicate the health check recreateContainer just ran, so remote-only.
-    const publicUrl = mode === "remote" ? readEnvPublicUrl(envFilePath) : undefined;
+    const publicUrl = readEnvPublicUrl(envFilePath);
     return { mode, targetDir, envFilePath, port, vaultPath, publicUrl };
 };
 /**
@@ -59,6 +57,15 @@ export const ensureDaemonRunning = (docker, prompts) => {
         : buildDaemonNotRunningMessage("."));
     return false;
 };
+/**
+ * Whether the post-start public-URL probe should run — and, when it should,
+ * proof that publicUrl is set. Local's PUBLIC_URL is the derived localhost
+ * URL, so probing it would only duplicate the health check the start cycle
+ * just ran.
+ */
+const shouldRunPostStartProbe = (deployment) => {
+    return deployment.mode === "remote" && deployment.publicUrl !== undefined;
+};
 /**
  * One-shot informational probe of the public /healthz after a confirmed
  * container start. Never a gate: a failure warns and the command still
@@ -127,7 +134,7 @@ export const recreateContainer = async (params, deps) => {
     spinner.stop("Server is up — health check passed.");
     // Informational only — the container is confirmed healthy above, so the
     // public-URL result never changes the exit code.
-    if (deployment.mode === "remote" && deployment.publicUrl) {
+    if (shouldRunPostStartProbe(deployment)) {
         await reportPublicUrlProbe(deployment.publicUrl, { prompts, fetchFn });
     }
     return 0;
@@ -157,7 +164,7 @@ export const runDown = async (flags, deps) => {
         return 1;
     }
     prompts.log("Container stopped and removed. Your vault data, search index, and settings are untouched.");
-    prompts.outro(`Start again with: npx vault-cortex@latest restart --dir "${initialized.targetDir}"`);
+    prompts.outro(`Start again with: npx vault-cortex@latest start --dir "${initialized.targetDir}"`);
     return 0;
 };
 /**
@@ -174,7 +181,7 @@ export const runLogs = async (flags, deps) => {
     if (!ensureDaemonRunning(docker, prompts))
         return 1;
     if (!docker.containerExists()) {
-        prompts.error("No vault-cortex container — start it with `npx vault-cortex@latest restart`.");
+        prompts.error(`No vault-cortex container — start it with: npx vault-cortex@latest start --dir "${initialized.targetDir}"`);
         return 1;
     }
     return await docker.streamLogs({
@@ -183,13 +190,13 @@ export const runLogs = async (flags, deps) => {
     });
 };
 /**
- * Re-creates the container from the .env on disk and verifies health.
- * Unlike `docker restart`, this applies .env edits (the env-file is only
- * read at container creation); unlike upgrade, it never pulls an image.
+ * Shared start/restart cycle: re-create the container from the .env on disk
+ * and verify health. One implementation, two command names — the labels are
+ * the only divergence, phrased for the intent each name serves.
  */
-export const runRestart = async (flags, deps) => {
+const runRecreateFromEnv = async (flags, deps, labels) => {
     const { prompts, docker, fetchFn } = deps;
-    prompts.intro("vault-cortex restart");
+    prompts.intro(labels.introTitle);
     const deployment = resolveDeployment(flags.dir, prompts);
     if (!deployment)
         return 1;
@@ -198,7 +205,33 @@ export const runRestart = async (flags, deps) => {
     const exitCode = await recreateContainer({ deployment, healthTimeoutMs: deps.healthTimeoutMs }, { prompts, docker, fetchFn });
     if (exitCode !== 0)
         return exitCode;
-    prompts.log("Applied the current .env settings.");
-    prompts.outro("Restart complete.");
+    prompts.log(labels.successLog);
+    prompts.outro(labels.outroMessage);
     return 0;
 };
+/**
+ * Starts the server from the saved .env — the command name users reach for
+ * when nothing is running yet (after `down`, or an init that skipped the
+ * start offer). Same cycle as restart: if a container is already running it
+ * is safely replaced, and `docker run` pulls the image when it's missing.
+ */
+export const runStart = async (flags, deps) => {
+    return runRecreateFromEnv(flags, deps, {
+        introTitle: "vault-cortex start",
+        successLog: "Started with the settings from .env.",
+        outroMessage: "Start complete.",
+    });
+};
+/**
+ * Re-creates the container from the .env on disk and verifies health.
+ * Unlike `docker restart`, this applies .env edits (the env-file is only
+ * read at container creation); unlike upgrade, it never replaces an image
+ * you already have (`docker run` still pulls when none exists locally).
+ */
+export const runRestart = async (flags, deps) => {
+    return runRecreateFromEnv(flags, deps, {
+        introTitle: "vault-cortex restart",
+        successLog: "Applied the current .env settings.",
+        outroMessage: "Restart complete.",
+    });
+};

package/dist/main.js

@@ -2,7 +2,7 @@ import { runConfigure } from "./configure.js";
 import { createDockerRunner } from "./docker.js";
 import { runGetSyncToken } from "./get-sync-token.js";
 import { runInit } from "./init.js";
-import { runDown, runLogs, runRestart } from "./lifecycle.js";
+import { runDown, runLogs, runRestart, runStart } from "./lifecycle.js";
 import { buildProgram } from "./program.js";
 import { createPrompts } from "./prompts.js";
 import { runUpgrade } from "./upgrade.js";
@@ -24,6 +24,11 @@ export const run = async (version) => {
             docker: createDockerRunner(),
             fetchFn: fetch,
         }),
+        runStart: (flags) => runStart(flags, {
+            prompts: createPrompts(),
+            docker: createDockerRunner(),
+            fetchFn: fetch,
+        }),
         runRestart: (flags) => runRestart(flags, {
             prompts: createPrompts(),
             docker: createDockerRunner(),

package/dist/messages.js

@@ -45,14 +45,18 @@ export const buildDockerNotInstalledMessage = (params) => {
 // targetDir is quoted: these lines are meant to be copy-pasted into a
 // shell, and an unquoted path breaks on spaces or special characters.
 const upgradeCommand = (targetDir) => `npx vault-cortex@latest upgrade --dir "${targetDir}"`;
-const startServerLine = (targetDir) => `Start the server:\n  ${upgradeCommand(targetDir)}`;
+// Start guidance prints `start`, not `upgrade` — telling a user who has never
+// started anything to run "upgrade" reads as updating something they don't
+// have. `start` runs the same re-create cycle and pulls the image on demand.
+export const startCommand = (targetDir) => `npx vault-cortex@latest start --dir "${targetDir}"`;
+const startServerLine = (targetDir) => `Start the server:\n  ${startCommand(targetDir)}`;
 /** Remote start line: running, blocked on the missing sync token, or ready to start. */
 const remoteStartLine = (params) => {
     const { targetDir, started, obsidianTokenMissing } = params;
     if (started)
         return "The server is running.";
     if (obsidianTokenMissing) {
-        return `Fill in OBSIDIAN_AUTH_TOKEN in ${targetDir}/.env, then start the server:\n  ${upgradeCommand(targetDir)}`;
+        return `Fill in OBSIDIAN_AUTH_TOKEN in ${targetDir}/.env, then start the server:\n  ${startCommand(targetDir)}`;
     }
     return startServerLine(targetDir);
 };

package/dist/program.js

@@ -29,6 +29,13 @@ export const buildProgram = (options) => {
         .action(async (flags) => {
         process.exitCode = await options.runUpgrade(flags);
     });
+    program
+        .command("start")
+        .description("Start the server with the saved settings and verify health (same cycle as restart)")
+        .option("--dir <path>", "directory containing .env (default: ./vault-cortex)")
+        .action(async (flags) => {
+        process.exitCode = await options.runStart(flags);
+    });
     program
         .command("restart")
         .description("Re-create the container from .env and verify health (applies .env edits; no image pull)")

package/dist/scaffold.js

@@ -40,8 +40,11 @@ export const readEnvVaultPath = (envFilePath) => {
 };
 /**
  * Returns true when the .env file has an active (uncommented) PUBLIC_URL line.
- * Used by upgrade to detect .env files from the old compose-based CLI, where
- * PUBLIC_URL was provided by docker-compose defaults rather than the .env.
+ * It's the FALSE result that carries the signal: the old compose-based CLI's
+ * generated .env never held a PUBLIC_URL line (the compose file's environment
+ * defaults supplied it), so a local .env without one predates the docker-run
+ * migration — callers use the negation to ask the user to add the line
+ * instead of starting a server missing a required variable.
  */
 export const hasEnvPublicUrl = (envFilePath) => {
     if (!existsSync(envFilePath))
@@ -61,7 +64,11 @@ export const readEnvPublicUrl = (envFilePath) => {
     // A whitespace-only line matches the regex and trims to "" — normalize to
     // undefined so the non-empty contract holds ("" is never a legitimate URL).
     const publicUrlValue = match?.[1].trim();
-    return publicUrlValue || undefined;
+    // Strip trailing slashes (mirroring askPublicUrl's prompt-side
+    // normalization): consumers append paths to this base, and a hand-edited
+    // `https://host/` would otherwise print broken `//mcp` connect URLs.
+    const normalizedPublicUrl = publicUrlValue?.replace(/\/+$/, "");
+    return normalizedPublicUrl || undefined;
 };
 /**
  * Detects the deployment mode from a .env file. Remote mode requires

package/package.json

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