kb-cli

A lightweight CLI tool for managing Markdown-based personal knowledge base.

Features

• 📝 Markdown-based note management with YAML frontmatter
• 🗂️ Flat file structure (no directory classification)
• 🔍 Simple indexing and querying
• 🔄 Git integration for version control
• 🌍 Cross-platform support (macOS, Linux, Windows)

Installation

From npm

npm install -g @kbkit/cli

From source

git clone <repository-url>
cd kb-cli
pnpm install
pnpm build
npm link

Usage

Interactive Mode (Default)

Simply run kb without any arguments to enter interactive mode:

kb

If no configuration file exists, you'll be prompted to:

1. Initialize a new knowledge base - Create a new local knowledge base
2. Clone a remote knowledge base - Clone an existing knowledge base from a Git repository
3. Exit

If a configuration file exists, you'll be presented with options:

1. 📝 新建笔记 - Create a new note
2. 🔄 重建索引 - Rebuild the index file (README.md)
3. 🚪 退出 - Exit the program

Command Line Mode

You can also use specific commands directly:

Initialize Knowledge Base

Initialize a new knowledge base:

kb init [path] [--clone <url>]

This will:

• Create a configuration directory at a platform-specific location:
  • macOS/Linux: ~/.kb
  • Windows: %USERPROFILE%\.kb
• Use default repository path:
  • macOS/Linux: ~/.kb/repo
  • Windows: %USERPROFILE%\.kb\repo
• Save configuration to the config file in the configuration directory

Examples

# Use default path
kb init

# Specify custom local path
kb init /path/to/your/knowledge-base      # macOS/Linux
kb init C:\Users\YourName\knowledge-base   # Windows

# Clone from remote repository
kb init --clone https://github.com/username/knowledge-base.git

# Clone to custom path
kb init /custom/path --clone https://github.com/username/repo.git      # macOS/Linux
kb init C:\custom\path --clone https://github.com/username/repo.git    # Windows

Configuration

Configuration is stored at:

• macOS/Linux: ~/.kb/config.json
• Windows: %USERPROFILE%\.kb\config.json

Example configuration:

{
  "repoPath": "/Users/username/.kb/repo"
}

Note:

• The configuration directory is platform-specific and cannot be changed
• The repository path defaults to the platform-specific location but can be customized
• The notes directory is fixed as notes and cannot be changed

Create a New Note

Create a new markdown note:

kb new "My Note Title"

This will:

• Generate a unique ID (format: YYYYMMDD-HHMMSS)
• Create a markdown file with frontmatter
• Open in your default editor (if EDITOR env var is set)

The created file will have this structure:

---
id: 20260416-143052
title: My Note Title
tags: []
created: 2026-04-16
updated: 2026-04-16
---

# My Note Title

Generate Index

Generate an index file (README.md) of all notes:

kb index

This will:

• Parse frontmatter
• Generate a sorted index by creation date
• Create/update README.md in the repository root

Example output:

# Knowledge Base

## 最近更新

- [My Note Title](notes/20260416-143052.md) - 2026-04-16
- [Another Note](notes/20260415-091234.md) - 2026-04-15

Development

Prerequisites

• Node.js >= 18
• pnpm

Setup

pnpm install
pnpm build

Development Mode

pnpm dev

Architecture

The CLI is built with a modular architecture:

/src
  /commands           # Command implementations
    init.ts           # Initialize knowledge base
    clone.ts          # Clone repository
    new.ts            # Create new note
    index.ts          # Generate index
  /utils              # Utility functions
    config.ts         # Configuration management
    fs.ts             # File system operations
    id.ts             # ID generation
    frontmatter.ts    # Frontmatter parsing
  cli.ts              # Main CLI entry point

Extending

The architecture supports easy extension for future commands:

• kb tag - Tag management
• kb list - List notes
• kb edit - Edit existing notes
• kb link - Link management

License

MIT