Pinkmess 🌸

Pinkmess is a note-taking CLI tool that allows you to manage collections of markdown notes with AI-powered metadata generation capabilities.

It is a completely opinionated PKMS terminal manager for lazy people just like me.

Warning

This is a personal tool that I built for my own note-taking workflow and experimentation with AI-powered note organization. It is NOT intended for production use and comes with several important caveats:

• No Stability Guarantees: The API and CLI interface may change at any time without warning
• Limited Testing: The code has not been extensively tested beyond my personal use cases
• Security Considerations: The tool hasn't undergone security auditing
• Dependencies: Relies on specific versions of external libraries that may become outdated
• Performance: Not optimized for large-scale note collections
• Documentation: May be incomplete or outdated

📥 Installation

pip install pinkmess

Or install the latest version from the repository:

$ pip install git+https://github.com/leodiegues/pinkmess.git

🚀 Quick Start

Requirements:

• Python 3.10+
• OpenAI API key
• Text editor (defaults to nvim)

1. Set your OpenAI API key:

2. Create and set a collection:

3. Create and edit a note:

4. Generate metadata:

🏗️ Basic Structure

The CLI is organized into three main command groups:

• collection: Manages note collections
• note: Handles individual notes
• config: Manages application configuration

📁 Collection Commands

Create a Collection

pinkmess collection create PATH [--name NAME] [--llm-model MODEL] [--llm-settings SETTINGS]

Creates a new collection at the specified path.

Example:

pinkmess collection create ~/notes --name personal

Set Current Collection

pinkmess collection set NAME

Sets the active collection by its name.

Example:

pinkmess collection set personal

List Collections

pinkmess collection list
# or
pinkmess collection ls

Shows all registered collections.

Show Current Collection

pinkmess collection current

Displays the currently active collection.

Remove Collection

pinkmess collection remove NAME
# or
pinkmess collection rm NAME

Removes a collection from the registry.

Example:

pinkmess collection remove personal

Open Collection

pinkmess collection open [--name NAME]

Opens the specified collection (or current collection if no name provided) in your configured editor.

Example:

# Open current collection
pinkmess collection open

# Open a specific collection
pinkmess collection open --name personal

Show Collection Stats

pinkmess collection stats

Displays statistics about the current collection (number of notes, creation date, last modification).

📝 Note Commands

Create Note

pinkmess note create

Creates a new empty note in the current collection with a timestamp-based filename.

Edit Note

pinkmess note edit [--path PATH]

Opens the specified note (or last created note) in your configured editor.

Generate Metadata

pinkmess note generate-metadata [--path PATH] [--key {summary|tags}]

Generates AI-powered metadata for a note.

Examples:

# Generate summary for the last created note
pinkmess note generate-metadata --key summary

# Generate tags for a specific note
pinkmess note generate-metadata --path ~/notes/20230815123456.md --key tags

Duplicate Note

pinkmess note duplicate [--path PATH]

Creates a copy of the specified note (or last created note) with a new timestamp-based filename in the current collection.

Example:

# Duplicate the last created note
pinkmess note duplicate

# Duplicate a specific note
pinkmess note duplicate --path ~/notes/20230815123456.md

Show Last Created Note

pinkmess note last

Shows the path of the most recently created note.

⚙️ Config Commands

Edit Configuration

pinkmess config edit

Opens the configuration file in your default editor.

Show Configuration

pinkmess config show

Displays the current configuration in JSON format.

Set Environment Variable

pinkmess config set-env KEY VALUE

Sets an environment variable in the .env file.

Example:

pinkmess config set-env OPENAI_API_KEY your_api_key_here

🛠️ Configuration Details

The configuration is stored in TOML format at the user config directory:

• Linux: ~/.config/pinkmess/config.toml
• macOS: ~/Library/Application Support/pinkmess/config.toml
• Windows: %LOCALAPPDATA%\pinkmess\config.toml

Key configuration options include:

• Collections list
• Current collection index
• Default LLM model
• LLM settings
• Editor preference

Environment variables are stored in a .env file in the same directory.

🔄 Typical Workflow

1. Create a new collection:

pinkmess collection create ~/notes/work --name work

2. Set it as current:

pinkmess collection set work

3. Create a new note:

pinkmess note create

4. Edit the note:

pinkmess note edit

5. Generate metadata:

pinkmess note generate-metadata --key summary
pinkmess note generate-metadata --key tags

📜 License

The project is licensed under the GPLv3 license.

---

Happy note-taking! 🌸