@codewithmehmet/paul-cli

# paul-cli 🚀 A powerful CLI tool for intelligent project file scanning and Git change tracking with an elegant interactive interface. ## Features ✨ **Smart File Scanning** - Automatically respects `.gitignore` and custom `.paulignore` rules - Excludes binary files and common build artifacts - Generates clean markdown documentation of your codebase 🔄 **Advanced Git Integration** - View staged/unstaged changes with diffs - Explore commit history and changes - Track all modifications since a specific commit - Export Git changes in markdown format 📦 **Preset System** - Save and reuse file selections - Manage multiple preset configurations - Quick access to common file combinations 🎨 **Dual Interface** - Interactive mode with intuitive navigation - Direct command mode for automation - Beautiful terminal UI powered by Ink/React ## Installation ```bash npm install -g paul-cli ``` Or with yarn: ```bash yarn global add paul-cli ``` ## Usage ### Interactive Mode Simply run `paul` to enter the interactive interface: ```bash paul ``` Navigate with arrow keys, select with space, and confirm with enter. ### Direct Commands #### Scan Files ```bash # Scan and copy to clipboard (default) paul ls # Save to file with auto-generated name paul ls -o # Save to specific file paul ls -o documentation.md # Exclude file contents (structure only) paul ls --no-content # Exclude tree visualization paul ls --no-tree ``` #### Git Changes ```bash # View current staged changes (default) paul diff # View both staged and unstaged changes paul diff --all paul diff -a # View only unstaged changes paul diff --unstaged # View changes from a specific commit paul diff abc123 paul diff HEAD~3 # View all changes since a commit paul diff abc123 --since paul diff HEAD~5 --since # Save diff to file paul diff -o changes.md ``` #### Initialize Configuration ```bash # Create .paulignore file paul init ``` ## Configuration ### .paulignore Create a `.paulignore` file in your project root to exclude specific files or patterns: ```gitignore # Exclude test files *.test.js *.spec.js # Exclude documentation docs/generated/ # Exclude specific directories temp/ cache/ ``` The tool automatically respects: - `.gitignore` rules - `.paulignore` rules (if present) - Common binary and build files ### Presets Presets are stored in `.paul/presets.json` and can be managed through the interactive interface: 1. Select files in interactive mode 2. Press `p` to open preset manager 3. Save current selection with a name 4. Load presets for quick access later ## Examples ### Generate Project Documentation ```bash # Full project documentation with code paul ls -o project-docs.md # Structure only (no code contents) paul ls --no-content -o structure.md ``` ### Track Development Progress ```bash # See what changed today paul diff --all # Review changes since last release paul diff v1.0.0 --since -o changelog.md # Check specific commit changes paul diff abc123 ``` ### Automation ```bash # Add to package.json scripts "scripts": { "docs": "paul ls -o docs/PROJECT.md", "changes": "paul diff --all -o CHANGES.md" } ``` ## Output Format The tool generates clean markdown with: - Project structure visualization - File contents with syntax highlighting - Git diffs with proper formatting - File size and line count statistics Example output structure: ```markdown # Project Context: my-project Generated: 2025-08-31 ## Project Structure ├── 📁 src │ ├── 📄 index.js │ └── 📄 utils.js └── 📄 package.json ## File Contents ### src/index.js \`\`\`javascript // code here \`\`\` ``` ## Keyboard Shortcuts **Interactive Mode:** - `↑↓` - Navigate items - `Space` - Select/deselect - `Enter` - Confirm/expand - `a` - Select all - `c` - Clear selection - `p` - Manage presets - `o` - Export options - `ESC/q` - Go back/quit **Git Mode:** - `s` - Toggle staged files - `u` - Toggle unstaged files ## Requirements - Node.js >= 16 - Git (for diff features) ## Development ```bash # Clone repository git clone https://github.com/yourusername/paul-cli.git cd paul-cli # Install dependencies npm install # Build npm run build # Development mode with watch npm run dev # Link for local testing npm link ``` ## Contributing Contributions are welcome! Please feel free to submit a Pull Request. 1. Fork the repository 2. Create your feature branch (`git checkout -b feature/AmazingFeature`) 3. Commit your changes (`git commit -m 'Add some AmazingFeature'`) 4. Push to the branch (`git push origin feature/AmazingFeature`) 5. Open a Pull Request ## License MIT © Mehmet ## Author **Your Name** - GitHub: [@codewithmehmet](https://github.com/codewithmehmet) - Email: codewithmehmet@gmail.Com ## Acknowledgments - Built with [Ink](https://github.com/vadimdemedes/ink) - React for CLI - Uses [clipboardy](https://github.com/sindresorhus/clipboardy) for clipboard operations - Powered by [meow](https://github.com/sindresorhus/meow) for CLI parsing ## Support If you find this tool helpful, please ⭐ star the repository! For issues and feature requests, please [create an issue](https://github.com/codewithmehmet@gmail.com/paul-cli/issues).