CLI

Relevant source files

• assets/demo-cli-init.gif
• assets/social-preview.png
• assets/social-preview.svg
• cli/README.md
• cli/src/__tests__/command-stubs.ts
• cli/src/__tests__/configure.test.ts
• cli/src/__tests__/docker.test.ts
• cli/src/__tests__/env.test.ts
• cli/src/__tests__/get-sync-token.test.ts
• cli/src/__tests__/init.test.ts
• cli/src/__tests__/lifecycle.test.ts
• cli/src/__tests__/messages.test.ts
• cli/src/__tests__/optional-settings.test.ts
• cli/src/__tests__/program.test.ts
• cli/src/__tests__/upgrade.test.ts
• cli/src/configure.ts
• cli/src/docker.ts
• cli/src/env.ts
• cli/src/get-sync-token.ts
• cli/src/init.ts
• cli/src/lifecycle.ts
• cli/src/main.ts
• cli/src/messages.ts
• cli/src/optional-settings.ts
• cli/src/program.ts
• cli/src/prompts.ts
• cli/src/scaffold.ts
• cli/src/upgrade.ts
• cli/tsconfig.json
• llms-install.md
• scripts/sync-cli-env-blocks.ts

The vault-cortex npm package (found in the cli/ directory) is a lifecycle and scaffolding tool designed to manage Vault Cortex deployments. By running npx vault-cortex@latest <command>, users can interactively configure their environment, upgrade server versions, and manage the underlying Docker containers without manual docker command construction cli/README.md1-16

System Architecture and Data Flow

The CLI is a TypeScript application that orchestrates the transition from user intent (prompts/flags) to a filesystem-ready deployment. It abstracts Docker complexities into a set of high-level commands.

CLI Module Structure

The following diagram maps the logical responsibilities of the CLI to their corresponding code entities.

Diagram: CLI Component Map

Sources: cli/src/main.ts1-15 cli/src/program.ts1-20 cli/src/init.ts1-32 cli/src/scaffold.ts1-19 cli/src/docker.ts1-10 cli/src/env.ts16-26

---

Commands

The CLI provides a suite of commands to manage the server lifecycle cli/README.md20-31

Command	Implementation	Purpose
init	init.ts	Interactive setup: scaffolds .env, generates auth tokens, and starts the server.
configure	configure.ts	Interactive settings editor for MEMORY_ENABLED, EMBEDDING_ENABLED, PORT, etc.
upgrade	upgrade.ts	Pulls the latest Docker image and re-creates the container while preserving data.
restart	lifecycle.ts	Re-creates the container to apply .env changes without pulling a new image.
logs	docker.ts	Streams the container logs to the terminal via docker logs.
down	docker.ts	Stops and removes the container; data in volumes/bind-mounts persists.
get-sync-token	get-sync-token.ts	Interactive flow to capture an Obsidian Sync token via a temporary container.

Sources: cli/README.md20-33 cli/src/upgrade.ts25-40 cli/src/get-sync-token.ts12-20

---

Interactive Initialization Flow

The runInit function in init.ts manages the init command lifecycle cli/src/init.ts237-240 It supports two primary deployment modes: Local (bind-mounted vault) and Remote (Obsidian Sync).

1. Environment Validation

The CLI verifies if the Docker daemon is reachable via isDaemonRunning() before proceeding cli/src/docker.ts173-174 It also ensures the target directory exists or can be created cli/src/init.ts34-37

2. Information Gathering

The CLI uses @clack/prompts to gather deployment details:

• Mode Selection: Choosing between local or remote cli/src/init.ts39-57
• Vault Path (Local): Validates the absolute path and checks for the existence of a .obsidian folder cli/src/init.ts83-100
• Sync Credentials (Remote): Collects PUBLIC_URL cli/src/init.ts127-155 VAULT_NAME cli/src/init.ts158-169 and optionally VAULT_PASSWORD cli/src/init.ts171-180
• Token Capture: Offers to run runObsidianLogin inside a container to capture the sync token automatically cli/src/init.ts64-74 cli/src/docker.ts41

3. Scaffolding

The CLI generates core files in the target directory (default ./vault-cortex):

• .env: Composed using buildLocalEnv cli/src/env.ts28-110 or buildRemoteEnv cli/src/env.ts120-170 This includes a 64-character hex MCP_AUTH_TOKEN cli/src/env.ts2-3
• Optional Blocks: The CLI maintains synced copies of deploy/ env examples to provide users with commented-out optional settings like TZ, EMBEDDING_ENABLED, and MEMORY_DIR cli/src/env.ts16-26 These blocks are updated via scripts/sync-cli-env-blocks.ts cli/src/env.ts17-20

4. Deployment Execution

If Docker is available, the CLI runs dockerRun() cli/src/docker.ts182-185 It then uses pollHealth to monitor the /healthz endpoint (polling every 2s for up to 120s) to confirm the server is ready cli/src/lifecycle.ts23-45

---

Container Management

The CLI uses docker run directly rather than docker-compose for its managed flows to reduce external dependencies cli/README.md112-116

Image and Volume Strategy

• Images: Uses ghcr.io/aliasunder/vault-cortex:latest for local and ghcr.io/aliasunder/vault-cortex:remote for sync-enabled setups cli/src/docker.ts5-6
• Persistence: Injects specific volume mounts for persistence:
  • vault-cortex_mcp_data: Persistent SQLite search index and logs cli/src/docker.ts133-142
  • vault-cortex_vault_data: Remote vault storage (Remote mode only) cli/src/docker.ts141
  • vault-cortex_obsidian_config: Obsidian Sync credentials cli/src/docker.ts143

Health Checks

The CLI injects a HEALTH_CMD into the container that uses a Node.js one-liner to fetch the internal http://127.0.0.1:8000/healthz endpoint cli/src/docker.ts103-104

Diagram: Data Flow from Prompts to Files

Sources: cli/src/init.ts237-330 cli/src/scaffold.ts13-19 cli/src/messages.ts119-127 cli/src/env.ts28-111

---

Connection Messaging

Post-initialization, messages.ts generates tailored instructions using ANSI styling that is automatically stripped when output is not a TTY or NO_COLOR is set cli/src/messages.ts15-18

• Local Mode: buildLocalConnectMessage provides the localhost URL and instructions for bridging to Claude Desktop using mcp-remote cli/src/messages.ts119-181
• Remote Mode: buildRemoteConnectMessage focuses on the PUBLIC_URL and OAuth 2.1 flow, providing example commands for Claude Code cli/src/messages.ts183-200
• Auth Token Display: If a token was newly written, it is displayed prominently; if an existing .env was kept, the user is directed to check the file cli/src/messages.ts66-75

Sources: cli/src/messages.ts1-200 cli/src/__tests__/messages.test.ts1-50