PureLink

Overview

PureLink is a fast, opinionated command-line tool for security engineers, network admins, and developers who need to validate remote endpoints before routing traffic through them. It answers one question: "Can I trust this endpoint?"

Built in Go with zero CGO dependencies, PureLink ships as a single static binary for Linux, macOS, and Windows.

Features

Installation

Go Install

go install github.com/MasuRii/PureLink/cmd/purelink@latest

From Source

git clone https://github.com/MasuRii/PureLink.git
cd PureLink
make build

The binary is written to bin/purelink.

Prebuilt Binaries

Download from the releases page. Builds are available for:

Homebrew (macOS & Linux)

brew install --cask MasuRii/tap/purelink

Scoop (Windows)

scoop bucket add MasuRii https://github.com/MasuRii/scoop-bucket.git
scoop install purelink

WinGet (Windows)

winget install MasuRii.PureLink

Docker

docker run --rm ghcr.io/masurii/purelink:latest --version
docker run --rm ghcr.io/masurii/purelink:latest check 1.2.3.4

npm

npm install -g purelink
# Or run without installing:
npx purelink --version

Quick Start

# Launch the interactive TUI
purelink

# Check a single IP
purelink check 159.89.194.243

# Check with abuse intelligence
purelink check 159.89.194.243 --abuse

# Check with purity signals and DNS info
purelink check 159.89.194.243 --purity --dns

# Fail CI when abuse risk is detected
purelink check 159.89.194.243 --fail-on-abuse

# Batch check from a file
purelink batch ./endpoints.txt

# Batch from stdin with JSON output and 16 workers
cat endpoints.txt | purelink batch - --stdin --format json --workers 16

# Verify endpoint uniqueness across lists
purelink dedupe ./list-a.txt ./list-b.txt

# Full diagnostic report with TLS and HTTP probes
purelink report example.com:443 --verbose

# Import endpoints from a v2rayN installation
purelink import v2rayn ~/v2rayN/

# Import from share link files
purelink import link ./subscription.txt

# Import from HTTP(S) subscription URLs
purelink import url "https://provider.example/subscription"

# Measure live download speed
purelink speedtest

# Export clean reachable endpoints after checks
purelink batch ./endpoints.txt --abuse --purity --export-clean clean.csv --export-format csv

# Export clean imported share links as a base64 subscription when raw links are preserved
purelink import link ./subscription.txt --abuse --export-clean clean.sub --export-format subscription

# Launch the interactive TUI after a batch run
purelink batch ./endpoints.txt --abuse --interactive

Commands

Global Flags

Batch Flags

Check Flags

Import Flags

The import v2rayn, import link, and import url commands share these flags:

Speedtest Flags

Export Formats

--export-clean writes only clean, reachable endpoints. The TUI can also export the currently visible list (e), split visible endpoints by region (r), split by protocol (p), or export clean endpoints (E).

Share-link and subscription exports only work when the import source preserved raw share links, such as import link, import url, pasted TUI subscriptions, and share-link backed v2rayN data. DB-only imports, WireGuard INI, SIP008 JSON, or any path using redacted non-interactive output may not have raw links; in that case PureLink returns no preserved share links available for export instead of emitting secrets accidentally.

Configuration

PureLink reads configuration from a YAML file or environment variables.

Config File

By default, PureLink looks for ~/.purelink.yaml in your home directory, then ./.purelink.yaml in the current directory. Override with --config.

# ~/.purelink.yaml
format: table
verbose: false
timeout: 10
workers: 8
no_color: false

providers:
  abuse:
    - blackbox
    - ipapi.is
    - iplogs
  purity:
    - ipapi.is
    - iplogs

Environment Variables

All config keys can be set via PURELINK_ prefixed environment variables:

Available Providers

Interactive TUI

Running purelink without a subcommand launches the interactive terminal UI by default. First-time users see an onboarding screen with import/check/report shortcuts, and batch --interactive opens the same Bubble Tea-powered UI after processing results.

TUI actions stream results progressively: batch checks emit each checked endpoint as it completes, imports emit one parsed endpoint at a time, check/report emit a single live result, and the cursor auto-follows the tail only while you are already near the bottom. Pressing q or ctrl+c cancels any active action before quitting.

Project Structure

PureLink/
├── cmd/purelink/              # Application entry point (Cobra commands)
├── internal/
│   ├── app/                   # Structured logging with sensitive data redaction
│   ├── checker/               # TCP/TLS/HTTP/DNS connectivity probes
│   ├── config/                # Viper-based configuration loading and validation
│   ├── engine/                # Batch worker pool, deduplication, aggregation, parsers, exports
│   ├── importer/              # v2rayN, share link file, and HTTP(S) subscription import orchestration
│   ├── output/                # Table/JSON/CSV/Markdown renderers + golden test data
│   ├── speedtest/             # Bounded live download speed measurements
│   └── tui/                   # Bubble Tea interactive terminal UI
├── pkg/
│   ├── abuse/                 # Provider interface, result merging, purity classification
│   │   └── providers/         # 9 provider implementations (blackbox, ipapi, iplogs, etc.)
│   ├── endpoint/              # Host:port parsing and normalization
│   ├── errors/                # Sentinel errors and validation types
│   ├── ip/                    # IP address classification utilities
│   └── v2rayn/                # Scanner, URI parser, SQLite reader, credential redactor
└── .github/
    ├── workflows/             # CI, release, and dependency review workflows
    └── ISSUE_TEMPLATE/        # Bug report and feature request templates

Development

Prerequisites

• Go 1.25.11+
• golangci-lint (for linting)
• goreleaser (for releases)

Common Commands

make build               # Build the binary to bin/
make test                # Run all tests with race detector and coverage
make lint                # Run golangci-lint
make fmt                 # Format all Go files
make coverage            # Generate coverage summary
make bench               # Run benchmarks
make fuzz                # Run fuzz smoke tests
make sec                 # Run gosec and govulncheck
make clean               # Remove build artifacts
make install             # Install to $GOPATH/bin
make deps                # Download and tidy dependencies

CI Pipeline

Every push and pull request runs:

1. Format check — gofmt verification
2. Lint — golangci-lint with 11 enabled linters
3. Vulnerability scan — govulncheck
4. Security scan — gosec
5. Unit tests — Race-enabled across Linux, macOS, and Windows
6. Coverage gate — Minimum 35% total coverage enforced
7. Static build — CGO-disabled binary verification
8. Dependency review — On all pull requests

Releases

Releases are automated via GoReleaser on every v* tag:

git tag v1.1.0
git push origin v1.1.0

This triggers a GitHub Actions workflow that verifies the build and tests, runs GoReleaser for cross-platform binaries/checksums/SBOMs, creates a draft GitHub release, and publishes the npm wrapper with the configured NPM_TOKEN secret.

License

MIT © MasuRii