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

npm install -g paul-cli

Or with yarn:

yarn global add paul-cli

Usage

Interactive Mode

Simply run paul to enter the interactive interface:

paul

Navigate with arrow keys, select with space, and confirm with enter.

Direct Commands

Scan Files

# 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

# 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

# Create .paulignore file
paul init

Configuration

.paulignore

Create a .paulignore file in your project root to exclude specific files or patterns:

# 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

# 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

# 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

# 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:

# 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

# 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
• Email: [email protected]

Acknowledgments

• Built with Ink - React for CLI
• Uses clipboardy for clipboard operations
• Powered by meow for CLI parsing

Support

If you find this tool helpful, please ⭐ star the repository!

For issues and feature requests, please create an issue.