Documentation

Docker (Server)

Run the REST API server in Docker:

# Build the image from source
docker build -f packages/server/Dockerfile -t vaultctl .

# Run
docker run -d \
  --name vaultctl \
  -p 3000:3000 \
  -v /path/to/your/vault:/vault \
  -e VAULT_PATH=/vault \
  -e AUTH_USER=admin \
  -e AUTH_PASSWORD=<your-secure-password> \
  vaultctl

Native macOS App

Download Vaultctl.app from the releases page. Code-signed with Developer ID and notarized by Apple.

From Source

Clone the repository from GitHub and build:

git clone <repo-url>
cd vaultctl
npm install && npm run build
alias vaultctl="node $(pwd)/packages/cli/dist/index.js"

Verify

vaultctl --version
vaultctl info
npm run test  # 466 tests across 33 files

Set the vault path via CLI (recommended):

vaultctl config set vault /path/to/your/vault

This writes the absolute path to ~/.vaultctlrc. You can also use an environment variable:

VAULT_PATH=/path/to/vault vaultctl health

Expected folder structure (PARA method):

00_Inbox/        # Uncategorized notes
01_Projects/     # Active projects
02_Areas/        # Ongoing responsibilities
03_Resources/    # Reference material
04_Archive/      # Completed/inactive

All commands accept --json for machine-readable output.

Core

Intelligence

Temporal

Schema

Management

Base URL: http://localhost:3333/api/v1/

SSE stream at /api/v1/events emits vault:activity on mutations.

MCP server for Claude Code, Claude Desktop, or any MCP-compatible client.

Configuration

// ~/.claude.json
{
  "mcpServers": {
    "vaultctl": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/vaultctl/packages/mcp/dist/index.js"],
      "env": { "VAULTCTL_PATH": "/path/to/your/vault" }
    }
  }
}

Tools (25)

knowledge_query, knowledge_read, knowledge_write, knowledge_timeline, health_check, health_fix, enrich, find_similar, suggest_links, intelligence_patterns, note_create, review_queue, daily_summary, weekly_summary, project_brief, session_start, session_end, session_decision, tags_list, stats, schema, schema_diff, schema_impact, index_rebuild, config_get

9 schema-driven validators. Type-specific rules declared in _meta/schema.yaml.

Declare schema in _meta/schema.yaml, validate with schema diff, simulate changes with schema impact.

Declaration

noteTypes:
  project:
    requiredFields: [status, tags, created]
    folder: 01_Projects
    statuses: [active, paused, completed]
  concept:
    requiredFields: [tags, created]
    folder: 03_Resources
    statuses: [active, paused, completed, archived, someday, draft]

globalRules:
  maxOrphans: 5
  maxStaleDays: 90
  requiredTags: [type]

Diff

$ vaultctl schema diff

  Type 'project':
    ✗ 2 notes missing 'status' field
    ✗ 1 note in wrong folder

  Type 'concept':
    ✓ All notes compliant

  Global:
    ✗ 3 orphans (max: 5) ✓
    ✗ 12 stale notes (max: 90 days)

Impact simulation

$ vaultctl schema impact --add-field priority --type project --required

  Impact: 15 of 23 project notes would fail
  Missing 'priority': 15 notes
  Already compliant: 8 notes

SwiftUI app using JavaScriptCore to run @vaultctl/core natively.

Features

• Dashboard with vault stats and recent activity
• Note browser with full-text search
• Inline markdown editor with wikilink autocomplete
• Force-directed knowledge graph with clustering
• Calendar with year heatmap and streaks
• Health dashboard with fix actions
• AI enrichment panel
• Inbox triage and batch categorization

Build from source

cd packages/native
swift build -c release
bash scripts/build-app.sh  # signs + notarizes
cp -R build/Vaultctl.app /Applications/

Markdown files with optional YAML frontmatter. Core parses frontmatter for metadata and body for wikilinks.

Frontmatter fields

Uses the Anthropic API (Claude). Set ANTHROPIC_API_KEY as an environment variable. All AI features are opt-in.

• Summary generation: Concise summary from note body
• Link suggestions: Notes that should be wikilinked
• Pattern detection: Hub notes, clusters, knowledge gaps
• Similar notes: Related notes by content similarity

No data sent to any API unless you explicitly run an enrichment command or use the MCP server with an AI assistant.

vaultctl is designed to work as the knowledge backbone for Claude Code sessions. A full integration guide covers MCP setup, CLAUDE.md patterns, skills, memory tiers, and session workflows.