✜ Piki

A personal wiki system for your markdown files

Piki helps you manage a personal knowledge base using plain Markdown files stored on your filesystem. Take notes, create documentation, build your own wiki—all without cloud services, subscriptions, or lock-in.

Features

• Local-first: Your notes are plain Markdown files on your filesystem
• Git-friendly: Version control your wiki with Git (optional)
• Dual interface: Use the CLI for quick edits or the GUI for rich text editing
• Live sharing: Present the current note as a live-updating local web page — great for video calls
• Cross-platform: Works on Windows, macOS, Linux, and BSD
• Lightweight: GUI built with FLTK featuring a custom rich-text editor
• Fast: Written in Rust for performance and reliability
• Private: No cloud service, no telemetry, no tracking
• Open source: MIT licensed

Installation

Via Cargo

cargo install piki
cargo install piki-gui

System Requirements

• Rust 2024 edition (for building from source)
• For GUI: FLTK dependencies
  • macOS: No additional dependencies
  • Linux/BSD: Wayland/X11 development libraries
  • Windows: No additional dependencies

Quick Start

1. Initialize Your Wiki

Create a directory for your notes (or use an existing one):

mkdir ~/.piki
cd ~/.piki

# Create a frontpage
echo "# John Doe's Brain" > frontpage.md

2. Launch the GUI

piki-gui

The GUI will open with your frontpage. Start editing, create links, and navigate between notes.

3. Or Use the CLI

# Edit interactively (fuzzy picker)
piki

# Edit a specific note
piki edit frontpage

# List all notes
piki ls

# View a note
piki view frontpage

Configuration

Create a ~/.pikirc file to customize your workflow:

[aliases]
# Daily notes
today = "code . -g daily/$(date +'%Y-%m-%d').md"
standup = "vim work/standup-$(date +'%Y').md"

# Git shortcuts
status = "git status -u"
sync = "git ci -m 'Auto-sync' && git pull --rebase && git push"
push = "git commit -m 'Auto-sync' && git push"

# Open in your favorite editor/IDE
code = "code ."
cfg = "vim ~/.pikirc"

# Launch GUI from CLI
g = "piki-gui"

CLI Usage

Commands

piki [options] [command]

Options:
  -d, --directory DIRECTORY   Directory containing markdown files (default: ~/.piki)

Commands:
  edit [name]     Edit a note (opens in $EDITOR or $VISUAL, defaults to vim)
  view [name]     View a note
  ls              List all notes
  search [terms]  Full-text search notes (all terms must match)
  log [-n NUM]    Show git commit log (if using git)
  run [cmd]       Run a shell command inside the notes directory
  help            Show help information

Search prints one grep-style note:line: text per matching line and, on a terminal, highlights the matched terms:

piki search budget            # notes mentioning "budget"
piki search marathon training # notes mentioning BOTH terms

Interactive Mode

When no command is specified, Piki opens an interactive fuzzy picker:

piki -d ~/my-wiki
# Type to filter notes, arrow keys to navigate, Enter to edit

Example Workflows

# Daily note workflow
piki edit "daily/$(date +'%Y-%m-%d')"

# Quick capture
piki edit inbox

# Browse and edit
piki -d ~/my-wiki  # Interactive picker

# View without editing
piki view project-ideas

# Git integration
piki run git status
piki log -n 10

GUI Usage

Launching

# Open to frontpage
piki-gui

# Open with custom wiki path
piki-gui -d /path/to/wiki

Key Features

Rich-Text Editing

• Live Markdown rendering as you type
• Headers (H1, H2, H3) with visual hierarchy
• Bold, italic, code, strikethrough, underline, highlighting
• Code blocks and blockquotes
• Clickable links

Keyboard Shortcuts

Shortcut	Action
Navigation
Cmd+N	New note
Cmd+O	Open / search notes
Cmd+[	Back
Cmd+]	Forward
Cmd+Option+F	Jump to frontpage
Cmd+Option+I	Open note index
Editing
Cmd+Z	Undo
Cmd+Shift+Z	Redo
Inline Styling
Cmd+B	Bold
Cmd+I	Italic
Cmd+U	Underline
Cmd+Shift+C	Inline code
Cmd+Shift+H	Highlight text
Cmd+Shift+X	Strikethrough
Cmd+K	Insert/Edit link
Cmd+\	Clear formatting
Paragraph Styling
Cmd+Option+0	Text paragraph
Cmd+Option+1	Header 1
Cmd+Option+2	Header 2
Cmd+Option+3	Header 3
Cmd+Shift+5	Blockquote
Cmd+Shift+6	Code block
Cmd+Shift+7	Numbered list
Cmd+Shift+8	Bulleted list
Cmd+Shift+9	Checklist
Option+Up	Move paragraph up
Option+Down	Move paragraph down
View
Cmd+Shift+L	Live Note Sharing

Live Note Sharing

Turn the note you're viewing into a clean, self-updating web page — ideal for showing your notes while screen sharing in a video call.

• Start it from View → Live Note Sharing (Cmd+Shift+L). A red "ON AIR" bar appears with the shareable link and a Stop button, and the note opens in your browser.
• Edits show up in the browser within about a second (live reload).
• The web view stays on its own note and never follows your in-app navigation, so you can keep a "public" note on screen while taking notes in a private one. The link in the ON AIR bar always points at the note you're currently viewing.
• Links are followable in the browser, the page follows the viewer's light/dark system theme, and a footer toggle switches between one and two columns to make better use of a widescreen.
• The server binds 127.0.0.1 only, so it's reachable from your machine alone — remote participants just see your screen-shared tab, never the server.

Auto-Save

• Changes are saved automatically
• Status bar shows save status and last save time
• Creates parent directories as needed

Link Formats

• Standard Markdown: [text](note.md)
• Wiki-style: [[NoteName]]
• Nested paths: [[folder/note]]

Plugin System

• Dynamic notes with ! prefix
• Built-in !index plugin lists all notes
• Plugin notes are read-only
• Extensible for custom dynamic content

Git Integration

Piki works seamlessly with Git for version control:

cd ~/.piki
git init
git add .
git commit -m "Initial wiki"

# Use piki's git commands
piki log
piki run git status

# Or use aliases in .pikirc
piki sync    # Commit, pull, push
piki push    # Commit and push

Platform Support

Piki is fully cross-platform:

Platform	CLI	GUI	Notes
macOS	✅	✅	Native menu bar support
Linux	✅	✅	X11 or Wayland required for GUI
Windows	✅	✅	Fully supported
BSD	✅	✅	FreeBSD, OpenBSD, etc.

Architecture

Piki is organized as a Cargo workspace:

• core/ - Shared library (document store, plugins)
• cli/ - Command-line interface
• gui/ - FLTK-based graphical interface

Philosophy

Local-First Your notes are plain text files on your filesystem. No databases, no proprietary formats, no cloud services.

Privacy No telemetry, no tracking, no data leaving your machine. Your personal knowledge stays personal.

Interoperability Markdown files work with any editor or tool. Use Piki alongside VS Code, Obsidian, vim, or anything else.

Simplicity Fast startup, minimal dependencies, straightforward workflows. A tool that gets out of your way.

Contributing

Contributions are welcome! Some ideas:

• Package managers (Homebrew, apt, Chocolatey, AUR)
• Full-text search across all notes
• Backlinks and note graph
• Custom syntax highlighting themes
• Mobile companion app
• Web server mode (read-only)
• Additional plugins (calendar, task list, etc.)

See the issues page on GitHub.

License

MIT License