GitHub - NeverVane/commandchronicles: Stop Scrolling Through History. Start Finding Commands

CommandChronicles CLI (ccr)

===================================================================
                CommandChronicles CLI (ccr) v0.4.2
===================================================================

  🚀 A modern shell history management tool that supercharges
     your command line experience with intelligent search
                and secure local storage

===================================================================

CommandChronicles CLI transforms your shell history into a powerful knowledge base, capturing rich context for every command and providing lightning-fast search capabilities through an intuitive TUI interface.

✨ Key Features

🔐 Military-grade encryption (XChaCha20-Poly1305) for your command history
🔍 Blazing-fast fuzzy search with real-time interactive TUI (Ctrl+R)
📝 Rich note system for annotating commands with context and explanations
🏷️ Comprehensive tag system for categorizing and organizing commands with visual indicators
🔗 Sync rules system for fine-grained control over command synchronization across devices
📊 Rich command metadata (exit codes, duration, working directory, git info)
🐚 Seamless shell integration for bash and zsh with automatic setup
🔑 Secure key derivation (Argon2id) and session management
⚡ Smart caching system for instant search results
📈 Beautiful command statistics and usage analytics

🖼️ CommandChronicles TUI vs Traditional History

Transform your command line experience: From basic history to intelligent, searchable command management

🚀 Quick Start

Installation

# One line install
curl -sSL https://get.commandchronicles.dev | bash

#or

# Clone the repository
git clone https://github.com/NeverVane/commandchronicles.git
cd commandchronicles

# Build the binary
go build -o ccr

# Move to your PATH
sudo mv ccr /usr/local/bin/

Initial Setup

# Initialize CommandChronicles
ccr init

# Automatically install shell hooks (recommended)
ccr install-hooks --auto

# Or manually install for specific shell
ccr install-hooks zsh
ccr install-hooks bash

# Enable auto-sync daemon (recommended)
ccr daemon-control install-service
ccr daemon-control start

After installation, restart your shell or run:

source ~/.zshrc  # for zsh
source ~/.bashrc # for bash

📖 Usage

Interactive Search (TUI)

Press Ctrl+R in your shell to launch the interactive TUI search interface.

TUI Key Bindings:

↑/↓ - Navigate through commands
Enter - Copy command to shell prompt
Ctrl+J - Execute command immediately
Tab - View detailed command information
Ctrl+F - Toggle fuzzy search
Ctrl+F+N - Toggle combined notes+commands search
Ctrl+N - Edit note for selected command
Ctrl+S - Show only successful commands
Ctrl+X - Show only failed commands
Ctrl+T - View statistics
Ctrl+K - Clear search
? - Show help
Esc/Ctrl+C - Exit

Important TUI Behavior:

Shell Integration Required: Command injection (Enter/Ctrl+J) only works when TUI is launched via Ctrl+R after installing shell hooks
Direct TUI Calls: Running ccr tui directly will show the interface but cannot inject commands into your shell
Recommended Usage: Always use Ctrl+R for interactive command search and selection
Installation: Run ccr install-hooks to enable full TUI functionality
Note Editing: Use Ctrl+N to edit notes directly in the TUI interface
Combined Search: Use Ctrl+F+N to search both commands and notes simultaneously

Command Line Search

# Search for commands containing "git"
ccr search git

# Search with fuzzy matching
ccr search --fuzzy "gt sttus"

# Filter by exit code
ccr search --exit-code 0 "docker"

# Filter by directory
ccr search --directory /project "npm"

# Filter by time
ccr search --since 1h "build"
ccr search --since 2d --until 1d "test"

Note System

CommandChronicles includes a comprehensive note system for annotating your commands with context, explanations, and reminders.

Add rich, multi-line notes to your commands with the integrated note editor

# Add a note to a command (use command ID from search results)
ccr note add 123 "This command deploys to production"

# Edit an existing note
ccr note edit 123 "Updated: This command deploys to staging environment"

# View a note
ccr note show 123

# List all commands with notes
ccr note list

# Search within notes
ccr note search "deployment"

# Delete a note
ccr note delete 123

Note Features:

Multi-line support: Notes can span multiple lines with proper formatting
Character limit: 1000 characters maximum per note
Encrypted storage: Notes are encrypted alongside command data
Visual indicators: Commands with notes show a colored dot (●) in the TUI
Integrated search: Use Ctrl+F+N in TUI for combined command+note searching
Rich editing: Full-featured note editor with word wrapping in TUI

TUI Note Editing:

Press Ctrl+N on any command to open the note editor
Multi-line editing: Press Enter for new lines, Ctrl+S to save, Esc to cancel
Real-time validation: Character count display with 1000 character limit
Word wrapping: Automatic text wrapping for long content
Visual feedback: Commands with notes show a colored indicator (●) in the list
Responsive design: Editor adapts to terminal size automatically

Tag System

CommandChronicles includes a comprehensive tag system for categorizing and organizing your commands with visual indicators and powerful search capabilities.

Organize and categorize your commands with color-coded tags for better workflow management

# Add a tag to a command (use command ID from search results)
ccr tag add 123 "docker"

# Remove a tag from a command
ccr tag remove 123 "docker"

# List all tags for a command
ccr tag list 123

# Show all commands with tags
ccr tag show

# Search commands by tag
ccr tag search "docker"

Tag Features:

Tag limits: Up to 5 tags per command, 50 characters maximum per tag
Color customization: Per-tag color configuration for better visual organization
Auto-tagging engine: Intelligent automatic tagging based on command patterns
Default tag rules: Pre-configured tags for common categories (docker, git, file-ops, network, system, etc.)
Encrypted storage: Tags are encrypted alongside command data
Visual indicators: Tagged commands display colored tag badges in the TUI
Integrated search: Tag-based filtering and search capabilities

TUI Tag Integration:

Tags appear as colored badges in the command list
View tags in command details view (Tab key)
Tags are preserved during search and filtering operations
Color-coded organization for quick visual categorization

Sync Rules System

CommandChronicles includes a powerful sync rules system that gives you fine-grained control over which commands synchronize to which devices. Create rules to selectively include or exclude commands from specific devices based on flexible conditions.

# List your devices
ccr devices show

# Create basic rules
ccr rules allow work-laptop                    # Allow all commands to work laptop
ccr rules deny personal-phone                  # Deny all commands to phone

# Create conditional rules
ccr rules deny personal-phone --tag sensitive  # Deny sensitive commands to phone
ccr rules allow home-server --dir /projects    # Only sync /projects commands to server
ccr rules allow dev-machine --pattern "git*"   # Only sync git commands to dev machine

# Manage rules
ccr rules list                    # View all rules
ccr rules delete <rule-id>        # Delete a rule (supports 8-char IDs)
ccr rules simulate "git push"     # Test how rules would apply to a command
ccr rules conflicts               # Detect rule conflicts

Sync Rules Features:

Privacy Control: Exclude personal/sensitive commands from work devices
Device-Specific Workflows: Only sync relevant commands to each device
Conditional Filtering: Apply rules based on tags, directories, command patterns, or time
Retroactive Application: Rules automatically apply to all existing commands, not just new ones
Allow/Deny Logic: Flexible rule combinations for precise control
Device Aliases: Use friendly names instead of device IDs

Rule Conditions:

Tags: --tag docker (commands with specific tags)
Directories: --dir /work (commands from specific paths)
Patterns: --pattern "ssh*" (commands matching patterns)
Time: --time "09:00-17:00" (commands during specific hours)

How It Works: Rules use allow/deny logic with target devices. When rules change, all existing commands are automatically re-evaluated and routing is updated across your devices. No rules means all commands sync everywhere (default behavior).

Example Use Cases:

Work/Personal Separation: ccr rules deny personal-laptop --tag work
Server Deployments: ccr rules allow production-server --tag deploy
Development Focus: ccr rules allow dev-machine --dir /code
Time-Based Rules: ccr rules deny mobile --time "09:00-17:00"

📋 Quick Reference

Tag Commands

ccr tag add <id> <tag>       # Add tag to command
ccr tag remove <id> <tag>    # Remove tag from command
ccr tag list <id>            # List tags for command
ccr tag show                 # Show all tagged commands
ccr tag search <tag>         # Search by tag

Note Commands

ccr note add <id> <note>     # Add note to command
ccr note edit <id> <note>    # Edit existing note
ccr note delete <id>         # Remove note
ccr note show <id>           # Display note
ccr note list                # List all noted commands
ccr note search <query>      # Search within notes

TUI Shortcuts

Ctrl+R         Launch interactive TUI
Ctrl+F         Toggle fuzzy search
Ctrl+F+N       Toggle combined notes+commands search
Ctrl+N         Edit note for selected command
Tab            View command details (including notes)
Enter          Copy command to shell
Ctrl+J         Execute command immediately
Ctrl+S         Filter successful commands only
Ctrl+X         Filter failed commands only
?              Show help
Esc/Ctrl+C     Exit

Statistics

# View command usage statistics
ccr stats

# Export statistics as JSON
ccr stats --format json > stats.json

Import/Export

# Import existing shell history
ccr import ~/.bash_history --format bash
ccr import ~/.zsh_history --format zsh

# Export command history
ccr export --format json > commands.json
ccr export --format bash > commands.bash

Session Management

# Lock your command history (requires password)
ccr lock

# Unlock for searching
ccr unlock

# Change password
ccr change-password

🔧 Configuration

CommandChronicles stores its configuration in ~/.config/commandchronicles/config.toml.

Example Configuration

[cache]
hot_cache_size = 2000      # Number of recent commands to keep in memory
search_batch_size = 5000   # Commands to load per search batch
max_memory_mb = 100        # Maximum memory usage

[security]
session_timeout = 7776000  # Session timeout in seconds (90 days)
argon2_time = 3           # Argon2 time parameter
argon2_memory = 65536     # Argon2 memory parameter (KB)

[shell]
auto_install = false      # Auto-install shell integration
graceful_degradation = true # Fallback if ccr is unavailable

[notes]
max_length = 1000         # Maximum characters per note
enable_search = true      # Enable note content searching
show_indicators = true    # Show note indicators in TUI

[tui]
animations = true         # Enable TUI animations
color_scheme = "auto"     # Color scheme: auto, dark, light
results_per_page = 20     # Results per page in TUI

🛡️ Security

CommandChronicles takes your privacy seriously:

All command history is encrypted using XChaCha20-Poly1305
Passwords are processed using Argon2id key derivation
Session keys are stored securely with configurable timeouts
All data is stored locally - no cloud services or telemetry ( optional )
Secure memory handling prevents sensitive data from being swapped to disk

🎯 Use Cases

CommandChronicles with notes, tags, and sync rules is perfect for:

DevOps workflows: Document deployment commands with environment details and tag by environment
Complex commands: Add context to long docker, kubectl, or database commands with explanatory notes
Learning: Annotate commands you're learning with explanations and categorize with learning tags
Team collaboration: Share documented and tagged command snippets with colleagues
Troubleshooting: Note solutions and context for debugging commands, tag by issue type
Project documentation: Keep command documentation alongside your history with project-specific tags
Command organization: Categorize commands by technology stack (docker, git, network, system)
Quick filtering: Find all Docker commands, Git operations, or system administration tasks instantly
Workflow optimization: Create searchable command libraries organized by function and context
Environment management: Tag commands by deployment environment (dev, staging, prod)
Technology discovery: Browse related commands through consistent tagging conventions
Multi-device privacy: Use sync rules to keep personal commands off work devices and vice versa
Role-based access: Allow only deployment commands to production servers with targeted rules
Development workflows: Sync coding commands to dev machines while filtering system admin tasks
Time-sensitive filtering: Use time-based rules to prevent work commands from syncing during personal hours
Project isolation: Route project-specific commands only to relevant development environments
Security compliance: Ensure sensitive operations never sync to unauthorized or mobile devices

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

👤 Author

Leonardo Zanobi

Website: https://commandchronicles.dev
GitHub: @NeverVane

🙏 Acknowledgments

Bubble Tea for the amazing TUI framework
Bleve for powerful full-text search
Cobra for CLI structure
The Go community for excellent cryptography libraries

Made with ❤️ by Leonardo Zanobi