GPGNotes

A CLI note-taking tool with GPG encryption, automatic tagging, full-text search, and Git synchronization.

Features

Markdown Notes - Write notes in plain markdown with YAML frontmatter
GPG Encryption - Every note is encrypted individually with GPG
Full-Text Search - Fast SQLite FTS5-powered search across all notes
Auto-Tagging - Intelligent tag generation using TF-IDF
Folders - Tag-based virtual folders for organizing notes
Todo Tracking - Aggregate tasks from markdown checkboxes across all notes
Git Sync - Automatic synchronization with private GitHub repositories
Daily Notes - Captain's Log style quick entries with summaries (docs)
Note Templates - Built-in templates (meeting, project, bug, journal, research) with custom template support
Version History - Git-based version tracking with history, diff, and restore commands
Markdown Rendering - Rich terminal preview with formatted display
URL Import - Web clipper to import content from URLs
Pagination - Interactive pagination for list and search results
AI Enhancement - Optional LLM-powered note refinement (docs)
Import/Export - Support for PDF, DOCX, RTF formats (docs)
TUI Mode - Full-screen text user interface for browsing and managing notes

Installation

Prerequisites

Python 3.11 or higher
GPG (GnuPG) installed on your system
- Linux: sudo apt install gnupg (Debian/Ubuntu)
- macOS: brew install gnupg

Install from PyPI

pip install gpgnotes

With optional dependencies:

pip install gpgnotes[llm]      # AI enhancement
pip install gpgnotes[import]   # PDF/DOCX import/export
pip install gpgnotes[tui]      # Full-screen TUI interface

Install with pipx

pipx install gpgnotes

# Add optional dependencies
pipx inject gpgnotes textual              # TUI interface
pipx inject gpgnotes openai anthropic     # AI enhancement
pipx inject gpgnotes python-docx pypdf    # PDF/DOCX import

Install from source

git clone https://github.com/oscarvalenzuelab/GPGNotes.git
cd GPGNotes
pip install -e .

Quick Start

1. Initialize

notes init

This guides you through:

Selecting a GPG key
Testing encryption
Configuring your editor
Setting up Git sync (optional)

Don't have a GPG key? Create one:

gpg --full-generate-key

2. Create a note

notes new "My First Note"

3. Search and manage

notes search "keyword"
notes list
notes open <note-id>
notes sync

Command Reference

Command	Description
`notes new "Title"`	Create a new note
`notes new --template meeting`	Create note from template
`notes new --folder work`	Create note in folder
`notes list`	List all notes
`notes list --preview`	List with content preview
`notes list --folder work`	List notes in folder
`notes list --page-size 10`	List with custom pagination
`notes recent`	Show 5 most recent notes
`notes search "query"`	Full-text search
`notes search --tag work`	Search by tag
`notes search --folder work`	Search within folder
`notes folders`	List all folders with counts
`notes move <id> --folder work`	Add note to folder
`notes move <id> --unfolder work`	Remove note from folder
`notes todos`	List incomplete tasks
`notes todos --all`	Include completed tasks
`notes todos --folder work`	Tasks from specific folder
`notes open <id>`	Open note by ID
`notes open "title"`	Open by title (fuzzy match)
`notes open --last`	Open most recent note
`notes show <id> --render`	Display note with formatting
`notes preview <id>`	Rich markdown preview
`notes history <id>`	Show version history
`notes diff <id> --from <commit>`	Compare versions
`notes restore <id> --version <commit>`	Restore previous version
`notes template list`	List all templates
`notes template show <name>`	Preview a template
`notes tags`	List all tags
`notes delete <id>`	Delete a note
`notes sync`	Sync with Git
`notes config --show`	Show configuration
`notes daily "entry"`	Quick daily log entry (docs)
`notes daily --time "entry"`	Entry with timestamp
`notes today`	Open today's daily note
`notes yesterday`	Open yesterday's note
`notes daily show`	View today's entries
`notes daily summary --month`	Generate monthly summary
`notes enhance <id>`	AI enhancement (docs)
`notes import file.pdf`	Import file (docs)
`notes import <url>`	Import from URL (web clipper)
`notes clip <url>`	Web clipper shortcut
`notes export <id>`	Export note (docs)
`notes tui`	Launch full-screen TUI interface

Interactive Mode

Run notes without arguments for interactive mode with:

Tab completion for note titles
Command history (Up/Down arrows)
Quick search by typing

TUI Mode

Run notes tui for a full-screen terminal interface with:

Split-pane view with folders, notes list, and preview
Keyboard navigation (n=new, e=edit, d=delete, s=search, y=sync, r=refresh, q=quit)
Auto-sync on launch to cache GPG passphrase
Decrypted note preview after authentication

Requires: pip install gpgnotes[tui] or pipx inject gpgnotes textual

Security

GPG Encryption: All notes encrypted with AES256
Local-first: Your data stays on your machine
Private repos: Git sync for private repositories only
Encrypted secrets: API keys stored with GPG encryption

Documentation

License

Apache License 2.0 - see LICENSE for details.

Note: This is an early release. Always backup your notes!

Release files for gpgnotes 0.4.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for gpgnotes 0.4.2
File	Size	Uploaded
gpgnotes-0.4.2.tar.gz	82.9 kB	Dec 19, 2025	Details

Built distribution (wheel)

Table of built distributions (wheels) for gpgnotes 0.4.2
File	Interpreter	ABI	Platform	Reset
gpgnotes-0.4.2-py3-none-any.whl 86.9 kB Dec 19, 2025	Python 3	none	any	Details

Total release size: 169.8 kB

Release files / gpgnotes-0.4.2.tar.gz

Download URL	gpgnotes-0.4.2.tar.gz
Size	82.9 kB
Tags	Source
SHA-256 checksum How to use checksums	`66378b12070b9b6dc4372786561014eaedb827f7bbff0687b8b5503e83c99c48`
BLAKE2b-256 checksum How to use checksums	`7b4aeff031c8dd596bc030b7a42be30fd7f904500332ad299378ad8106a209ed`
Upload date	Dec 19, 2025
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.13.7`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/oscarvalenzuelab/GPGNotes
Publishing commit: github.com/oscarvalenzuelab/GPGNotes/tree/24fa82d3c610589dfedbb4ac9316d5880da0ef5a

Workflow

Publishing configuration: github.com/oscarvalenzuelab/GPGNotes/blob/24fa82d3c610589dfedbb4ac9316d5880da0ef5a/.github/workflows/publish.yml
Publishing logs: github.com/oscarvalenzuelab/GPGNotes/actions/runs/20356798139/attempts/1

Artifact

Subject: gpgnotes-0.4.2.tar.gz
SHA-256 checksum: 66378b12070b9b6dc4372786561014eaedb827f7bbff0687b8b5503e83c99c48 Verifying attestations

Release files / gpgnotes-0.4.2-py3-none-any.whl

Download URL	gpgnotes-0.4.2-py3-none-any.whl
Size	86.9 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`f24e74b4ea92e61019898d2b5a006f003c34b24237e9e036793b700e04373df9`
BLAKE2b-256 checksum How to use checksums	`4768a22dfb0d774cd01fe1f9b184144847979981ac9c4bf5d5ba9d6b28dd6ebf`
Upload date	Dec 19, 2025
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.13.7`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/oscarvalenzuelab/GPGNotes
Publishing commit: github.com/oscarvalenzuelab/GPGNotes/tree/24fa82d3c610589dfedbb4ac9316d5880da0ef5a

Workflow

Publishing configuration: github.com/oscarvalenzuelab/GPGNotes/blob/24fa82d3c610589dfedbb4ac9316d5880da0ef5a/.github/workflows/publish.yml
Publishing logs: github.com/oscarvalenzuelab/GPGNotes/actions/runs/20356798139/attempts/1

Artifact

Subject: gpgnotes-0.4.2-py3-none-any.whl
SHA-256 checksum: f24e74b4ea92e61019898d2b5a006f003c34b24237e9e036793b700e04373df9 Verifying attestations