@openparachute/vault 0.3.1 → 0.4.0

package/src/cli.ts

@@ -37,6 +37,8 @@ import {
   loadEnvFile,
   listVaults,
   vaultDir,
+  vaultDbPath,
+  vaultConfigPath,
   DEFAULT_PORT,
   CONFIG_DIR,
   ASSETS_DIR,
@@ -44,11 +46,13 @@ import {
   LOG_PATH,
   ERR_PATH,
   GLOBAL_CONFIG_PATH,
+  stopSignalPath,
 } from "./config.ts";
 import type { VaultConfig } from "./config.ts";
 import { DATA_DIR } from "./config.ts";
 import { installAgent, uninstallAgent, isAgentLoaded, restartAgent } from "./launchd.ts";
 import { chooseMcpUrl } from "./mcp-install.ts";
+import { buildInitSummaryLines } from "./init-summary.ts";
 import {
   runBackup,
   readLastBackup,
@@ -81,6 +85,7 @@ import { resolveBindHostname } from "./bind.ts";
 import { generateToken, createToken, listTokens, revokeToken, migrateVaultKeys } from "./token-store.ts";
 import type { TokenPermission } from "./token-store.ts";
 import { resolveCreateTokenFlags, VAULT_SCOPES } from "./scopes.ts";
+import { validateVaultName, decideInitVaultName } from "./vault-name.ts";
 import { getVaultStore } from "./vault-store.ts";
 import { upsertService, ServicesManifestError } from "./services-manifest.ts";
 import {
@@ -177,6 +182,9 @@ switch (command) {
   case "restart":
     await cmdRestart();
     break;
+  case "stop":
+    await cmdStop();
+    break;
   case "uninstall":
     await cmdUninstall(cmdArgs);
     break;
@@ -218,6 +226,27 @@ switch (command) {
 // Command implementations
 // ---------------------------------------------------------------------------
 
+/**
+ * Compute the `paths` array for the parachute-vault entry in services.json.
+ * One entry advertises every vault on this server; `paths[0]` is the
+ * canonical mount the hub stamps into `.well-known/parachute.json`, so the
+ * default vault sorts first when one is set. With no vaults yet, fall back
+ * to "/" so an early-init registration is still well-formed.
+ */
+function buildVaultServicePaths(
+  defaultVault: string | undefined,
+  vaults: string[],
+): string[] {
+  if (vaults.length === 0) return ["/"];
+  if (defaultVault && vaults.includes(defaultVault)) {
+    return [
+      `/vault/${defaultVault}`,
+      ...vaults.filter((v) => v !== defaultVault).map((v) => `/vault/${v}`),
+    ];
+  }
+  return vaults.map((v) => `/vault/${v}`);
+}
+
 async function cmdInit(args: string[] = []) {
   ensureConfigDirSync();
 
@@ -225,8 +254,37 @@ async function cmdInit(args: string[] = []) {
   // --no-mcp skips it without prompting. If both passed, --no-mcp wins
   // (safer default). Neither → prompt in a TTY, default-yes in a
   // non-TTY for back-compat with existing piped install scripts.
+  //
+  // --token / --no-token follow the same pattern for whether the API
+  // token is surfaced to the user at the end of init (for pasting into
+  // other MCP clients, scripts, or curl).
+  //
+  // --vault-name <name> skips the name prompt for non-interactive installs
+  // (validated up front; exits non-zero on invalid input).
   const flagMcpOn = args.includes("--mcp");
   const flagMcpOff = args.includes("--no-mcp");
+  const flagTokenOn = args.includes("--token");
+  const flagTokenOff = args.includes("--no-token");
+  // --autostart / --no-autostart toggle daemon registration. Default is on
+  // (preserves historical behavior). When --no-autostart is passed, init
+  // skips registering with launchd / systemd AND removes any prior
+  // registration — for CI, dev sandboxes, Docker, or any environment where
+  // another supervisor manages the process. --no-autostart wins over
+  // --autostart on the same command line (safer-default precedence).
+  const flagAutostartOn = args.includes("--autostart");
+  const flagAutostartOff = args.includes("--no-autostart");
+
+  const nameDecision = decideInitVaultName(args, {
+    isTTY: !!process.stdin.isTTY,
+  });
+  if (nameDecision.kind === "error") {
+    console.error(nameDecision.message);
+    process.exit(1);
+  }
+  // Whether the user explicitly supplied --vault-name. We use this both to
+  // pick the chosen name on first init AND to print a friendly notice if
+  // they pass --vault-name on a re-run where vaults already exist.
+  const vaultNameFlagSupplied = args.indexOf("--vault-name") !== -1;
 
   const isMac = process.platform === "darwin";
   const isLinux = process.platform === "linux";
@@ -234,14 +292,23 @@ async function cmdInit(args: string[] = []) {
 
   console.log("Parachute Vault — self-hosted knowledge graph\n");
 
-  // 1. Create default vault if none exist
+  // 1. Create the vault if none exist. The name is decided here — flag wins,
+  // else prompt in a TTY (default "default"), else fall back to "default" so
+  // piped installs keep working unchanged.
   const vaults = listVaults();
   let apiKey: string | undefined;
   if (vaults.length === 0) {
-    console.log("Creating default vault...");
-    apiKey = createVault("default");
-    console.log("  Created vault: default");
+    const chosenName =
+      nameDecision.kind === "name" ? nameDecision.name : await promptVaultName();
+    console.log(`Creating vault "${chosenName}"...`);
+    apiKey = createVault(chosenName);
+    console.log(`  Created vault: ${chosenName}`);
   } else {
+    if (vaultNameFlagSupplied) {
+      console.log(
+        `  --vault-name ignored: ${vaults.length} vault(s) already exist. Use \`parachute-vault create\` to add another.`,
+      );
+    }
     console.log(`Found ${vaults.length} existing vault(s)`);
   }
 
@@ -272,30 +339,28 @@ async function cmdInit(args: string[] = []) {
   }
   writeGlobalConfig(globalConfig);
 
-  // 2a. Register in the shared services manifest so the @openparachute/cli
+  // 2a. Register in the shared services manifest so the @openparachute/hub
   // dispatcher can discover this service and its health endpoint. Upserts
   // by name, preserving entries for other services. Non-fatal on failure —
   // init can complete without the manifest, just with a warning.
   //
-  // `paths[0]` is the canonical mount point — CLI uses it for the
-  // `.well-known/parachute.json` URL and for `parachute expose`. Advertise
-  // `/vault/<default_vault>` so MCP clients land at the scoped endpoint.
-  // When no default vault exists yet (multi-vault, no fallback), fall back
-  // to "/" — the CLI can detect and prompt.
-  const servicePath = globalConfig.default_vault
-    ? `/vault/${globalConfig.default_vault}`
-    : "/";
+  // `paths[0]` is the canonical mount point — the hub uses it for the
+  // `.well-known/parachute.json` URL and for `parachute expose`, so the
+  // default vault always sorts first. Remaining vaults follow so the hub
+  // well-known and paraclaw's attach picker see every vault on this server.
+  // Re-running init re-registers the full set; that doubles as the
+  // recovery path for installs whose services.json is stale (#208).
   try {
     upsertService({
       name: "parachute-vault",
       port: globalConfig.port || DEFAULT_PORT,
-      paths: [servicePath],
+      paths: buildVaultServicePaths(globalConfig.default_vault, allVaults),
       health: "/health",
       version: pkg.version,
     });
   } catch (err) {
     const msg = err instanceof ServicesManifestError ? err.message : String(err);
-    console.log(`  Warning: could not update ~/.parachute/services.json: ${msg}`);
+    console.error(`  Warning: could not update ~/.parachute/services.json: ${msg}`);
   }
 
   // 2b. Migrate existing legacy keys into per-vault token tables
@@ -325,28 +390,67 @@ async function cmdInit(args: string[] = []) {
     console.log();
   }
 
-  // 5b. Offer to set an owner password for OAuth consent, unless one is already set.
+  // 5b. Owner password is only needed for OAuth consent (browser-based
+  // clients like claude.ai / ChatGPT / Claude Desktop). Those paths are
+  // coming in the next few weeks; until then, skip the prompt. Users who
+  // want to expose the vault publicly today can set one manually via
+  // `parachute-vault set-password`.
   if (!hasOwnerPassword()) {
-    await promptForOwnerPassword("Set an owner password for OAuth consent?");
+    console.log();
+    console.log("Public exposure + web-AI connectors (claude.ai, ChatGPT, etc.) are coming soon.");
+    console.log("  When you're ready to expose this vault publicly, run:");
+    console.log("    parachute-vault set-password    # required for OAuth consent");
   }
 
   // 6. Install daemon (platform-aware). Idempotent — safe to re-run after
   // a folder move; this refreshes ~/.parachute/server-path and bounces the
   // daemon so the new location takes effect immediately.
-  console.log("Installing daemon...");
+  //
+  // Autostart precedence (resolved here so the user's prior config is
+  // honored on re-runs that don't pass a flag):
+  //   1. --no-autostart on this run → false (and persisted)
+  //   2. --autostart on this run    → true  (and persisted)
+  //   3. Existing config.autostart  → that value
+  //   4. Default                    → true (historical behavior)
+  // When false: skip register AND uninstall any prior registration so the
+  // flag's intent ("don't auto-start / don't auto-restart") matches reality
+  // even if a previous run had registered a daemon.
+  let autostartEnabled: boolean;
+  if (flagAutostartOff) autostartEnabled = false;
+  else if (flagAutostartOn) autostartEnabled = true;
+  else if (typeof globalConfig.autostart === "boolean") autostartEnabled = globalConfig.autostart;
+  else autostartEnabled = true;
+
+  if (flagAutostartOff || flagAutostartOn) {
+    globalConfig.autostart = autostartEnabled;
+    writeGlobalConfig(globalConfig);
+  }
+
   let serverPath: string | null = null;
-  if (isMac) {
-    ({ serverPath } = await installAgent());
-  } else if (isLinux && isSystemdAvailable()) {
-    ({ serverPath } = await installSystemdService());
+  if (!autostartEnabled) {
+    console.log("Autostart disabled — skipping daemon registration.");
+    if (isMac) {
+      await uninstallAgent();
+    } else if (isLinux && isSystemdAvailable()) {
+      await uninstallSystemdService();
+    }
+    console.log("  To run vault: parachute-vault serve   (or use your own supervisor)");
+    console.log("  To re-enable: parachute-vault init --autostart");
   } else {
-    console.log("  Auto-start not available on this platform.");
-    console.log("  Run manually: bun src/server.ts");
-    console.log("  Or use Docker: docker compose up -d");
-  }
-  if (serverPath) {
-    console.log(`  Server path:  ${serverPath}`);
-    console.log(`  Wrapper:      ~/.parachute/vault/start.sh`);
+    console.log("Installing daemon...");
+    if (isMac) {
+      ({ serverPath } = await installAgent());
+    } else if (isLinux && isSystemdAvailable()) {
+      ({ serverPath } = await installSystemdService());
+    } else {
+      console.log("  Auto-start not available on this platform.");
+      console.log("  Run manually: bun src/server.ts");
+      console.log("  Or use Docker: docker compose up -d");
+    }
+    if (serverPath) {
+      console.log(`  Server path:  ${serverPath}`);
+      console.log(`  Wrapper:      ~/.parachute/vault/start.sh`);
+    }
   }
   const bindHost = resolveBindHostname(process.env);
   console.log(`  Listening on http://${bindHost}:${globalConfig.port || DEFAULT_PORT}`);
@@ -361,11 +465,43 @@ async function cmdInit(args: string[] = []) {
   } else if (flagMcpOn) {
     addMcp = true;
   } else if (process.stdin.isTTY) {
-    addMcp = await confirm("Add Vault MCP to Claude Code (~/.claude.json)?", true);
+    addMcp = await confirm("Install Vault as an MCP server in Claude Code (~/.claude.json)?", true);
   } else {
     addMcp = true; // non-interactive: preserve the installable-via-pipe default
   }
 
+  // 7b. Surface an API token for other clients? (Codex, Goose, OpenCode,
+  // Cursor, Zed, Cline, scripts, curl.) Same flag/TTY precedence as MCP.
+  // Note: a token is always minted when addMcp is true (it gets baked into
+  // the ~/.claude.json entry); this prompt controls whether that token is
+  // printed prominently at the end so the user can paste it elsewhere.
+  let addToken: boolean;
+  if (flagTokenOff) {
+    addToken = false;
+  } else if (flagTokenOn) {
+    addToken = true;
+  } else if (process.stdin.isTTY) {
+    addToken = await confirm(
+      "Generate an API token for other MCP clients (Codex, Goose, OpenCode, Cursor, Zed, Cline), scripts, or curl?",
+      true,
+    );
+  } else {
+    addToken = true; // non-interactive: default-yes matches addMcp default
+  }
+
+  // Mint a token if we need one (for the claude.json entry and/or for
+  // prominent display) and don't already have one from vault creation.
+  // Re-runs of init that opt in will mint a fresh token — old tokens
+  // continue to work; the user can `tokens revoke` the unused ones.
+  const defaultVault = globalConfig.default_vault || "default";
+  const needToken = addMcp || addToken;
+  if (needToken && !apiKey) {
+    const store = getVaultStore(defaultVault);
+    const { fullToken } = generateToken();
+    createToken(store.db, fullToken, { label: "init", permission: "full" });
+    apiKey = fullToken;
+  }
+
   if (addMcp) {
     installMcpConfig(apiKey);
     console.log(`  MCP server added to ~/.claude.json`);
@@ -375,30 +511,31 @@ async function cmdInit(args: string[] = []) {
   }
 
   // 8. Summary
-  console.log("\n---");
   const port = globalConfig.port || DEFAULT_PORT;
-  if (apiKey) {
-    console.log(`\nYour API token: ${apiKey}`);
-    console.log("  Use this in Claude Desktop, curl, or any client.");
-    console.log("  Pass via: Authorization: Bearer <token>");
-    console.log("  Or via:   X-API-Key: <token>");
-    console.log("\nSave this — it will not be shown again.");
-  }
+  const mcpUrl = `http://127.0.0.1:${port}/vault/${defaultVault}/mcp`;
+  const lines = buildInitSummaryLines({
+    addMcp,
+    addToken,
+    apiKey,
+    configDir: CONFIG_DIR,
+    bindHost,
+    port,
+    mcpUrl,
+  });
+  for (const line of lines) console.log(line);
+}
 
-  console.log(`\nConfig:   ${CONFIG_DIR}`);
-  console.log(`Server:   http://${bindHost}:${port}`);
 
-  console.log(`\nUsage examples:`);
-  console.log(`  curl http://localhost:${port}/health`);
-  if (apiKey) {
-    console.log(`  curl -H "Authorization: Bearer ${apiKey}" http://localhost:${port}/api/notes`);
+async function promptVaultName(): Promise<string> {
+  while (true) {
+    const answer = await ask("What would you like to call this vault?", "default");
+    const v = validateVaultName(answer);
+    if (v.ok) return v.name;
+    console.log(`  ${v.error}`);
   }
-
-  console.log(`\nNext steps:`);
-  console.log(`  parachute-vault status            check everything is running`);
-  console.log(`  parachute-vault config             view/edit configuration`);
 }
 
+
 async function promptForOwnerPassword(purpose: string): Promise<boolean> {
   console.log(`\n${purpose}`);
   console.log("  Used on the OAuth consent page to authorize third-party clients");
@@ -628,9 +765,20 @@ async function cmd2fa(args: string[]) {
 }
 
 function cmdCreate(args: string[]) {
-  const name = args[0];
+  // --json: emit a single machine-readable object on stdout instead of the
+  // human-friendly multi-line print. Designed for orchestrators (the hub's
+  // POST /vaults shells out to this CLI and parses stdout). Errors still go
+  // to stderr as plain text and exit nonzero — callers branch on exit code.
+  const jsonMode = args.includes("--json");
+  // Greedy strip of any `--*` token to recover the positional vault name.
+  // Today only `--json` is recognized; any other `--foo` is silently dropped.
+  // If a future flag (e.g. `--force`, `--dry-run`) is added, the parsing
+  // here needs to whitelist it — otherwise an invalid flag becomes a silent
+  // no-op rather than a usage error.
+  const positional = args.filter((a) => !a.startsWith("--"));
+  const name = positional[0];
   if (!name) {
-    console.error("Usage: parachute-vault create <name>");
+    console.error("Usage: parachute-vault create <name> [--json]");
     process.exit(1);
   }
 
@@ -663,14 +811,49 @@ function cmdCreate(args: string[]) {
   const needsDefault = !globalConfig.default_vault
     || !listVaults().includes(globalConfig.default_vault);
   let defaultNote: string | null = null;
+  let setAsDefault = false;
   if (needsDefault) {
     globalConfig.default_vault = name;
     writeGlobalConfig(globalConfig);
+    setAsDefault = true;
     defaultNote = wasFirst
       ? `Set as default vault (unscoped routes will target "${name}")`
       : `Set as default vault (previous default was missing)`;
   }
 
+  // Re-register in services.json so the hub well-known and paraclaw's
+  // attach picker see this vault. cmdInit registers on first run; cmdCreate
+  // adds the new path on every subsequent vault. Without this, vaults
+  // created after init were invisible to the hub (#208).
+  // Warnings go to stderr to keep --json stdout clean for the orchestrator.
+  try {
+    upsertService({
+      name: "parachute-vault",
+      port: globalConfig.port || DEFAULT_PORT,
+      paths: buildVaultServicePaths(globalConfig.default_vault, listVaults()),
+      health: "/health",
+      version: pkg.version,
+    });
+  } catch (err) {
+    const msg = err instanceof ServicesManifestError ? err.message : String(err);
+    console.error(`Warning: could not update ~/.parachute/services.json: ${msg}`);
+  }
+
+  if (jsonMode) {
+    const payload = {
+      name,
+      token: key,
+      paths: {
+        vault_dir: vaultDir(name),
+        vault_db: vaultDbPath(name),
+        vault_config: vaultConfigPath(name),
+      },
+      set_as_default: setAsDefault,
+    };
+    console.log(JSON.stringify(payload));
+    return;
+  }
+
   console.log(`Vault "${name}" created.`);
   console.log(`  Path: ${vaultDir(name)}`);
   console.log(`  API token: ${key}`);
@@ -815,20 +998,38 @@ async function cmdConfig(args: string[]) {
 function cmdTokens(args: string[]) {
   const subcmd = args[0];
 
-  // parachute-vault tokens — list all tokens (across all vaults)
+  // parachute-vault tokens [list] [--vault <name>]
+  //   Default: every vault's tokens, grouped by vault.
+  //   --vault <name>: only that vault.
   if (!subcmd || subcmd === "list") {
-    const vaults = listVaults();
+    const vaultFlag = args.indexOf("--vault");
+    const onlyVault = vaultFlag !== -1 ? args[vaultFlag + 1] : null;
+    if (vaultFlag !== -1 && !onlyVault) {
+      console.error("--vault requires a value.");
+      process.exit(1);
+    }
+    const vaults = onlyVault ? [onlyVault] : listVaults();
     let anyTokens = false;
 
     for (const vaultName of vaults) {
       const vc = readVaultConfig(vaultName);
-      if (!vc) continue;
+      if (!vc) {
+        if (onlyVault) {
+          console.error(`Vault "${vaultName}" not found.`);
+          process.exit(1);
+        }
+        continue;
+      }
       const store = getVaultStore(vaultName);
       // Ensure legacy keys are migrated
       const globalCfg = readGlobalConfig();
       migrateVaultKeys(store.db, vc.api_keys, globalCfg.api_keys);
 
-      const tokens = listTokens(store.db);
+      // Per-vault filter (v16): only tokens bound to this vault, plus
+      // legacy NULL-bound (server-wide) rows. The `[server-wide]` annotation
+      // surfaces the latter so an operator listing one vault still sees
+      // tokens that authenticate cross-vault.
+      const tokens = listTokens(store.db, { vaultName });
       if (tokens.length === 0) continue;
       anyTokens = true;
 
@@ -836,7 +1037,8 @@ function cmdTokens(args: string[]) {
       for (const t of tokens) {
         const expiry = t.expires_at ? ` (expires: ${t.expires_at})` : "";
         const lastUsed = t.last_used_at ? ` (last used: ${t.last_used_at})` : "";
-        console.log(`  ${t.id}  ${t.label}  [${t.permission}]${expiry}${lastUsed}`);
+        const serverWide = t.vault_name === null ? " [server-wide]" : "";
+        console.log(`  ${t.id}  ${t.label}  [${t.permission}]${serverWide}${expiry}${lastUsed}`);
       }
       console.log();
     }
@@ -847,12 +1049,26 @@ function cmdTokens(args: string[]) {
     return;
   }
 
-  // parachute-vault tokens create --vault <name>
+  // parachute-vault tokens create [--vault <name> | --all]
   //   [--scope vault:read,vault:write | --read | --permission full|read]
   //   [--expires <duration>] [--label <label>]
+  //
+  // Per-vault binding (v16): the minted token is pinned to <vaultName>
+  // unless --all is passed, in which case the token is server-wide
+  // (vault_name = NULL) and authenticates against any vault. --all is
+  // the explicit opt-out — there's no implicit fall-through to server-wide.
   if (subcmd === "create") {
     const vaultFlag = args.indexOf("--vault");
+    const allFlag = args.includes("--all");
+    if (allFlag && vaultFlag !== -1) {
+      console.error("--vault and --all are mutually exclusive.");
+      process.exit(1);
+    }
     const vaultName = vaultFlag !== -1 ? args[vaultFlag + 1] : (readGlobalConfig().default_vault || "default");
+    if (!vaultName) {
+      console.error("--vault requires a value.");
+      process.exit(1);
+    }
 
     const vc = readVaultConfig(vaultName);
     if (!vc) {
@@ -876,6 +1092,10 @@ function cmdTokens(args: string[]) {
     let expiresAt: string | null = null;
     if (expiresFlag !== -1) {
       const dur = args[expiresFlag + 1];
+      if (!dur) {
+        console.error("--expires requires a value (e.g. 7d, 30d, 24h, 1y).");
+        process.exit(1);
+      }
       expiresAt = parseDuration(dur);
       if (!expiresAt) {
         console.error(`Invalid duration: ${dur}. Use format like 7d, 30d, 24h, 1y.`);
@@ -884,7 +1104,7 @@ function cmdTokens(args: string[]) {
     }
 
     const labelFlag = args.indexOf("--label");
-    const label = labelFlag !== -1 ? args[labelFlag + 1] : "default";
+    const label = (labelFlag !== -1 ? args[labelFlag + 1] : undefined) ?? "default";
 
     const store = getVaultStore(vaultName);
     const { fullToken } = generateToken();
@@ -893,15 +1113,22 @@ function cmdTokens(args: string[]) {
       permission,
       scopes,
       expires_at: expiresAt,
+      // v16 binding: pin to the vault we minted in unless --all was passed
+      // (which leaves vault_name NULL = legacy server-wide).
+      vault_name: allFlag ? null : vaultName,
     });
 
     const displayScopes = scopes ?? [...VAULT_SCOPES];
-    console.log(`Created token for vault "${vaultName}":`);
+    const heading = allFlag
+      ? `Created server-wide token (authenticates against any vault):`
+      : `Created token for vault "${vaultName}":`;
+    console.log(heading);
     console.log(`  Token:      ${fullToken}`);
     console.log(`  Permission: ${permission}`);
     console.log(`  Scopes:     ${displayScopes.join(" ")}`);
     if (expiresAt) console.log(`  Expires:    ${expiresAt}`);
     console.log(`  Label:      ${label}`);
+    if (!allFlag) console.log(`  Vault:      ${vaultName}`);
     console.log();
     console.log("Save this token — it will not be shown again.");
     return;
@@ -917,6 +1144,10 @@ function cmdTokens(args: string[]) {
 
     const vaultFlag = args.indexOf("--vault");
     const vaultName = vaultFlag !== -1 ? args[vaultFlag + 1] : (readGlobalConfig().default_vault || "default");
+    if (!vaultName) {
+      console.error("--vault requires a value.");
+      process.exit(1);
+    }
 
     const vc = readVaultConfig(vaultName);
     if (!vc) {
@@ -942,8 +1173,8 @@ function cmdTokens(args: string[]) {
 function parseDuration(dur: string): string | null {
   const match = dur.match(/^(\d+)(h|d|w|m|y)$/);
   if (!match) return null;
-  const n = parseInt(match[1], 10);
-  const unit = match[2];
+  const n = parseInt(match[1]!, 10);
+  const unit = match[2]!;
   const now = new Date();
   switch (unit) {
     case "h": now.setHours(now.getHours() + n); break;
@@ -1001,6 +1232,41 @@ async function cmdRestart() {
   process.exit(1);
 }
 
+async function cmdStop() {
+  loadEnvFile();
+  const port = readGlobalConfig().port || DEFAULT_PORT;
+  const sentinel = stopSignalPath();
+
+  // Health check first: avoid leaving a stale sentinel that would kill the
+  // *next* server boot. The server clears any pre-existing sentinel on
+  // startup, but only after it loads — a sentinel written between launch
+  // and the first poll could still win the race. Skipping the write when
+  // nothing is listening is the cheap, obvious guard.
+  const health = await checkHealth(port);
+  if (health.status === "not-listening" || health.status === "error") {
+    console.log(`Vault is not running (${health.status}${health.error ? `: ${health.error}` : ""}).`);
+    return;
+  }
+
+  ensureConfigDirSync();
+  writeFileSync(sentinel, `${new Date().toISOString()}\n`);
+  console.log(`Stop signal written: ${sentinel}`);
+
+  // Wait briefly for the server to pick up the sentinel and stop responding.
+  // Polls match the server's 500ms cadence; give it ~5s before giving up.
+  const start = Date.now();
+  while (Date.now() - start < 5_000) {
+    await new Promise((r) => setTimeout(r, 600));
+    const h = await checkHealth(port);
+    if (h.status === "not-listening" || h.status === "error") {
+      console.log(`Vault stopped (${Math.round((Date.now() - start) / 100) / 10}s).`);
+      return;
+    }
+  }
+  console.error("Vault did not stop within 5s. Check vault logs or `parachute-vault status`.");
+  process.exit(1);
+}
+
 async function cmdStatus() {
   loadEnvFile();
   const globalConfig = readGlobalConfig();
@@ -1819,16 +2085,27 @@ async function cmdImport(args: string[]) {
 
   const positional: string[] = [];
   for (let i = 0; i < args.length; i++) {
-    if (args[i] === "--format") {
-      format = args[++i];
-    } else if (args[i] === "--vault") {
-      vaultName = args[++i];
-    } else if (args[i] === "--dry-run") {
+    const arg = args[i]!;
+    if (arg === "--format") {
+      const v = args[++i];
+      if (!v) {
+        console.error("--format requires a value.");
+        process.exit(1);
+      }
+      format = v;
+    } else if (arg === "--vault") {
+      const v = args[++i];
+      if (!v) {
+        console.error("--vault requires a value.");
+        process.exit(1);
+      }
+      vaultName = v;
+    } else if (arg === "--dry-run") {
       dryRun = true;
-    } else if (args[i] === "--obsidian") {
+    } else if (arg === "--obsidian") {
       format = "obsidian";
     } else {
-      positional.push(args[i]);
+      positional.push(arg);
     }
   }
   sourcePath = positional[0] ?? "";
@@ -1931,10 +2208,16 @@ async function cmdExport(args: string[]) {
 
   const positional: string[] = [];
   for (let i = 0; i < args.length; i++) {
-    if (args[i] === "--vault") {
-      vaultName = args[++i];
+    const arg = args[i]!;
+    if (arg === "--vault") {
+      const v = args[++i];
+      if (!v) {
+        console.error("--vault requires a value.");
+        process.exit(1);
+      }
+      vaultName = v;
     } else {
-      positional.push(args[i]);
+      positional.push(arg);
     }
   }
   outputPath = positional[0] ?? "";
@@ -2058,7 +2341,7 @@ function usage() {
   console.log(`
 Parachute Vault — self-hosted knowledge graph
 
-If you installed via the Parachute CLI, prefer the wrapper commands for
+If you installed via the Parachute Hub, prefer the wrapper commands for
 lifecycle — \`parachute start vault\`, \`parachute stop vault\`,
 \`parachute status\` — and use the vault-direct commands below for setup,
 data, and debugging.
@@ -2066,7 +2349,22 @@ data, and debugging.
 ── Standard use ───────────────────────────────────────────────────────
 
 Setup:
-  parachute-vault init [--mcp | --no-mcp]  Set up everything (one command, idempotent)
+  parachute-vault init [--mcp|--no-mcp] [--token|--no-token] [--vault-name <name>]
+                       [--autostart|--no-autostart]
+                                           Set up everything (one command, idempotent).
+                                           --mcp/--no-mcp controls the Claude Code MCP entry;
+                                           --token/--no-token controls whether an API token is
+                                           printed for pasting into other MCP clients / scripts.
+                                           --vault-name skips the prompt and names the vault
+                                           (lowercase alphanumeric, hyphens, underscores;
+                                           omit to be prompted interactively, default "default").
+                                           --autostart (default) registers vault with launchd /
+                                           systemd so it starts on boot AND auto-restarts on
+                                           crash. --no-autostart skips daemon registration AND
+                                           uninstalls any prior registration — for CI, dev
+                                           sandboxes, Docker, or environments where another
+                                           supervisor manages the process. Persists in
+                                           config.yaml as 'autostart: true|false'.
   parachute-vault doctor                   Diagnose install/config issues
   parachute-vault uninstall [--wipe] [--yes]
                                            Remove daemon + MCP entry; --wipe also removes vaults, .env,
@@ -2076,15 +2374,19 @@ Setup:
   parachute --version                      Print the installed version (alias: -v, version)
 
 Vaults:
-  parachute-vault create <name>            Create a new vault
+  parachute-vault create <name> [--json]   Create a new vault (--json: emit { name, token, paths, set_as_default })
   parachute-vault list                     List all vaults
   parachute-vault remove <name> [--yes]    Remove a vault
   parachute-vault mcp-install              Add vault MCP to Claude
 
 Tokens:
-  parachute-vault tokens                          List all tokens
-  parachute-vault tokens create                   Create a full-access token in the default vault
-  parachute-vault tokens create --vault <name>    Create a token in a specific vault
+  parachute-vault tokens                          List tokens (every vault)
+  parachute-vault tokens list --vault <name>      List tokens for one vault only
+  parachute-vault tokens create                   Create a vault-bound token in the default vault
+  parachute-vault tokens create --vault <name>    Create a token bound to a specific vault
+  parachute-vault tokens create --all             Create a server-wide token (vault_name=NULL).
+                                                  Authenticates against any vault — use sparingly,
+                                                  for cross-vault automation only.
   parachute-vault tokens create --read            Read-only token (shorthand for --scope vault:read)
   parachute-vault tokens create --scope vault:write
                                                   Narrow the token's scopes. Accepts a comma-separated
@@ -2119,9 +2421,9 @@ Import/Export:
 
 ── Advanced / standalone ──────────────────────────────────────────────
 
-Direct daemon controls. For normal use, prefer the Parachute CLI wrappers
+Direct daemon controls. For normal use, prefer the Parachute Hub wrappers
 — they add PID tracking, log rotation, and cross-service \`parachute status\`
-visibility. Use these when running vault without the CLI or when debugging.
+visibility. Use these when running vault without the hub or when debugging.
 
   parachute-vault serve                    Run server in the foreground (no PID tracking).
                                            Prefer \`parachute start vault\` for managed lifecycle.
@@ -2129,5 +2431,9 @@ visibility. Use these when running vault without the CLI or when debugging.
                                            Prefer \`parachute status\` for a cross-service view.
   parachute-vault logs                     Stream server logs
   parachute-vault restart                  Restart the daemon
+  parachute-vault stop                     Signal a graceful shutdown of the running server
+                                           (writes \`~/.parachute/vault/stop.signal\` — useful
+                                           when no signal channel is available, e.g. Docker
+                                           exec or unmanaged foreground runs).
 `);
 }