KBIntake
KBIntake is a Windows-first local vault importer. It lets you send files and folders into a knowledge-base vault from PowerShell or from the Windows Explorer right-click menu, while keeping an auditable SQLite job history.
Current release: v2.1.1
What It Is For
KBIntake is built for people who collect notes, PDFs, screenshots, exports, and reference files throughout the day and want a repeatable way to move them into a local vault. Instead of manually copying files, checking for duplicates, renaming conflicts, and remembering where each file went, KBIntake records every import as a job and stores the resulting file manifest.
The default target is a local folder vault, such as:
C:\Users\\Documents\KBIntakeVault
KBIntake does not require a cloud service. Configuration, queue state, manifests, logs, and the default vault are local to your Windows profile.
Install
Recommended
- Open the v2.1.1 release page.
- Download
KBIntake-Setup.exe.
- Run the installer.
- Open a new PowerShell window and run:
kbintake doctor
The installer:
- installs
kbintake.exe, kbintakew.exe, kbintake_com.dll, kbintake-com-reg.exe, and kbintake.ico under %LOCALAPPDATA%\Programs\kbintake
- adds that directory to your user
PATH
- registers Explorer right-click entries for files and folders (cascading submenu + Win11 native COM menu)
- creates a Windows Settings uninstall entry
Winget
The winget manifest for v2.1.1 is in installer/winget/2.1.1/. The community package PR: .
Until the PR is merged, use the GitHub Release installer.
After publication:
winget install GeziP.KBIntake
Quick Start
Explorer flow:
- Right-click a file or folder.
- Choose the KBIntake action to expand the submenu.
- Select Import (process immediately), Queue (queue for later), or Settings (open TUI).
- KBIntake imports it silently and shows a Windows toast notification.
- Inspect the result:
kbintake jobs list
Terminal flow:
kbintake doctor --fix
kbintake import --process C:\path\to\note.md
kbintake jobs list
Obsidian Integration
KBIntake can import files directly into your Obsidian vault and auto-open notes after import.
Setup
- Add your Obsidian vault as a KBIntake target:
kbintake targets add obsidian "C:\Users\\Documents\YourVaultName"
kbintake targets set-default obsidian
- Edit
%LOCALAPPDATA%\kbintake\config.toml — add obsidian_vault to the target and enable auto-open:
[[targets]]
target_id = "obsidian"
name = "obsidian"
root_path = 'C:\Users\\Documents\YourVaultName'
status = "active"
obsidian_vault = "YourVaultName"
[import]
auto_open_obsidian = true
obsidian_vault must match the vault name shown in Obsidian's sidebar.
Usage
# Import and open in Obsidian
kbintake import note.md --process --open
# Import without opening
kbintake import note.md --process
# Import from clipboard
kbintake import --clipboard --process
On first run, KBIntake generates default templates. Imported .md files go to vault/notes/, PDFs to vault/documents/, code files to vault/snippets/, etc. See docs/CONFIGURATION.md for the full template list.
Features
- Explorer cascading right-click menu with Import / Queue / Settings sub-items
- Windows 11 native top-level context menu via COM DLL
- no-console Explorer flow through
kbintakew.exe
- Windows toast notifications for success, duplicate, and failure cases
- terminal import flow with optional immediate processing
- SQLite-backed batches, items, manifests, and audit events
- SHA-256 hashing and per-target duplicate detection
- deterministic filename conflict handling without overwriting existing files
- multiple vault targets with add/list/show/rename/remove/set-default commands
- import template system with variable interpolation and conditional rendering
- v2 multi-condition routing rules with template binding
- per-target default subfolder configuration
- Markdown frontmatter injection with template-defined fields
--tags quick tag injection merged with template tags
--clipboard import file paths from Windows clipboard
- dry-run preview with table or JSON output
- job list/show with table or JSON output
- retry failed jobs
- hash-safe undo for imported batches
- per-target vault statistics
vault audit command for orphan, missing, duplicate, and malformed frontmatter detection
- Watch Mode: monitor directories for new files with debounce and extension filters
- TUI interactive settings (
kbintake tui)
- Obsidian URI integration with auto-open after import
- zh-CN (Chinese) localization (CLI, toast, TUI, Explorer context menu)
- Windows Service mode for background queue processing
- release workflow that publishes installer and binary assets
- winget manifest copy stored under
installer/winget/
Common Commands
kbintake --version
kbintake version
kbintake doctor [--fix] [--migrate]
kbintake config show
kbintake config validate
kbintake config set-target [--name ]
kbintake config-show
kbintake targets list [--include-archived]
kbintake targets show
kbintake targets add
kbintake targets rename
kbintake targets remove [--force]
kbintake targets set-default
kbintake import [--target ] [--template ] [--tags "a,b"] [--clipboard] [--process] [--dry-run] [--json] [--open]
kbintake jobs list [--status ] [--limit ] [--json] [--table]
kbintake jobs show [--json] [--table]
kbintake jobs retry
kbintake jobs undo [--force]
kbintake vault stats [--target ] [--json]
kbintake vault audit [--target ] [--fix] [--json]
kbintake watch [--path ]
kbintake tui
kbintake obsidian open --vault
kbintake explorer install [--exe-path ] [--icon-path ] [--queue-only]
kbintake explorer uninstall
kbintake agent
kbintake service install
kbintake service start
kbintake service stop
kbintake service uninstall
kbintake service status
Configuration
Runtime state lives in %LOCALAPPDATA%\kbintake by default:
config.toml
data\kbintake.db
logs\
vault\
Important config sections:
[[targets]]: vault destinations (with optional default_subfolder, obsidian_vault)
[[templates]]: import templates with subfolder, tags, and frontmatter
[[routing_rules]]: v2 multi-condition routing with template binding
[[routing]]: v1 extension-based routing (still supported)
[[watch]]: directories to monitor for automatic import
[import].max_file_size_mb: file size guardrail
[import].inject_frontmatter: Markdown metadata injection
[import].language: output language ("en" or "zh-CN"), also controls Explorer context menu text
[import].auto_open_obsidian: auto-open imported notes in Obsidian
[agent].poll_interval_secs: background worker polling interval
Full reference: docs/CONFIGURATION.md
Background Processing
For terminal use, kbintake import --process queues and processes immediately.
For passive background processing, install the Windows Service from an elevated Administrator PowerShell:
kbintake service install
kbintake service start
kbintake service status
To remove it:
kbintake service stop
kbintake service uninstall
Service mode is implemented and validated for install/start/queue processing/logging/stop/uninstall. Reboot-resume validation remains a release-checklist manual item.
Troubleshooting
Start with:
kbintake doctor
Common fixes:
- Missing target directory:
kbintake doctor --fix
- Wrong vault target:
kbintake config set-target
- Explorer menu missing:
kbintake explorer install
- Schema needs migration:
kbintake doctor --migrate
kbintake not found after install: open a new PowerShell window
- Service install/start access denied: use Administrator PowerShell
Build From Source
Install Rust from , then from the repository root:
cargo build --release --locked --bins
To build the installer locally, install NSIS and run from the repository root:
New-Item -ItemType Directory -Force .\dist | Out-Null
Copy-Item .\target\release\kbintake.exe .\dist\kbintake.exe -Force
Copy-Item .\target\release\kbintakew.exe .\dist\kbintakew.exe -Force
Copy-Item .\kbintake\assets\kbintake.ico .\dist\kbintake.ico -Force
& "C:\Program Files (x86)\NSIS\makensis.exe" .\installer\kbintake.nsi
Validation
Automated checks:
cargo fmt --all -- --check
cargo test --locked
cargo clippy --all-targets --all-features --locked -- -D warnings
cargo build --locked
cargo build --release --locked --bins
Manual Windows smoke checks:
.\scripts\validate-explorer-toast.ps1
.\scripts\validate-service-mode.ps1
validate-service-mode.ps1 requires an elevated Administrator PowerShell session.
Planned Work
- Windows 11 COM DLL physical machine validation
- monitor the
microsoft/winget-pkgs PR for winget publication
- code-sign release binaries to reduce SmartScreen friction
- perform reboot-resume validation for service mode
See docs/PROJECT_STATUS.md and docs/ROADMAP.md.
Project Documents