SoloPDF CLI 📄✨

A production-ready, blazingly fast PDF manipulation CLI tool powered by Rust and Node.js

🚀 Features

⚡ Ultra-Fast: Core operations powered by Rust for maximum performance
📊 PDF Analysis: Get page counts, file information, and checksums instantly
✍️ Advanced Watermarking: Add customizable text watermarks with precise control
🔐 Digital Signatures: Generate keys, sign PDFs cryptographically, and verify signatures
🎯 Precise Control: Target specific pages (odd, even, or custom ranges)
🌐 Cross-Platform: Native binaries for Linux, macOS (Intel & ARM), and Windows
🎨 Beautiful CLI: Colorful, intuitive command-line interface with progress indicators

📦 Quick Installation

NPM (Recommended)

npm install -g solopdf-cli

Alternative Package Managers

# Yarn
yarn global add solopdf-cli

# pnpm
pnpm add -g solopdf-cli

🎉 Ready to use! The tool is available as both solopdf and solopdf-cli commands.

⚡ Quick Start

# Get page count (ultra-fast)
solopdf pages document.pdf

# Get detailed PDF information
solopdf info document.pdf

# Add watermark to all pages
solopdf watermark input.pdf "Confidential" output.pdf

# Watermark specific pages with custom styling
solopdf watermark input.pdf "Draft" output.pdf --pages "1,3,5" --font-size 16 --color red

# Generate cryptographic key pair
solopdf generate-key --output signing-keys.json

# Sign PDF digitally
solopdf sign-digital contract.pdf signed-contract.pdf signing-keys.json

📖 Complete Usage Guide

📊 PDF Analysis Commands

📄 Page Count Analysis

Get the number of pages in a PDF document instantly.

solopdf pages <file.pdf>

Example Output:

$ solopdf pages document.pdf
🔍 Analyzing: /path/to/document.pdf
📊 Counting pages... ✅ Done!
✅ Success! Page count: 25

ℹ️ Detailed PDF Information

Get comprehensive information about a PDF file.

solopdf info <file.pdf>

Example Output:

$ solopdf info document.pdf
ℹ️  Getting PDF info: /path/to/document.pdf
📋 Analyzing PDF structure... ✅ Done!
✅ Success! PDF Information:
   📄 Pages: 25
   📁 File: /path/to/document.pdf

🔐 File Checksum Verification

Generate SHA-256 checksum for file integrity verification.

solopdf checksum <file.pdf>

Example Output:

$ solopdf checksum document.pdf
🔍 Analyzing file: /path/to/document.pdf
🔐 Calculating checksum... ✅ Done!
✅ Success! File Checksum:
   🔐 Checksum: sha256:a1b2c3d4e5f6...
   📁 File: /path/to/document.pdf
💡 Share this checksum with recipients for file verification

✍️ Advanced PDF Watermarking

Basic Watermarking

Add text watermarks to PDF documents with professional results.

solopdf watermark <input.pdf> "<watermark-text>" <output.pdf>

Advanced Options Reference

Option	Description	Default	Example Values
`--font-size <size>`	Font size in points	`12`	`8`, `12`, `16`, `24`
`--color <color>`	Text color	`black`	`red`, `blue`, `#FF0000`
`--x-position <x>`	X coordinate (points)	Auto	`100`, `200.5`
`--y-position <y>`	Y coordinate (points)	Auto	`50`, `150.25`
`--pages <selection>`	Page selection	`all`	`all`, `even`, `odd`, `"1,3,5"`
`--position <preset>`	Predefined position	`bottom-right`	See positions below
`--rotation <degrees>`	Rotation angle	`0`	`-45`, `0`, `45`, `90`
`--opacity <level>`	Transparency level	`1.0`	`0.1` to `1.0`

Page Selection Options

Value	Description	Example Result
`all`	All pages (default)	Pages 1, 2, 3, 4, 5...
`even`	Even-numbered pages only	Pages 2, 4, 6, 8...
`odd`	Odd-numbered pages only	Pages 1, 3, 5, 7...
`"1,3,5"`	Specific pages (comma-separated)	Only pages 1, 3, and 5
`"1-5"`	Page ranges	Pages 1, 2, 3, 4, 5

Position Presets

┌─────────────┬─────────────┬─────────────┐
│  top-left   │ top-center  │  top-right  │
├─────────────┼─────────────┼─────────────┤
│center-left  │   center    │center-right │
├─────────────┼─────────────┼─────────────┤
│bottom-left  │bottom-center│bottom-right │
└─────────────┴─────────────┴─────────────┘

Real-World Examples

Confidential Document Watermarking:

solopdf watermark sensitive.pdf "CONFIDENTIAL" confidential.pdf \
  --font-size 18 \
  --color red \
  --position center \
  --opacity 0.3 \
  --rotation 45

Draft Watermark on Odd Pages:

solopdf watermark proposal.pdf "DRAFT - NOT FINAL" draft-proposal.pdf \
  --pages odd \
  --font-size 14 \
  --color blue \
  --position top-right

Custom Positioned Signature:

solopdf watermark contract.pdf "Reviewed by Legal Dept." reviewed-contract.pdf \
  --x-position 50 \
  --y-position 750 \
  --font-size 10 \
  --color gray

Specific Pages with Large Text:

solopdf watermark report.pdf "SAMPLE COPY" sample-report.pdf \
  --pages "1,5,10" \
  --font-size 24 \
  --position center \
  --opacity 0.5

🔐 Digital Signature Operations

🔑 Generate Cryptographic Key Pair

Create a new RSA key pair for digital signing operations.

solopdf generate-key [--output <filename.json>]

Options:

--output <file> - Output filename (default: keypair.json)

Example:

$ solopdf generate-key --output company-signing-keys.json
🔑 Generating signing key pair...
🔐 Creating cryptographic keys... ✅ Done!
📋 Extracting key information... ✅ Done!
✅ Success! Key pair generated
   🔑 Fingerprint: SHA256:abcd1234...
   📁 Saved to: /path/to/company-signing-keys.json
⚠️  Keep your private key secure!

✍️ Digital PDF Signing

Sign PDF documents with cryptographic digital signatures for authenticity and integrity.

solopdf sign-digital <input.pdf> <output.pdf> <keyfile.json> [OPTIONS]

Options:

--text <text> - Visible signature text (optional)
--save-sig <file> - Save signature metadata to file (optional)

Example:

$ solopdf sign-digital contract.pdf signed-contract.pdf company-keys.json \
    --text "John Smith, Legal Director" \
    --save-sig signature-info.json

📄 Input PDF: /path/to/contract.pdf
✍️  Output PDF: /path/to/signed-contract.pdf
🔑 Key file: /path/to/company-keys.json
🔐 Digitally signing PDF...
📝 Creating digital signature... ✅ Done!
💾 Signature saved to: /path/to/signature-info.json
✅ Success! PDF digitally signed
   📄 Original: contract.pdf
   📄 Signed: signed-contract.pdf
   🕐 Timestamp: 2025-01-21T14:30:00Z
   🔐 Algorithm: RSA-SHA256

✅ Digital Signature Verification

Verify the authenticity and integrity of digitally signed PDF documents.

solopdf verify-signature <signed.pdf> <signature.json> <keyfile.json>

Example - Valid Signature:

$ solopdf verify-signature signed-contract.pdf signature-info.json company-keys.json
📄 PDF file: /path/to/signed-contract.pdf
📋 Signature: /path/to/signature-info.json
🔑 Key file: /path/to/company-keys.json
🔍 Verifying digital signature...
🔐 Validating signature... ✅ Done!
✅ SUCCESS! Digital signature is VALID
   🎉 Document is authentic and unmodified
   🕐 Verified at: 2025-01-21T14:35:00Z
   📅 Signed at: 2025-01-21T14:30:00Z
   🔐 Algorithm: RSA-SHA256

Example - Invalid Signature:

$ solopdf verify-signature tampered.pdf signature-info.json company-keys.json
❌ FAILED! Digital signature is INVALID
   📝 Reason: Document has been modified after signing
   🕐 Verified at: 2025-01-21T14:40:00Z

📋 Complete Command Reference

Command	Syntax	Description
Analysis
`pages`	`solopdf pages <file.pdf>`	Get page count instantly
`info`	`solopdf info <file.pdf>`	Get detailed PDF information
`checksum`	`solopdf checksum <file.pdf>`	Generate SHA-256 checksum
Watermarking
`watermark`	`solopdf watermark <input.pdf> "<text>" <output.pdf> [options]`	Add advanced watermarks
Digital Signatures
`generate-key`	`solopdf generate-key [--output file.json]`	Generate RSA key pair
`sign-digital`	`solopdf sign-digital <input.pdf> <output.pdf> <keyfile.json> [options]`	Sign PDF digitally
`verify-signature`	`solopdf verify-signature <signed.pdf> <sig.json> <key.json>`	Verify digital signature
Help & Info
`--help`	`solopdf --help` or `solopdf <command> --help`	Show detailed help
`--version`	`solopdf --version`	Show version information

🛠️ System Requirements

Minimum Requirements

Node.js: 18.0.0 or higher
RAM: 512 MB available memory
Disk Space: 50 MB for installation
Operating System: Linux, macOS, or Windows

Supported Architectures

Linux: x86_64 (Intel/AMD 64-bit)
macOS: x86_64 (Intel) and ARM64 (Apple Silicon)
Windows: x86_64 (Intel/AMD 64-bit)

🎉 Zero Configuration: The Rust core is pre-compiled and included - no additional setup required!

📊 Performance Benchmarks

SoloPDF CLI is optimized for speed:

Operation	Typical Performance	Large Files (100+ pages)
Page Count	< 1ms	< 10ms
PDF Info	< 2ms	< 15ms
Checksum	5-20ms	50-200ms
Watermarking	10-100ms	100ms-2s
Digital Signing	50-200ms	200ms-1s
Signature Verification	30-150ms	150ms-500ms

Performance measured on modern systems. Results may vary based on hardware and document complexity.

🏗️ Development & Building

Development Setup

Prerequisites:

# Install Node.js 18+ and pnpm 8+
node --version  # Should be 18.0.0+
pnpm --version  # Should be 8.0.0+

# Install Rust (latest stable)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Clone and Build:

git clone https://github.com/soloflow-ai/solopdf-cli.git
cd solopdf-cli

# Install all dependencies
pnpm install

# Build Rust core with native optimizations
pnpm build:rust

# Build Node.js wrapper
pnpm build

# Link for global testing
cd node-wrapper && npm link

Verify Installation:

solopdf --version
solopdf pages sample-pdfs/single-page.pdf

Development Commands

Command	Purpose	Usage
`pnpm test`	Run all tests	Full test suite
`pnpm lint`	Check code style	TypeScript + Rust
`pnpm build:rust`	Build Rust core	Native compilation
`pnpm build:all`	Build everything	Complete build
`pnpm validate`	Quick validation	Pre-commit checks
`cargo fmt`	Format Rust code	Code formatting
`cargo test`	Run Rust tests	Core functionality

Cross-Platform Building

Build native binaries for all supported platforms:

# Build for specific platforms
pnpm run build:linux      # Linux x86_64
pnpm run build:windows    # Windows x86_64
pnpm run build:macos      # macOS Intel
pnpm run build:macos-arm  # macOS Apple Silicon

# Build all platforms (requires cross-compilation setup)
pnpm run build:all-platforms

🔒 Security Features

Digital Signature Security

RSA-2048 keys for strong cryptographic security
SHA-256 hashing for data integrity verification
Timestamp validation prevents replay attacks
Key fingerprinting for identity verification

File Security

No data transmission - all operations are local
Temporary file cleanup - no data left behind
Memory-safe operations - Rust prevents buffer overflows
Checksum verification - detect file tampering

Privacy Protection

Zero telemetry - no usage data collected
No network requests - completely offline operation
Local processing only - your files never leave your system

🚨 Troubleshooting

Common Issues

❓ "Command not found: solopdf"

# Solution 1: Reinstall globally
npm install -g solopdf-cli

# Solution 2: Check npm global path
npm config get prefix
export PATH=$PATH:$(npm config get prefix)/bin

# Solution 3: Use npx (temporary usage)
npx solopdf-cli pages document.pdf

❓ "Permission denied" on Linux/macOS

# Fix: Make binary executable
chmod +x $(which solopdf)

# Or reinstall with proper permissions
sudo npm install -g solopdf-cli

❓ "Module not found" errors

# Clear npm cache and reinstall
npm cache clean --force
npm install -g solopdf-cli

❓ "Invalid PDF" or parsing errors

# Verify file integrity
file document.pdf
solopdf checksum document.pdf

# Try with a known good PDF
solopdf pages sample-pdfs/single-page.pdf

Getting Help

Check command help: solopdf --help or solopdf <command> --help
Verify installation: solopdf --version
Test with sample: Use files from sample-pdfs/ directory
Report issues: GitHub Issues

📚 API Reference

Node.js Integration

You can also use SoloPDF CLI functions directly in your Node.js applications:

import { 
  getPageCount,
  signPdfWithOptions,
  getPdfInfoBeforeSigning 
} from 'solopdf-cli';

// Get page count
const pages = getPageCount('/path/to/document.pdf');
console.log(`Document has ${pages} pages`);

// Add watermark with options
const options = {
  fontSize: 14,
  color: 'red',
  pages: [1, 3, 5],
  position: 'center',
  opacity: 0.5
};

signPdfWithOptions('/path/to/input.pdf', 'SAMPLE', options);

🤝 Contributing

We welcome contributions from developers of all skill levels! Here's how to get involved:

Quick Contribution Guide

🍴 Fork the repository on GitHub
📝 Create a feature branch: git checkout -b feature/amazing-feature
🛠️ Make your changes and add tests
✅ Test your changes: pnpm test
📤 Commit with clear messages: git commit -m 'Add amazing feature'
🚀 Push to your branch: git push origin feature/amazing-feature
📥 Open a Pull Request with detailed description

Areas for Contribution

🐛 Bug Fixes: Fix issues and improve reliability
⭐ New Features: Add PDF manipulation capabilities
📚 Documentation: Improve guides and examples
🧪 Testing: Add test cases and improve coverage
🎨 UI/UX: Enhance CLI interface and user experience
🔧 Performance: Optimize speed and memory usage

Development Guidelines

Code Style: Follow existing patterns and run pnpm lint
Testing: Add tests for new features (pnpm test)
Documentation: Update README and inline docs
Commits: Use clear, descriptive commit messages
Pull Requests: Include detailed description and link issues

📄 License

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

What this means:

✅ Commercial use - Use in commercial projects
✅ Modification - Modify and adapt the code
✅ Distribution - Share and redistribute
✅ Private use - Use for personal projects
✅ No warranty - Software provided "as is"

🙋‍♂️ Support & Community

Get Help

📖 Documentation: This README and solopdf --help
🐛 Bug Reports: GitHub Issues
💡 Feature Requests: GitHub Discussions
❓ General Questions: GitHub Discussions

Stay Updated

⭐ Star the repository for updates
👀 Watch releases for new versions
📢 Follow us on social media for announcements

Made with ❤️ by Soloflow.AI

⭐ Star this project • 🐛 Report a bug • 💡 Request a feature • 🤝 Contribute

solopdf-cli

SoloPDF CLI 📄✨

🚀 Features

📦 Quick Installation

NPM (Recommended)

Alternative Package Managers

⚡ Quick Start

📖 Complete Usage Guide

📊 PDF Analysis Commands

📄 Page Count Analysis

ℹ️ Detailed PDF Information

🔐 File Checksum Verification

✍️ Advanced PDF Watermarking

Basic Watermarking

Advanced Options Reference

Page Selection Options

Position Presets

Real-World Examples

🔐 Digital Signature Operations

🔑 Generate Cryptographic Key Pair

✍️ Digital PDF Signing

✅ Digital Signature Verification

📋 Complete Command Reference

🛠️ System Requirements

Minimum Requirements

Supported Architectures

📊 Performance Benchmarks

🏗️ Development & Building

Development Setup

Development Commands

Cross-Platform Building

🔒 Security Features

Digital Signature Security

File Security

Privacy Protection

🚨 Troubleshooting

Common Issues

Getting Help

📚 API Reference

Node.js Integration

🤝 Contributing

Quick Contribution Guide

Areas for Contribution

Development Guidelines

📄 License

🙋‍♂️ Support & Community

Get Help

Stay Updated

Readme

Keywords

Package Sidebar

Install

Repository

Homepage

DownloadsWeekly Downloads

Version

License

Unpacked Size

Total Files

Last publish

Collaborators

Weekly Downloads