@blockingmachine/cli (1.0.1-beta.2)

Published 2026-10-29 00:40:42 +00:00 by danielhipskind

Setup this registry in your project .npmrc file:

@blockingmachine:registry=

To install the package using npm, run the following command:

npm install @blockingmachine/cli@1.0.1-beta.2

or add it to the package.json file:

"@blockingmachine/cli": "1.0.1-beta.2"

For more information on the npm registry, see the documentation.

Blockingmachine

Description

Blockingmachine CLI is a powerful command-line tool that streamlines the process of collecting, analyzing, and exporting ad-blocking and privacy filter lists. It aggregates rules from multiple trusted sources, intelligently deduplicates entries, categorizes blocking rules, and exports to various formats including AdGuard, hosts files, dnsmasq, and more. Designed for flexibility, the tool allows for custom filtering by category, priority, and tags, enabling both automated workflows and personalized filter list creation.

Blockingmachine Core - Core functionality library
Blockingmachine Desktop - Desktop application for managing filter lists

Quick Start

# Install globally
npm install -g @blockingmachine/cli

# Create a new configuration
blockingmachine init

# Import and export rules
blockingmachine import
blockingmachine export adguard

Timeline

Current Release (v1.0.0-beta.8)

🚀 Full integration with @blockingmachine/core
💪 TypeScript support
📥 Multiple source list support
🔄 Rule categorization and filtering
⚡ Multi-format export capabilities
✅ Advanced configuration options
🐞 Bug fixes and performance improvements

Upcoming Features (v1.0.0)

📊 Enhanced statistics and reporting
🔍 Improved pattern matching and rule validation
📋 Support for additional export formats
🌐 Better network resilience and retry logic
🎯 Rule optimization commands
📦 Smaller installation footprint
🧪 Extended test coverage

Future Roadmap (v1.x+)

🔄 Streaming processing for large rule sets
🌍 Internationalization support
🔒 Enhanced security features
📈 Performance optimizations
🧩 Plugin system for custom rule processors
🤝 Third-party service integrations
🛠️ Advanced debugging and troubleshooting tools

Version History

1.0.0-beta.3 (Current)

Added parallel processing capabilities
Fixed MongoDB connection handling issues
Added more comprehensive export formats
Improved command-line argument parsing
Enhanced logging and error reporting
Fixed NPM packaging issues

1.0.0-beta.2

Added support for multiple export formats
Enhanced configuration options
Improved rule categorization
Fixed dependency resolution issues
Optimized database operations

1.0.0-beta.1

Initial public release
Core commands (import/export) stable
Basic documentation
Essential features implemented

0.9.0 (Internal)

Feature complete CLI
Internal testing and validation
Performance optimization
Documentation drafting

0.5.0 (Development)

Command structure implementation
Basic feature development
Initial testing setup

Features

Enhanced Rule Processing

Smart Rule Classification: Automatically detects and categorizes rules:
- Domain-based blocking rules
- Regular expression patterns
- Exception rules
- Cosmetic filters
Mobile-Specific Detection: Identifies mobile-specific rules using patterns:
- App store URLs
- Mobile domains
- App-specific patterns
- Platform-specific rules

Advanced Filtering

Category-Based Management:

blockingmachine export --categories privacy,security
blockingmachine export --exclude advertising,gaming

Priority System:

blockingmachine export --min-priority 80

Tag-Based Filtering:

blockingmachine export --tags mobile,trusted

Multiple Export Formats

DNS-Based Formats:
- Hosts files (hosts)
- dnsmasq configuration (dnsmasq)
- Unbound configuration (unbound)
- BIND configuration (bind)
Browser-Based Formats:
- AdGuard (adguard)
- ABP format (abp)
Application-Specific:
- Privoxy rules (privoxy)
- Shadowrocket configuration (shadowrocket)

Database Management

# Import and process rules
blockingmachine import

# View database statistics
blockingmachine view
blockingmachine view --sample 10

# Run database migrations
blockingmachine migrate

# Clean up and maintenance
blockingmachine cleanup
blockingmachine cleanup --drop  # Development only

Configuration

{
  "mongodb": {
    "uri": "mongodb://localhost:27017/blockingmachine",
    "options": {
      "maxPoolSize": 10
    }
  },
  "output": {
    "directory": "./filters/output"
  },
  "sources": [
    {
      "name": "EasyPrivacy",
      "url": "https://easylist.to/easylist/easyprivacy.txt",
      "category": "privacy",
      "enabled": true,
      "priority": 90
    }
  ]
}

Logging and Debugging

Detailed Logging:
```
blockingmachine --debug import
```
Log Files:
- logs/error.log: Error-level messages
- logs/combined.log: All log levels

Rule Processing Pipeline

graph TD
    A[Download Rules] --> B[Parse & Classify]
    B --> C[Apply Modifiers]
    C --> D[Deduplication]
    D --> E[Store in MongoDB]
    E --> F[Export Filters]

Performance Optimization

Caching System:

# Enable caching in .blockingmachinerc.json
{
  "caching": {
    "enabled": true,
    "ttl": 3600,
    "maxSize": "100mb"
  }
}

Batch Processing: Rules are processed in configurable batch sizes
Parallel Processing: Multi-threaded rule processing for better performance

Error Handling

# View detailed error logs
blockingmachine --debug import

# Check rule validation errors
blockingmachine validate --fix

Contributing

Setting up the development environment:

# Fork and clone the repository
git clone https://github.com/yourusername/blockingmachine-cli.git

# Install dependencies
cd blockingmachine
npm install

# Run tests
npm test

# Start in development mode
npm run dev

Running Tests:

# Run all tests
npm test

# Run specific test suite
npm test -- --grep "rule processing"

# Run with coverage
npm run test:coverage

Environment Variables

# Development mode
NODE_ENV=development

# MongoDB configuration
MONGODB_URI=mongodb://localhost:27017/blockingmachine
MONGODB_MAX_POOL_SIZE=10

# Logging
LOG_LEVEL=debug
LOG_FORMAT=pretty

# Feature flags
ENABLE_CACHING=true
ENABLE_PARALLEL_PROCESSING=true

Troubleshooting

Common Issues

MongoDB Connection Issues

# Check MongoDB status
brew services list | grep mongodb

# Start MongoDB if needed
brew services start mongodb-community

Permission Issues

# Fix output directory permissions
chmod 755 ./filters/output

Memory Issues

# Increase Node.js memory limit
export NODE_OPTIONS="--max-old-space-size=4096"

API Documentation

Command Context

interface CommandContext {
  config: AppConfig;
  debug: boolean;
  logger: Logger;
}

Export Options

interface ExportOptions {
  formats?: SupportedFormat[];
  categories?: string[];
  excludeCategories?: string[];
  minPriority?: number;
  tags?: string[];
  outputPath?: string;
}

Security

All downloaded content is validated and sanitized
HTTPS-only for rule downloads
Input validation for all command parameters
Safe file system operations

Please read our Contributing Guide for more details.

Code Style

We use ESLint and Prettier to maintain code quality. Before submitting a pull request:

# Run linter
  npm run lint

  # Fix linting issues automatically
  npm run lint:fix

Technology Stack

Electron: Cross-platform desktop application framework
React: UI library for building interactive interfaces
TypeScript: Type-safe JavaScript
Recharts: Responsive charting library
Electron Store: Persistent settings storage
@blockingmachine/core: Core rule processing functionality

License

This project is licensed under the BSD-3-Clause License.

Made with ❤️ by Greigh Studios LLC

Dependencies

ID	Version
@blockingmachine/core	^1.0.1-beta.2
chalk	^6.0.1
commander	^15.0.0
cosmiconfig	^10.0.1
dotenv	^18.0.9
mongoose	^9.11.4
node-fetch	^3.3.2
progress	^2.0.3
winston	^3.19.0
zod	^4.6.7

Development dependencies

ID	Version
@types/jest	^30.0.0
@types/node	^26.6.5
@types/progress	^2.0.7
jest	^30.5.2
rimraf	^6.1.3
ts-jest	^29.4.15
typescript	~5.9.3

Details

npm

2026-10-29 00:40:42 +00:00

Greigh Studios LLC

Project website

BSD-3-Clause

86 KiB

Assets (1)

cli-1.0.1-beta.2.tgz 86 KiB

Versions (7) View all

1.0.1-beta.3

2026-11-02

1.0.1-beta.2

2026-10-29

1.0.0

2026-10-12

1.0.0-rc.12

2026-10-12

1.0.0-rc.11

2026-10-10

@blockingmachine/cli (1.0.1-beta.2)

Installation

About this package

Blockingmachine

Description

Quick Start

Timeline

Current Release (v1.0.0-beta.8)

Upcoming Features (v1.0.0)

Future Roadmap (v1.x+)

Version History

1.0.0-beta.3 (Current)

1.0.0-beta.2

1.0.0-beta.1

0.9.0 (Internal)

0.5.0 (Development)

Features

Enhanced Rule Processing

Advanced Filtering

Multiple Export Formats

Database Management

Configuration

Logging and Debugging

Rule Processing Pipeline

Performance Optimization

Error Handling

Contributing

Environment Variables

Troubleshooting

Common Issues

API Documentation

Command Context

Export Options

Security

Code Style

Technology Stack

License

Dependencies

@blockingmachine/cli (1.0.1-beta.2)

Installation

About this package

Blockingmachine

Description

Related Projects

Quick Start

Timeline

Current Release (v1.0.0-beta.8)

Upcoming Features (v1.0.0)

Future Roadmap (v1.x+)

Version History

1.0.0-beta.3 (Current)

1.0.0-beta.2

1.0.0-beta.1

0.9.0 (Internal)

0.5.0 (Development)

Features

Enhanced Rule Processing

Advanced Filtering

Multiple Export Formats

Database Management

Configuration

Logging and Debugging

Rule Processing Pipeline

Performance Optimization

Error Handling

Contributing

Environment Variables

Troubleshooting

Common Issues

API Documentation

Command Context

Export Options

Security

Code Style

Technology Stack

License

Dependencies