Braindump

A CLI tool for managing markdown journal entries with a terminal-based bullet point editor.

Installation

From source

git clone https://github.com/MatejGroombridge/braindump.git
cd braindump
pip install -e .

Direct from GitHub

pip install git+https://github.com/MatejGroombridge/braindump.git

Update

pip install --force-reinstall git+https://github.com/MatejGroombridge/braindump.git   

After installation, ensure the Python Scripts folder is on your PATH:

OS	Typical location
Windows	%APPDATA%\Python\Python3XX\Scripts
macOS/Linux	~/.local/bin

Usage

The tool is invoked using the dump command. Run dump help for full command list and editor controls.

Commands

Command	Description
new	Create a new journal entry
list	View recent entries
open	Open entry in terminal editor (with note cycling)
edit	Open entry in external editor
copy	Copy specific entries by ID to clipboard
tag	Add or remove tags
synth	Toggle synthesised status
delete	Delete an entry
sync	Pull, commit and push with git
pull	Pull remote changes only
help	Show all commands and controls

Create a new entry

dump new                        # Create entry with no tags
dump new health career          # Create entry with tags

Creates a file like 2026012201.md with YAML frontmatter. Files are named YYYYMMDDXX.md where XX auto-increments for multiple entries on the same day.

Editor Controls

Key	Action
Arrow Keys	Navigate (accounts for text wrapping)
↓ at end	Create new bullet point
Enter	New bullet at same indentation level
Tab	Increase indentation
Shift+Tab	Decrease indentation
Enter	(on empty bullet) Decrease indentation
Enter ×2	(on empty L1 bullet) Save and exit
Backspace	Delete char, or merge line at bullet start
⌘S / Ctrl+S	Save and exit
⌘X / Ctrl+X	Cancel without saving
Ctrl+N	Cycle to next note
Ctrl+P	Cycle to previous note
Escape	Cancel without saving

Note: On macOS, use ⌘ (Command) for save/cancel. Ctrl+N/P works on all platforms.

Stylized Bullets

Different bullet characters are used for each indentation level:

• Level 1
  ◦ Level 2
    ‣ Level 3
      ⁃ Level 4
        ▪ Level 5

List entries

dump list                       # Show last 10 entries
dump list 5                     # Show last 5 entries

Open/Edit entries

dump open                       # Open latest in terminal editor
dump open 3                     # Open entry #3 in terminal editor
dump edit                       # Open latest in external editor
dump edit 3                     # Open entry #3 in external editor

Manage tags

dump tag 1 add health exercise
dump tag 1 remove fitness
dump tag 1 add health remove old

Copy entries to clipboard

dump copy                       # Copy latest entry to clipboard
dump copy 1 3 6                 # Copy specific entries by ID

Copied entries include an intro line and are separated by horizontal rules.

Toggle synthesised status

dump synth 1                    # Toggle synthesised status of entry #1

Delete an entry

dump delete 1                   # Delete entry #1

Sync with git

dump sync                       # Pull remote, commit local changes, push
dump pull                       # Pull remote changes only

The sync command performs a full bidirectional sync:

1. Fetches and pulls remote changes (stashing local changes if needed)
2. Commits all local changes with message format: Log: YYYY-MM-DD
3. Pushes to remote

Show help

dump help                       # Show all commands and editor controls

Configuration

• Journal entries stored in ~/dumps/
• Date format: Jan 22, 2026
• Monokai Pro colour scheme

Requirements

• Python 3.9+
• typer, rich, pyperclip, pyyaml, prompt_toolkit