{"id":30674937,"url":"https://github.com/NeverVane/commandchronicles","last_synced_at":"2025-09-01T08:02:17.670Z","repository":{"id":301350083,"uuid":"1008874989","full_name":"NeverVane/commandchronicles","owner":"NeverVane","description":"Never Lose a Command Again. Ever","archived":false,"fork":false,"pushed_at":"2025-07-21T07:17:43.000Z","size":194930,"stargazers_count":16,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-21T09:22:20.137Z","etag":null,"topics":["cli","command-line","developer-tools","sync"],"latest_commit_sha":null,"homepage":"https://commandchronicles.dev","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/NeverVane.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-26T08:20:02.000Z","updated_at":"2025-07-21T07:17:47.000Z","dependencies_parsed_at":"2025-07-12T20:26:33.628Z","dependency_job_id":"3225edc0-5be1-4a7f-bc95-89e6a13c7721","html_url":"https://github.com/NeverVane/commandchronicles","commit_stats":null,"previous_names":["nevervane/commandchronicles"],"tags_count":9,"template":false,"template_full_name":null,"purl":"pkg:github/NeverVane/commandchronicles","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NeverVane%2Fcommandchronicles","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NeverVane%2Fcommandchronicles/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NeverVane%2Fcommandchronicles/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NeverVane%2Fcommandchronicles/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/NeverVane","download_url":"https://codeload.github.com/NeverVane/commandchronicles/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NeverVane%2Fcommandchronicles/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273092822,"owners_count":25044435,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-01T02:00:09.058Z","response_time":120,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","command-line","developer-tools","sync"],"created_at":"2025-09-01T08:01:11.064Z","updated_at":"2025-09-01T08:02:17.645Z","avatar_url":"https://github.com/NeverVane.png","language":"Go","readme":"# CommandChronicles CLI (ccr)\n\n```\n===================================================================\n                CommandChronicles CLI (ccr) v0.4.2\n===================================================================\n\n  🚀 A modern shell history management tool that supercharges\n     your command line experience with intelligent search\n                and secure local storage\n\n===================================================================\n```\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/NeverVane/commandchronicles/releases\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/version-0.4.2-blue.svg\" alt=\"Version\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"LICENSE\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/license-MIT-green.svg\" alt=\"License\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://golang.org\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/go-%3E%3D1.23-00ADD8.svg\" alt=\"Go Version\"\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n**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.\n\n## ✨ Key Features\n\n- 🔐 **Military-grade encryption** (XChaCha20-Poly1305) for your command history\n- 🔍 **Blazing-fast fuzzy search** with real-time interactive TUI (Ctrl+R)\n- 📝 **Rich note system** for annotating commands with context and explanations\n- 🏷️ **Comprehensive tag system** for categorizing and organizing commands with visual indicators\n- 🔗 **Sync rules system** for fine-grained control over command synchronization across devices\n- 📊 **Rich command metadata** (exit codes, duration, working directory, git info)\n- 🐚 **Seamless shell integration** for bash and zsh with automatic setup\n- 🔑 **Secure key derivation** (Argon2id) and session management\n- ⚡ **Smart caching system** for instant search results\n- 📈 **Beautiful command statistics** and usage analytics\n\n## 🖼️ CommandChronicles TUI vs Traditional History\n\n![History Comparison](docs/images/screenshots/historyComparison.png)\n\n*Transform your command line experience: From basic history to intelligent, searchable command management*\n\n## 🚀 Quick Start\n\n### Installation\n\n```bash\n# One line install\ncurl -sSL https://get.commandchronicles.dev | bash\n```\n\n#or\n\n```bash\n# Clone the repository\ngit clone https://github.com/NeverVane/commandchronicles.git\ncd commandchronicles\n\n# Build the binary\ngo build -o ccr\n\n# Move to your PATH\nsudo mv ccr /usr/local/bin/\n```\n\n### Initial Setup\n\n```bash\n# Initialize CommandChronicles\nccr init\n\n# Automatically install shell hooks (recommended)\nccr install-hooks --auto\n\n# Or manually install for specific shell\nccr install-hooks zsh\nccr install-hooks bash\n\n# Enable auto-sync daemon (recommended)\nccr daemon-control install-service\nccr daemon-control start\n```\n\nAfter installation, restart your shell or run:\n```bash\nsource ~/.zshrc  # for zsh\nsource ~/.bashrc # for bash\n```\n\n## 📖 Usage\n\n### Interactive Search (TUI)\n\nPress `Ctrl+R` in your shell to launch the interactive TUI search interface.\n\n**TUI Key Bindings:**\n- `↑/↓` - Navigate through commands\n- `Enter` - Copy command to shell prompt\n- `Ctrl+J` - Execute command immediately\n- `Tab` - View detailed command information\n- `Ctrl+F` - Toggle fuzzy search\n- `Ctrl+F+N` - Toggle combined notes+commands search\n- `Ctrl+N` - Edit note for selected command\n- `Ctrl+S` - Show only successful commands\n- `Ctrl+X` - Show only failed commands\n- `Ctrl+T` - View statistics\n- `Ctrl+K` - Clear search\n- `?` - Show help\n- `Esc/Ctrl+C` - Exit\n\n**Important TUI Behavior:**\n- **Shell Integration Required**: Command injection (Enter/Ctrl+J) only works when TUI is launched via `Ctrl+R` after installing shell hooks\n- **Direct TUI Calls**: Running `ccr tui` directly will show the interface but cannot inject commands into your shell\n- **Recommended Usage**: Always use `Ctrl+R` for interactive command search and selection\n- **Installation**: Run `ccr install-hooks` to enable full TUI functionality\n- **Note Editing**: Use `Ctrl+N` to edit notes directly in the TUI interface\n- **Combined Search**: Use `Ctrl+F+N` to search both commands and notes simultaneously\n\n### Command Line Search\n\n```bash\n# Search for commands containing \"git\"\nccr search git\n\n# Search with fuzzy matching\nccr search --fuzzy \"gt sttus\"\n\n# Filter by exit code\nccr search --exit-code 0 \"docker\"\n\n# Filter by directory\nccr search --directory /project \"npm\"\n\n# Filter by time\nccr search --since 1h \"build\"\nccr search --since 2d --until 1d \"test\"\n```\n\n### Note System\n\nCommandChronicles includes a comprehensive note system for annotating your commands with context, explanations, and reminders.\n\n![Note System](docs/images/features/noteSystem.png)\n\n*Add rich, multi-line notes to your commands with the integrated note editor*\n\n```bash\n# Add a note to a command (use command ID from search results)\nccr note add 123 \"This command deploys to production\"\n\n# Edit an existing note\nccr note edit 123 \"Updated: This command deploys to staging environment\"\n\n# View a note\nccr note show 123\n\n# List all commands with notes\nccr note list\n\n# Search within notes\nccr note search \"deployment\"\n\n# Delete a note\nccr note delete 123\n```\n\n**Note Features:**\n- **Multi-line support**: Notes can span multiple lines with proper formatting\n- **Character limit**: 1000 characters maximum per note\n- **Encrypted storage**: Notes are encrypted alongside command data\n- **Visual indicators**: Commands with notes show a colored dot (●) in the TUI\n- **Integrated search**: Use `Ctrl+F+N` in TUI for combined command+note searching\n- **Rich editing**: Full-featured note editor with word wrapping in TUI\n\n**TUI Note Editing:**\n- Press `Ctrl+N` on any command to open the note editor\n- **Multi-line editing**: Press `Enter` for new lines, `Ctrl+S` to save, `Esc` to cancel\n- **Real-time validation**: Character count display with 1000 character limit\n- **Word wrapping**: Automatic text wrapping for long content\n- **Visual feedback**: Commands with notes show a colored indicator (●) in the list\n- **Responsive design**: Editor adapts to terminal size automatically\n\n### Tag System\n\nCommandChronicles includes a comprehensive tag system for categorizing and organizing your commands with visual indicators and powerful search capabilities.\n\n![Tag System](docs/images/features/tagSystem.png)\n\n*Organize and categorize your commands with color-coded tags for better workflow management*\n\n```bash\n# Add a tag to a command (use command ID from search results)\nccr tag add 123 \"docker\"\n\n# Remove a tag from a command\nccr tag remove 123 \"docker\"\n\n# List all tags for a command\nccr tag list 123\n\n# Show all commands with tags\nccr tag show\n\n# Search commands by tag\nccr tag search \"docker\"\n```\n\n**Tag Features:**\n- **Tag limits**: Up to 5 tags per command, 50 characters maximum per tag\n- **Color customization**: Per-tag color configuration for better visual organization\n- **Auto-tagging engine**: Intelligent automatic tagging based on command patterns\n- **Default tag rules**: Pre-configured tags for common categories (docker, git, file-ops, network, system, etc.)\n- **Encrypted storage**: Tags are encrypted alongside command data\n- **Visual indicators**: Tagged commands display colored tag badges in the TUI\n- **Integrated search**: Tag-based filtering and search capabilities\n\n**TUI Tag Integration:**\n- Tags appear as colored badges in the command list\n- View tags in command details view (Tab key)\n- Tags are preserved during search and filtering operations\n- Color-coded organization for quick visual categorization\n\n### Sync Rules System\n\nCommandChronicles 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.\n\n```bash\n# List your devices\nccr devices show\n\n# Create basic rules\nccr rules allow work-laptop                    # Allow all commands to work laptop\nccr rules deny personal-phone                  # Deny all commands to phone\n\n# Create conditional rules\nccr rules deny personal-phone --tag sensitive  # Deny sensitive commands to phone\nccr rules allow home-server --dir /projects    # Only sync /projects commands to server\nccr rules allow dev-machine --pattern \"git*\"   # Only sync git commands to dev machine\n\n# Manage rules\nccr rules list                    # View all rules\nccr rules delete \u003crule-id\u003e        # Delete a rule (supports 8-char IDs)\nccr rules simulate \"git push\"     # Test how rules would apply to a command\nccr rules conflicts               # Detect rule conflicts\n```\n\n**Sync Rules Features:**\n- **Privacy Control**: Exclude personal/sensitive commands from work devices\n- **Device-Specific Workflows**: Only sync relevant commands to each device\n- **Conditional Filtering**: Apply rules based on tags, directories, command patterns, or time\n- **Retroactive Application**: Rules automatically apply to all existing commands, not just new ones\n- **Allow/Deny Logic**: Flexible rule combinations for precise control\n- **Device Aliases**: Use friendly names instead of device IDs\n\n**Rule Conditions:**\n- **Tags**: `--tag docker` (commands with specific tags)\n- **Directories**: `--dir /work` (commands from specific paths)\n- **Patterns**: `--pattern \"ssh*\"` (commands matching patterns)\n- **Time**: `--time \"09:00-17:00\"` (commands during specific hours)\n\n**How It Works:**\nRules 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).\n\n**Example Use Cases:**\n- **Work/Personal Separation**: `ccr rules deny personal-laptop --tag work`\n- **Server Deployments**: `ccr rules allow production-server --tag deploy`\n- **Development Focus**: `ccr rules allow dev-machine --dir /code`\n- **Time-Based Rules**: `ccr rules deny mobile --time \"09:00-17:00\"`\n\n## 📋 Quick Reference\n\n### Tag Commands\n```bash\nccr tag add \u003cid\u003e \u003ctag\u003e       # Add tag to command\nccr tag remove \u003cid\u003e \u003ctag\u003e    # Remove tag from command\nccr tag list \u003cid\u003e            # List tags for command\nccr tag show                 # Show all tagged commands\nccr tag search \u003ctag\u003e         # Search by tag\n```\n\n### Note Commands\n```bash\nccr note add \u003cid\u003e \u003cnote\u003e     # Add note to command\nccr note edit \u003cid\u003e \u003cnote\u003e    # Edit existing note\nccr note delete \u003cid\u003e         # Remove note\nccr note show \u003cid\u003e           # Display note\nccr note list                # List all noted commands\nccr note search \u003cquery\u003e      # Search within notes\n```\n\n### TUI Shortcuts\n```\nCtrl+R         Launch interactive TUI\nCtrl+F         Toggle fuzzy search\nCtrl+F+N       Toggle combined notes+commands search\nCtrl+N         Edit note for selected command\nTab            View command details (including notes)\nEnter          Copy command to shell\nCtrl+J         Execute command immediately\nCtrl+S         Filter successful commands only\nCtrl+X         Filter failed commands only\n?              Show help\nEsc/Ctrl+C     Exit\n```\n\n### Statistics\n\n```bash\n# View command usage statistics\nccr stats\n\n# Export statistics as JSON\nccr stats --format json \u003e stats.json\n```\n\n### Import/Export\n\n```bash\n# Import existing shell history\nccr import ~/.bash_history --format bash\nccr import ~/.zsh_history --format zsh\n\n# Export command history\nccr export --format json \u003e commands.json\nccr export --format bash \u003e commands.bash\n```\n\n### Session Management\n\n```bash\n# Lock your command history (requires password)\nccr lock\n\n# Unlock for searching\nccr unlock\n\n# Change password\nccr change-password\n```\n\n## 🔧 Configuration\n\nCommandChronicles stores its configuration in `~/.config/commandchronicles/config.toml`.\n\n### Example Configuration\n\n```toml\n[cache]\nhot_cache_size = 2000      # Number of recent commands to keep in memory\nsearch_batch_size = 5000   # Commands to load per search batch\nmax_memory_mb = 100        # Maximum memory usage\n\n[security]\nsession_timeout = 7776000  # Session timeout in seconds (90 days)\nargon2_time = 3           # Argon2 time parameter\nargon2_memory = 65536     # Argon2 memory parameter (KB)\n\n[shell]\nauto_install = false      # Auto-install shell integration\ngraceful_degradation = true # Fallback if ccr is unavailable\n\n[notes]\nmax_length = 1000         # Maximum characters per note\nenable_search = true      # Enable note content searching\nshow_indicators = true    # Show note indicators in TUI\n\n[tui]\nanimations = true         # Enable TUI animations\ncolor_scheme = \"auto\"     # Color scheme: auto, dark, light\nresults_per_page = 20     # Results per page in TUI\n```\n\n## 🛡️ Security\n\nCommandChronicles takes your privacy seriously:\n\n- All command history is encrypted using XChaCha20-Poly1305\n- Passwords are processed using Argon2id key derivation\n- Session keys are stored securely with configurable timeouts\n- All data is stored locally - no cloud services or telemetry ( optional )\n- Secure memory handling prevents sensitive data from being swapped to disk\n\n## 🎯 Use Cases\n\nCommandChronicles with notes, tags, and sync rules is perfect for:\n\n- **DevOps workflows**: Document deployment commands with environment details and tag by environment\n- **Complex commands**: Add context to long docker, kubectl, or database commands with explanatory notes\n- **Learning**: Annotate commands you're learning with explanations and categorize with learning tags\n- **Team collaboration**: Share documented and tagged command snippets with colleagues\n- **Troubleshooting**: Note solutions and context for debugging commands, tag by issue type\n- **Project documentation**: Keep command documentation alongside your history with project-specific tags\n- **Command organization**: Categorize commands by technology stack (docker, git, network, system)\n- **Quick filtering**: Find all Docker commands, Git operations, or system administration tasks instantly\n- **Workflow optimization**: Create searchable command libraries organized by function and context\n- **Environment management**: Tag commands by deployment environment (dev, staging, prod)\n- **Technology discovery**: Browse related commands through consistent tagging conventions\n- **Multi-device privacy**: Use sync rules to keep personal commands off work devices and vice versa\n- **Role-based access**: Allow only deployment commands to production servers with targeted rules\n- **Development workflows**: Sync coding commands to dev machines while filtering system admin tasks\n- **Time-sensitive filtering**: Use time-based rules to prevent work commands from syncing during personal hours\n- **Project isolation**: Route project-specific commands only to relevant development environments\n- **Security compliance**: Ensure sensitive operations never sync to unauthorized or mobile devices\n\n## 🤝 Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add some amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 👤 Author\n\n**Leonardo Zanobi**\n\n- Website: [https://commandchronicles.dev](https://commandchronicles.dev)\n- GitHub: [@NeverVane](https://github.com/NeverVane)\n\n## 🙏 Acknowledgments\n\n- [Bubble Tea](https://github.com/charmbracelet/bubbletea) for the amazing TUI framework\n- [Bleve](https://github.com/blevesearch/bleve) for powerful full-text search\n- [Cobra](https://github.com/spf13/cobra) for CLI structure\n- The Go community for excellent cryptography libraries\n\n---\n\n\u003cp align=\"center\"\u003e\n  Made with ❤️ by Leonardo Zanobi\n\u003c/p\u003e\n","funding_links":[],"categories":["CLIs \u0026 Terminal Tools"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FNeverVane%2Fcommandchronicles","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FNeverVane%2Fcommandchronicles","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FNeverVane%2Fcommandchronicles/lists"}