gems/jade-depo/README.md

Jade CLI

A simple CLI tool for managing markdown notes in a depository (vault). Inspired by Obsidian but focused on simplicity and command-line usage.

Features

• Multi-Depository Support: Manage multiple note repositories with short names
• Note Management: Create, edit, list, and delete markdown notes
• Tag Support: Extract and search notes by tags (+tag syntax)
• Full-Text Search: Search note content using ripgrep
• Link Support: Parse both [[wiki-style]] and [markdown](links)
• Trash System: Deleted notes moved to .jade/trash/ instead of permanent deletion
• Context-Aware: Automatically detects which depository you're in

Installation

go build -o jade

Usage

Managing Depositories

Before you can use jade, you need to add at least one depository:

# Add a depository with a short name
jade depo add personal ~/my-notes

# Add depository using current directory
cd ~/work/meeting-notes
jade depo add work

# List all depositories
jade depo list

# Set default depository
jade depo set-default personal

# Remove a depository (doesn't delete files)
jade depo remove work

Open Depository

# Open the default depository in your $EDITOR
jade

# Open a specific depository
jade --depo work

List Notes

# List all notes in the default depository
jade list

# Use a specific depository by name
jade --depo work list

# Or by path
jade --depo /path/to/notes list

# Context-aware: if you're inside a registered depository, jade uses it automatically
cd ~/my-notes
jade list  # Uses the depository that contains current directory

Create a Note

# Create a new note with a title
jade add "My New Note"

# This creates 'my-new-note.md' and opens it in $EDITOR

Search Notes

# Search by content
jade search "kubernetes"

# Search by tag
jade search --tag docker
jade search --tag +work  # prefix is optional

Edit a Note

# Find and edit a note by title (fuzzy search)
jade edit "My Note"

# If multiple matches, you'll be prompted to select

Delete a Note

# Delete a note (moves to trash with confirmation)
jade rm "My Note"

# Skip confirmation
jade rm --force "My Note"

List All Tags

# Show all tags with their occurrence counts
jade tags

Configuration

Jade uses a two-level configuration system:

Global CLI Config (~/.config/jade/config.yml)

Manages your depositories and default settings:

depositories:
  personal: /home/user/my-notes
  work: /home/user/work/notes
default_depository: personal

This file is automatically created and managed by jade depo commands.

Per-Depository Structure

Each depository contains a .jade/ directory for metadata:

• .jade/trash/ - Deleted notes
• Future: .jade/index.db - SQLite index for fast search

Depository Structure

my-notes/
├── .jade/
│   └── trash/          # Deleted notes go here
├── note-1.md
├── note-2.md
└── subfolder/
    └── note-3.md

The .jade/ directory is automatically created and contains metadata. You can optionally add it to .gitignore if you don't want to track it in version control, or commit it to sync trash/metadata across devices.

Note Format

Notes are standard markdown files. The first # heading is used as the title (filename is fallback).

Example note:

# My Note Title

This is a note about +kubernetes and +docker.

I can reference [[another-note.md]] or use [regular links](other-note.md).

Tags can appear anywhere in +content.

Requirements

• Go 1.25+ (for building)
• ripgrep (rg) for search functionality
• $EDITOR environment variable set (falls back to vi)

Roadmap

v1.0 (Current)

• Basic note operations (add, edit, delete, list)
• Tag extraction and listing (+tag syntax)
• Content and tag search
• Trash system
• Multi-depository support with short names
• Context-aware depository detection

v1.1 (Future)

• SQLite indexing for faster search
• Graph visualization
• Backlinks
• Watch mode (auto-index on changes)

v2.0 (Future)

• Mobile access (native app or PWA)
• Web interface with authentication
• OCR support

License

MIT