HyperList TUI

A powerful Terminal User Interface (TUI) application for creating, editing, and managing HyperLists - a methodology for describing anything in a hierarchical, structured format.

HyperList is a universal methodology for describing anything - any state, item, pattern, action, process, transition, program, instruction set, etc. It can be used as an outliner, a todo list handler, a process design tool, a data modeler, or any other way you want to describe something.

Learn more about the HyperList methodology at: https://isene.org/hyperlist/

For historical context and the original VIM implementation, see: hyperlist.vim

• Paste multiple lines: When pasting multi-line content into item insertion prompts ('o', 'O', 'a', 'A'), each line becomes a separate item
• Visual feedback: Shows [+N lines] indicator during multi-line paste
• Smart insertion: All pasted lines inserted as siblings at the same level
• Great for importing bullet lists from PDFs, emails, or other documents
• Requires rcurses 6.1.5+

• Export to PDF: :export pdf filename.pdf - Full LaTeX-based PDF generation
• Export to LaTeX: :export latex filename.tex - Get the LaTeX source
• Professional output: Color-coded elements, table of contents, headers
• Complete HyperList support: All syntax elements rendered beautifully
• Requires: texlive-latex-base and texlive-latex-extra packages

• Yank to clipboard: 'y' and 'Y' now copy to system clipboard
• Middle-click paste: Yanked items can be pasted into other terminals
• Preserves indentation: Copied text maintains proper structure

• Configuration Lines: Add settings at the bottom of HyperList files using ((option=value, option2=value))
• Theme Support: Three color themes - light (bright colors), normal (standard), dark (for light terminals)
• Line Wrapping: Enable with wrap=yes - wrapped lines use + prefix per HyperList spec
• Line Numbers: Enable with show_numbers=yes
• Manual Configuration: Use :set option=value to change settings on the fly
• View Settings: Use :set to see all settings, :set option to see one setting
• Auto-apply: Settings from config lines are applied when files are loaded
• Invisible Config Lines: Config lines are stored but never displayed in the editor
• Persistent Settings: All :set commands automatically update the config line in the file

• theme - Color theme: light, normal, or dark
• wrap - Line wrapping: yes or no
• show_numbers - Show line numbers: yes or no
• fold_level - Default fold level: 0-99 (0=all folded, 99=all open)
• auto_save - Enable auto-save: yes or no
• auto_save_interval - Auto-save frequency in seconds
• tab_width - Indentation width: 2-8 spaces

Example config line: ((theme=dark, wrap=yes, fold_level=2))

Add a configuration line at the bottom of any HyperList file:

My HyperList
    Item 1
    Item 2

((fold_level=2, theme=light))

Use :set commands while editing:

:set                    # Show all current settings
:set fold_level         # Show current fold level
:set fold_level=3       # Set fold level to 3
:set theme=dark         # Switch to dark theme
:set wrap=yes           # Enable line wrapping

All :set commands automatically update the file's configuration line.

• Save as Template: Save any HyperList document as a reusable template (:st)
• Template Manager: List and delete your custom templates (:lt, :dt)
• Enhanced Template Browser: Shows both built-in and user templates
• Template Metadata: Includes description and creation date
• Templates stored in ~/.hyperlist/templates/ for easy backup and sharing

• File-level encryption for sensitive files (dot files like .passwords.hl)
• Line-level encryption for individual items (Ctrl-E to toggle)
• Secure AES-256-CBC encryption with PBKDF2 key derivation
• Password caching for the session

• Auto-collapse everything outside the current context
• Smart focus: Shows only current item, ancestors, and immediate children
• Visual hierarchy: Focused items in full color, others greyed out
• Improved navigation with proper cursor tracking

• Improved highlighting: Dark gray background preserves syntax colors
• Subtle selection: No more harsh reverse video
• Preserved colors: All HyperList elements maintain their colors when selected

• Hierarchical Organization: Create multi-level nested lists with unlimited depth
• Rich Syntax Highlighting: Color-coded elements for better readability
  • Properties and dates in red
  • Operators (AND, OR, IF, THEN) in blue
  • Checkboxes in various shades of green
  • References in magenta
  • Hash tags in yellow/orange
  • Comments in cyan
• Advanced Folding: Collapse and expand sections with multiple fold levels
• Powerful Navigation: Jump between items, references, and markers
• Full Editing Capabilities: Create, edit, delete, move, and reorganize items
• Checkbox Support: Multiple checkbox types with completion tracking
• Template System: Built-in templates plus save/load custom templates
• Presentation Mode: Focus on current item with auto-collapse

• Encryption: Protect sensitive data with AES-256 encryption
• Automatic detection: Dot files automatically prompt for encryption
• Line-level security: Encrypt individual sensitive items
• Visual indicators: Encrypted lines show lock icon

• Bold: *text*
• Italic: /text/
• Underline: _text_
• References: <reference name> or <file:/path/to/file>
• Hash tags: #tag
• Comments: ; comment text
• Dates: 2025-08-12 or 2025-08-12 14:30

• PDF: Professional LaTeX-based PDF with color coding and TOC
• LaTeX: Source .tex files for customization
• HTML: Full-featured HTML with syntax highlighting
• Markdown: GitHub-flavored Markdown
• Plain Text: Clean text output
• PNG Graph: Visual representation using Graphviz

• Multiple file support with recent files list
• Autosave functionality with configurable intervals
• Split view for working with multiple lists
• Encryption support for sensitive files

• Ruby 3.0 or higher
• rcurses gem: gem install rcurses
• Optional: Graphviz for PNG export (apt-get install graphviz or brew install graphviz)

gem install hyperlist

git clone https://github.com/isene/HyperList.git
cd HyperList
chmod +x hyperlist
./hyperlist

hyperlist                    # Start with empty document
hyperlist file.hl           # Open existing HyperList file
hyperlist .passwords.hl     # Open encrypted file (will prompt for password)
hyperlist file.txt          # Open any text file

• j/↓ - Move down
• k/↑ - Move up
• h - Go to parent item
• l - Go to first child
• g/Home - Go to top
• G/End - Go to bottom
• / - Search
• n - Next search match
• N - Next template marker (=)

• i/Enter - Edit line
• o - Insert line below
• O - Insert line above
• a - Insert child item
• A - Insert outdented item (one level less)
• I - Cycle indentation size (2-5 spaces)
• D - Delete and yank line
• C-D - Delete and yank item with descendants
• y/Y - Copy line/tree
• p - Paste

• Space - Toggle fold
• za - Toggle all folds
• 1-9 - Expand to level
• 0 - Multi-digit fold level

• v - Toggle checkbox
• V - Toggle checkbox with timestamp
• C-E - Encrypt/decrypt current line
• R - Go to reference
• F - Open file reference
• P - Presentation mode (with auto-collapse)
• t - Insert template (built-in or custom)
• ? - Help screen

• :w - Save
• :q - Quit
• :wq or W - Save and quit
• :e file - Open file
• :export pdf - Export to PDF (requires LaTeX)
• :export latex - Export to LaTeX source
• :export html - Export to HTML
• :export md - Export to Markdown
• :graph - Export to PNG graph

• :st - Save current document as template
• :dt - Delete a user template
• :lt - List all user templates
• t - Browse and insert templates

Daily Tasks
    [ ] Morning review
        [ ] Check emails
        [ ] Review calendar
    [ ] Development work
        [ ] Fix bug #123
        [ ] Code review
    [X] Lunch break
    [ ] Afternoon tasks

Save as .passwords.hl for automatic encryption:

Online Accounts
    GitHub
        Username: myuser
        Password: [will be encrypted]
        2FA: enabled
    Banking
        Account: 12345678
        PIN: [will be encrypted]

MyProject #project
    Planning Phase
        [X] Define objectives
        [O] Identify stakeholders
        [ ] Create timeline
    Implementation
        Backend Development
            Authentication module
            Database schema
            REST endpoints
        Frontend Development
            Login page
            Dashboard
    Documentation
        Technical docs
        User manual

Team Meeting 2025-08-12 14:00
    Participants
        John (PM)
        Sarah (Dev)
        Mike (Design)
    Discussion Points
        Sprint planning <Sprint-23>
        Bug review <file:./bugs.hl>
        Design updates
            ; Mike will share mockups
    Action Items
        [ ] John: Update roadmap
        [ ] Sarah: Fix critical bugs
        [ ] Mike: Finalize designs

The application stores configuration in ~/.hyperlist/:

• recent_files.txt - List of recently opened files
• marks.yml - Saved marks across sessions
• command_history - Command history for : commands
• templates/ - User-defined templates

Each HyperList file can have its own configuration line at the bottom:

((option=value, option2=value))

This configuration line is:

• Automatically applied when the file is loaded
• Updated when you use :set commands
• Invisible in the editor (not displayed as content)
• Preserved when saving the file

Available options:

• theme - light/normal/dark
• wrap - yes/no
• show_numbers - yes/no
• fold_level - 0-99
• auto_save - yes/no
• auto_save_interval - seconds
• tab_width - 2-8

Run the included test suite:

./hyperlist test.hl

Follow the instructions in the test file to verify all features are working correctly.

Contributions are welcome! Please feel free to submit issues and pull requests.

• Fixed: Critical navigation bug where the last item (line 154 in test.hl) was not reachable when pressing 'G'
• Fixed: Improved scrolling behavior to properly handle wrapped lines using rcurses built-in capabilities
• Fixed: Split view navigation - g/G/Home/End/PgUp/PgDown now correctly affect the active pane
• Added: Wrap-around navigation in split view right pane (UP from first goes to last, DOWN from last goes to first)
• Added: Visual end-of-document indicator (blank line at bottom) for better UX
• Improved: Scroll calculations now dynamically account for line wrapping

• Added encryption support for sensitive documents
• Enhanced presentation mode
• Various bug fixes and improvements

This software is released into the Public Domain.

Created by Geir Isene - https://isene.org

Based on the HyperList methodology and inspired by the original hyperlist.vim plugin.

• The rcurses library for excellent terminal UI capabilities
• The Ruby community for a wonderful programming language
• All contributors and users of HyperList

For more information about HyperList, visit https://isene.org/hyperlist/