Mental Note CLI

A zero-dependency Python productivity tool for managing mental notes, tasks, and ideas via command line

Version 2.0.2 - Recurring Tasks & Automation

Getting Started

Installation

# Add the tap
brew tap julianpaez/mental-note

# Install mental-note
brew install mental-note

# Verify installation
mental-note --version
mn --version

Quick Start

# Add your first note
mn add do "Complete project proposal" --due tomorrow --tags work,urgent

# List all notes
mn list

# Mark as complete
mn done 1

# View your profile
mn profile

Action Types

Mental Note supports 6 action types for different purposes:

Action	Icon	Purpose	Example
`do`	✓	Tasks and action items	mn add do "Review PR #123"
`remember`	●	Information to recall	mn add remember "API key: abc123"
`contemplate`	?	Ideas to think about	mn add contemplate "New architecture"
`forget`	✗	Things to let go of	mn add forget "Old password"
`ignore`	○	Things to deliberately ignore	mn add ignore "Background noise"
`stick`	★	Important reminders	mn add stick "Daily standup 10am"

Short Flags (v1.9.0)

Short flag aliases reduce common commands from ~48 to ~25 keystrokes:

Short	Long Flag	Description
`-t`	`--tags`	Tags (comma-separated)
`-d`	`--due`	Due date (add command)
`-D`	`--due`	Filter by due date (list)
`-p`	`--project`	Project name
`-s`	`--section`	Section name
`-f`	`--format`	Display format
`-a`	`--archived`	Include archived
`-c`	`--completed`	Filter completed
`-P`	`--pending`	Filter pending
`-o`	`--overdue`	Filter overdue
`-r`	`--reverse`	Reverse sort
`-A`	`--action`	Action type
`-n`	`--parent`	Parent note ID
`-R`	`--recursive`	Recursive operation
`-q`	`--query`	Search query
`-F`	`--fuzzy`	Fuzzy matching
`-B`	`--boolean`	Boolean query
`-y`	`--confirm`	Skip confirmation
`-C`	`--content`	New content

# Before (48 chars)
mn list --project Work --tags urgent --pending

# After (25 chars)
mn list -p Work -t urgent -P

Core Commands

add - Add Notes

Create new notes with optional tags, due dates, projects, and more.

Basic Usage

mn add <action> "content" [options]

# Simple task
mn add do "Review quarterly report"

# With due date and tags
mn add do "Submit proposal" --due tomorrow --tags work,urgent

# Short flags
mn add do "Fix bug" -d 2d -t code,p1

# With project and section
mn add do "Design homepage" --project "Website" --section "Todo"

# Create subtask
mn add do "Write introduction" --parent 42

Natural Language Input

Create notes using natural language with automatic extraction of elements. The parser intelligently identifies dates, times, tags, projects, priorities, and more.

# Date & Time
mn add "Review PR tomorrow 2pm"
mn add "Meeting next Monday 10:30am"
mn add "Follow up in 3h"

# Tags (#) & Projects (@)
mn add "Update docs #urgent #docs @Work"
mn add "Plan vacation @Personal #travel"

# Priority (p1-p4)
mn add "Fix critical bug p1"
mn add "Refactor code p3"

# Action Types (prefix:)
mn add "remember: Buy milk"
mn add "contemplate: New architecture?"

# Subtasks (>)
mn add "Launch > Testing > Unit tests"
mn add "Write report > Introduction > Draft"

# Combined Power Usage
mn add "do: Review PR tomorrow 2pm #code @Work p1"

Due Date Formats

today, tomorrow, yesterday
3h (3 hours), 2d (2 days), 1w (1 week)
2025-12-25 (ISO format)
Monday, next Friday

list - List Notes

Display notes with powerful filtering and multiple formats.

Basic Usage

mn list [options]

# List all active notes
mn list

# Filter by status
mn list --pending
mn list --completed
mn list --overdue

# Filter by project/section
mn list --project "Work" --section "Todo"

# Filter by tags
mn list --tags urgent,code

# Filter by due date
mn list --due 7d     # Due within 7 days
mn list --due-on today  # Due exactly today
mn list --due-on tomorrow
mn list --due-on 2025-12-25


    Tip: Use --due to find tasks due within a timeframe (e.g., next 7 days). Use --due-on to find tasks due on a specific date.


# Different formats
mn list --format kanban
mn list --format tree
mn list --format cards
mn list --format compact
mn list --format json

Display Formats

Format	Description	Best For
`table`	Tabular view with columns	Overview
`kanban`	Board view by action/section	Project management
`tree`	Hierarchical tree view	Subtask hierarchies
`cards`	Detailed card format	Individual review
`compact`	Minimal one-line format	Quick scanning
`oneline`	Single line per note	Terminal integration
`json`	JSON output	Scripting

show - Show Details

Display detailed information about specific notes.

# Show single note
mn show 42

# Show multiple notes
mn show 1 2 3 4 5

# Show with filters
mn show --tags urgent --pending

edit - Edit Notes

Modify existing notes.

# Edit content
mn edit 42 --content "Updated task description"

# Edit tags
mn edit 42 --tags work,urgent,p1

# Edit action type
mn edit 42 --action remember

# Short flags
mn edit 42 -C "New content" -t newtags

delete - Delete Notes

Remove notes from your collection.

# Delete single note
mn delete 42

# Delete multiple notes
mn delete 1 2 3 4 5

# Delete with confirmation skip
mn delete 42 --confirm

# Delete recursively (with subtasks)
mn delete 42 --recursive

archive - Archive Notes

Move completed or old notes to archive.

# Archive single note
mn archive 42

# Archive all completed
mn archive --completed

# View archived notes
mn archived
mn list --archived

# Unarchive note
mn unarchive 42

Project Commands

Organize notes into projects with sections for better task management.

project create

# Create project with sections
mn project create "Work" --sections "Todo,In Progress,Done"

# Create with color
mn project create "Personal" --sections "Backlog,Active" --color blue

project list

# List all projects
mn project list

# Include archived projects
mn project list --archived

project show

# Show project details
mn project show "Work"

project update

# Rename project
mn project update "Work" --name "Work 2025"

# Update sections
mn project update "Work" --sections "Backlog,Todo,In Progress,Review,Done"

project delete

# Delete project
mn project delete "Old Project"

# Delete and reassign notes
mn project delete "Old Project" --reassign "New Project"

project stats

# View project statistics
mn project stats "Work"

# Output includes:
# - Total notes, completed, pending
# - Completion rate
# - Notes by section
# - Notes by action type

Using Projects with Notes

# Add note to project
mn add do "Review PR" --project "Work" --section "Todo"

# Filter by project
mn list --project "Work"
mn list --project "Work" --section "In Progress"

# Kanban view (auto-groups by section)
mn list --project "Work" --format kanban

Hierarchy Commands

Create subtask hierarchies with up to 4 levels of nesting.

Creating Subtasks

# Create parent task
mn add do "Write quarterly report"  # ID: 1

# Add subtasks
mn add do "Write introduction" --parent 1
mn add do "Gather data" --parent 1
mn add do "Create charts" --parent 1

# View hierarchy
mn list --format tree

# Output:
# ├─ ✓ #1 Write quarterly report [░░░░░░░░░░ 0/3]
# │  ├─ ✓ #2 Write introduction
# │  ├─ ✓ #3 Gather data
# │  └─ ✓ #4 Create charts

indent

Make a note a subtask of its previous sibling.

mn indent 42

outdent

Promote a note to its parent's level.

mn outdent 42

move

Move notes within the hierarchy.

# Move under new parent
mn move 42 --parent 10

# Move after specific sibling
mn move 42 --after 15

Recursive Operations

# Complete task and all subtasks
mn done 42 --recursive

# Delete task and all subtasks
mn delete 42 --recursive

Completion Commands

done - Mark Tasks Complete

# Mark single task complete
mn done 42

# Mark multiple tasks
mn done 1 2 3 4 5

# Complete with all subtasks
mn done 42 --recursive

Tip: Completing tasks earns XP and contributes to your daily goals!

undone - Mark Tasks Incomplete

# Reopen completed task
mn undone 42

# Reopen multiple tasks
mn undone 1 2 3

Completion Indicators

Symbol	Meaning
✓	Pending task
☑	Completed task
[█████░░░░░ 3/6]	Parent task progress

Search Commands

Basic Search

# Simple text search
mn search "quarterly report"

# Search with filters
mn search "bug" --project "Engineering" --pending

Fuzzy Search

Find notes even with typos or spelling variations.

# Fuzzy matching
mn search "quaterly" --fuzzy

# Adjust threshold (0.0-1.0)
mn search "performence" --fuzzy --threshold 0.8

Boolean Search

Create complex queries with AND, OR, NOT operators.

# AND - both terms required
mn search "quarterly AND report" --boolean

# OR - either term
mn search "bug OR issue" --boolean

# NOT - exclude term
mn search "report NOT quarterly" --boolean

# Complex query
mn search "API AND (bug OR issue) NOT resolved" --boolean

Field-Specific Search

# Search by field
mn search "tags:urgent" --boolean
mn search "action:do AND completed:false" --boolean
mn search "project:Work AND section:Todo" --boolean

# Available fields:
# content:, tags:, action:, completed:, archived:,
# id:, date:, due:, project:, section:

Saved Searches

# Save a search
mn search save "urgent-tasks" "tags:urgent AND completed:false" --boolean

# List saved searches
mn search list

# Run saved search
mn search run urgent-tasks

# Delete saved search
mn search delete old-search

Timeline & Metrics

timeline - Chronological View

# View all notes timeline
mn timeline

# Filter timeline
mn timeline --after 7d
mn timeline --project "Work" --completed

metrics - Analytics Dashboard

# View full metrics
mn metrics

# Output includes:
# - Overview (total notes, active/archived)
# - Completion stats
# - By action type
# - Top tags
# - Projects summary
# - Recent activity
# - Gamification stats
# - Goals progress
# - Health score

export/import - Backup & Restore

# Export to JSON (full preservation)
mn export backup.json

# Export formats
mn export backup.md --format markdown
mn export backup.csv --format csv
mn export backup.txt --format text

# Export with filters
mn export work-notes.json --project "Work"
mn export completed.json --completed

# Import notes
mn import backup.json
mn import data.csv --format csv

# Import with duplicate detection
mn import notes.json --no-duplicates --threshold 0.7

Gamification & Goals

profile - Your Dashboard

# View gamification profile
mn profile

# Shows:
# - Level & XP progress
# - Badges unlocked
# - Current streak
# - Goals progress
# - Activity statistics

Leveling System

Level	Rank	XP Required
1	The First Commit Hypothesis	0
2	The Asynchronous Axiom	100
3	The Dependency Theorem	250
4	The Callback Conjecture	500
5	The Recursion Revelation	1,000
6	The Merge Conflict Conjecture	2,000
7	The Singleton Synthesis	4,000
8	The Polymorphism Principle	8,000
9	The Abstraction Ascension	16,000
10	The Infinite Loop Paradox	32,000

badges - Achievement System

# View all badges
mn badges

# Filter badges
mn badges --unlocked
mn badges --locked
mn badges --tier initialization
mn badges --tier refinement
mn badges --tier mastery

74 achievements across 3 tiers plus 12 hidden easter eggs!

goals - Daily & Weekly Tracking

# View current progress
mn goals show
mn :progress

# View history
mn goals history
mn goals history --days 90

# Configure goals
mn settings --set daily_goal=8
mn settings --set weekly_goal=40

settings - Configure Features

# View all settings
mn settings

# Update settings
mn settings --set gamification_enabled=true
mn settings --set daily_goal=5
mn settings --set weekly_goal=25
mn settings --set default_format=kanban
mn settings --set notification_verbosity=full

Easter Eggs

# Hidden commands for fun and bonus XP
mn coffee   # Take a coffee break
mn zen      # Get zen wisdom
mn fortune  # Get a fortune
mn matrix   # Enter the matrix
mn hack     # Hack the system

Aliases & Shortcuts

Built-in Aliases

Alias	Equivalent	Purpose
`:today`	`list --due today`	Today's tasks
`:urgent`	`list --tags urgent`	Urgent items
`:quick`	`list --tags quick`	Quick tasks
`:stats`	`metrics`	Metrics dashboard
`:yesterday`	`list --after yesterday`	Yesterday's activity
`:progress`	`goals show`	Goal progress

Creating Custom Aliases

# Create simple alias
mn alias save standup "list --completed --after yesterday; list --due today"

# Create with description
mn alias save weekly-review \
  "metrics; goals history --days 7; list --completed --after 7d" \
  --description "Weekly review workflow"

# Use alias
mn :standup
mn :weekly-review

Managing Aliases

# List all aliases
mn alias list

# Show alias details
mn alias show standup

# Update alias
mn alias update standup --command "new command"

# Delete alias
mn alias delete old-alias

# Rename alias
mn alias rename old-name new-name

# Export/import for team sharing
mn alias export ~/team-workflows.json
mn alias import ~/team-workflows.json

Recurring Tasks

Automate routine tasks with scheduled generation.

recurring add - Create Recurring Task

Create a new recurring task with a schedule pattern.

Basic Usage

mn recurring add CONTENT --every PATTERN [OPTIONS]

# Daily standup at 9am
mn recurring add "Daily standup" --every day --at 09:00 --tags work

# Weekly team meeting
mn recurring add "Team sync" --every monday --at 10:00 --tags work,meeting

# Monthly report on the 1st
mn recurring add "Monthly report" --every 1st --at 09:00 --tags work,report

# Interval-based (every 2 hours)
mn recurring add "Drink water" --every 2h --tags health

recurring list - List Recurring Tasks

# List all recurring tasks
mn recurring list

# List only active tasks
mn recurring list --active

# List only paused tasks
mn recurring list --paused

recurring show - Show Details

# Show details with upcoming instances
mn recurring show 5 --instances

Managing Recurring Tasks

# Edit recurring task
mn recurring edit 5 --every tue,thu --at 14:00

# Pause (vacation mode)
mn recurring pause 5 --until 2026-01-15

# Resume
mn recurring resume 5

# Delete
mn recurring delete 5

Automation (Cron)

Set up automatic background checking via cron job.

# Set up cron job
mn recurring setup-cron

# Check status
mn recurring status-cron

Schedule Patterns

Pattern	Description	Example
`day`, `daily`	Every day	`--every day`
`weekday`	Monday-Friday	`--every weekday`
`mon,wed,fri`	Specific days	`--every mon,wed,fri`
`1st`, `last`	Day of month	`--every 1st`
`2h`, `30m`	Intervals	`--every 2h`

Productivity Workflows

Daily Workflow

# Morning routine (5-10 min)
mn :progress        # Check goals
mn list --overdue   # Catch up
mn list --due today --format kanban  # Plan day

# Throughout day
mn done 42          # Complete tasks
mn :progress        # Check progress

# Evening wrap-up (10 min)
mn list --completed --after today  # Review accomplishments
mn archive --completed  # Clean up
mn goals show       # Final check

Weekly Review

# Step 1: Reflect
mn list --completed --after 7d --format cards
mn metrics
mn goals history --days 7

# Step 2: Clean up
mn archive --completed
mn project list

# Step 3: Review pending
mn list --pending --format kanban
mn list --overdue

# Step 4: Plan
mn list --tags p1 --pending
mn export ~/backups/weekly-$(date +%Y-%m-%d).json

GTD (Getting Things Done)

# Setup GTD structure
mn project create "GTD" --sections "Inbox,Next Actions,Waiting,Someday"

# Capture (throughout day)
mn add remember "Random thought" --project GTD --section Inbox

# Clarify (morning)
mn list --project GTD --section Inbox

# Engage (throughout day)
mn list --project GTD --section "Next Actions" --pending
mn done <ID>

Kanban Workflow

# Create Kanban board
mn project create "Work" --sections "Backlog,Todo,In Progress,Review,Done"

# View board
mn list --project Work --format kanban

# Add tasks to sections
mn add do "New feature" --project Work --section Todo

# Track progress
mn project stats Work

Pomodoro Technique

# Choose task
mn list --tags focus --pending --format cards

# Work for 25 minutes...

# Mark progress
mn done <ID>
mn goals show

# Take 5-minute break
mn coffee

# Repeat 4 times, then 15-30 min break
mn profile

Quick Reference

Essential Commands

mn add do "Task" Add a new task

mn list List all notes

mn done 42 Mark task complete

mn :today Today's tasks

mn :progress Goal progress

mn profile Gamification profile

mn metrics Analytics dashboard

mn search "text" Search notes

Common Patterns

# Quick task
mn add do "Task" -d today -t quick

# Important task
mn add do "Task" -d today -t p1,urgent

# Natural language (fastest!)
mn add "Review PR tomorrow 2pm #code @Work p1"

# Daily workflow
mn :today  # Review
mn done <IDs>  # Complete
mn :progress  # Check goals
mn archive --completed  # Clean up