Skip to content

README.md

Latest commit

 

History

History
176 lines (127 loc) · 5.75 KB

README.md

File metadata and controls

176 lines (127 loc) · 5.75 KB
Raw

vault-cortex (CLI)

Set up a Vault Cortex MCP server for your Obsidian vault in one command:

npx vault-cortex@latest init

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 — including its images, PDFs, canvases, and data files — see the full feature overview. The server runs as a Docker container; this CLI scaffolds the config and manages the container so you don't have to.

npx vault-cortex init — the interactive setup wizard picks a mode, finds your vault, generates the config, and starts the server

Commands

  • init — interactive setup: scaffold the config, generate the auth token, start the server
  • upgrade — pull the latest image and re-create the container; your data stays
  • restart — re-create the container so your .env edits take effect; no image pull
  • logs — show the server's logs, live or after the fact
  • down — stop and remove the container; your data stays
  • get-sync-token — generate an Obsidian Sync auth token for remote setups

Run npx vault-cortex <command> --help for all flags.

init

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, 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. During a remote setup, init offers to run get-sync-token for you when Docker is available.

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:

npx vault-cortex@latest init --yes --vault-path /path/to/YourVault

upgrade

Pull the latest image, re-create the container, and verify health:

npx vault-cortex@latest upgrade

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).

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 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.

restart

Re-create the container from your .env and verify health:

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, it never pulls a new image: you get the same server version back, with your current settings applied.

Use --dir <path> if your config isn't in ./vault-cortex.

logs

Show the server's logs:

npx vault-cortex@latest logs

Flags:

  • --follow — keep streaming new output until you press ctrl-C
  • --since <time> — only logs newer than this (e.g. 10m, 2h, or a timestamp)
  • --dir <path> — directory containing .env (default ./vault-cortex)
npx vault-cortex@latest logs --follow --since 10m

down

Stop and remove the container:

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. 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.

get-sync-token

Generate an Obsidian Sync auth token — needed for remote setups — without leaving the CLI:

npx vault-cortex@latest 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:

npx vault-cortex@latest get-sync-token --dir ./vault-cortex

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 or a Docker-compatible runtime (e.g. OrbStack, Colima, Podman) to run the server — the CLI manages the container through the docker command

Docs