LinkCovery - Modern Bookmark Management CLI

LinkCovery is a modern, fast, and intuitive bookmark management tool built with Python. It provides a beautiful command-line interface that makes managing, searching, and organizing your links effortless.

🤔 Why LinkCovery?

Browser bookmarks quickly become cluttered and inefficient. LinkCovery helps you intelligently manage and organize your links from the terminal—the place where you, as a developer, spend most of your time. With powerful search capabilities, tagging systems, and data portability, LinkCovery transforms how you interact with your saved links, making them truly useful rather than just saved.

✨ Features

🚀 Core Functionality

• Smart Link Management: Add, edit, delete, and organize links with ease
• Powerful Search: Search by URL, description, tags, domain, or read status
• Data Portability: Import and export your bookmarks in JSON format
• Read Tracking: Keep track of which links you've read
• Rich Statistics: Get insights into your bookmark collection

🏗️ Technical Excellence

• Modern Architecture: Clean separation of concerns with service layers
• Type Safety: Full Pydantic validation and type hints throughout
• Error Handling: Comprehensive error handling with helpful messages
• Beautiful UI: Rich terminal interface with tables and colors
• Configuration: Flexible configuration system with file-based storage
• Cross-Platform: Works seamlessly on macOS, Linux, and Windows

📦 Installation

Prerequisites

• Python 3.13 or higher
• uv package manager (recommended)

Install from Source

git clone https://github.com/arian24b/linkcovery.git
cd linkcovery
uv sync

Install as Package

uv add linkcovery

🎯 Quick Start

Add Your First Link

uv run python main.py links add "https://github.com/arian24b/linkcovery" \
  --desc "LinkCovery GitHub Repository" \
  --tag "github,project"

List Your Links

uv run python main.py links list

Search Your Bookmarks

# Search by keyword
uv run python main.py links search github

# Search by domain
uv run python main.py links search --domain github.com

# Search by tag
uv run python main.py links search --tag project

Export Your Data

uv run python main.py data export my-bookmarks.json

Import Bookmarks

uv run python main.py data import my-bookmarks.json

� CLI Reference

Link Management (links)

• links add <url> - Add a new bookmark
  • --desc, -d - Description for the link
  • --tag, -t - Tag to categorize the link
  • --read, -r - Mark as already read
• links list - List all bookmarks
  • --limit, -l - Maximum number of links to show
  • --read-only - Show only read links
  • --unread-only - Show only unread links
• links search [query] - Search bookmarks
  • --domain - Filter by domain
  • --tag, -t - Filter by tag
  • --read-only - Show only read links
  • --unread-only - Show only unread links
  • --limit, -l - Maximum results
• links show <id> - Show detailed link information
• links edit <id> - Edit an existing link
  • --url - New URL
  • --desc, -d - New description
  • --tag, -t - New tag
  • --read - Mark as read
  • --unread - Mark as unread
• links delete <id> - Delete a link
  • --force, -f - Skip confirmation
• links mark-read <id> - Mark a link as read
• links mark-unread <id> - Mark a link as unread

Data Management (data)

• data export <file> - Export links to JSON
  • --force, -f - Overwrite existing file
• data import <file> - Import links from JSON

Configuration (config)

• config show - Show current configuration
• config get <key> - Get a specific configuration value
• config set <key> <value> - Set a configuration value
• config reset - Reset to default configuration

General Commands

• stats - Show bookmark statistics
• version - Show version information

⚙️ Configuration

LinkCovery stores its configuration in your system's config directory:

• macOS: ~/Library/Application Support/linkcovery/config.json
• Linux: ~/.config/linkcovery/config.json
• Windows: %APPDATA%/linkcovery/config.json

Available Settings

Setting	Default	Description
app_name	"LinkCovery"	Application name
version	"1.0.0"	Application version
database_path	(auto-detected)	Custom database path
default_export_format	"json"	Default export format
max_search_results	50	Maximum search results
allowed_extensions	[".json"]	Allowed file extensions
debug	false	Enable debug mode

Examples

# Set maximum search results
uv run python main.py config set max_search_results 100

# Enable debug mode
uv run python main.py config set debug true

# View all settings
uv run python main.py config show

🗄️ Database

LinkCovery uses SQLite for data storage. The database is automatically created in your system's data directory:

• macOS: ~/Library/Application Support/linkcovery/links.db
• Linux: ~/.local/share/linkcovery/links.db
• Windows: %APPDATA%/linkcovery/links.db

Database Schema

The links table contains:

• id - Unique identifier (primary key)
• url - The bookmark URL (unique, required)
• domain - Extracted domain name (required)
• description - Optional description text
• tag - Associated tag for categorization
• is_read - Boolean read status
• created_at - ISO timestamp of creation
• updated_at - ISO timestamp of last update

🏗️ Project Structure

linkcovery/
├── main.py                         # Application entry point
├── linkcovery/
│   ├── cli/                        # Command-line interface
│   │   ├── __init__.py            # Main CLI app and routing
│   │   ├── links.py               # Link management commands
│   │   ├── config.py              # Configuration commands
│   │   ├── data.py                # Import/export commands
│   │   └── utils.py               # CLI utilities and decorators
│   ├── core/                      # Core business logic
│   │   ├── config.py              # Configuration management
│   │   ├── database.py            # Database service layer
│   │   ├── exceptions.py          # Custom exception classes
│   │   ├── models.py              # Pydantic and SQLAlchemy models
│   │   └── utils.py               # Core utility functions
│   └── services/                  # Business logic services
│       ├── link_service.py        # Link management business logic
│       └── data_service.py # Import/export operations
├── pyproject.toml                 # Project configuration
└── README.md                      # This file

🧪 Development

Setup Development Environment

# Clone the repository
git clone https://github.com/arian24b/linkcovery.git
cd linkcovery

# Install with development dependencies
uv sync --all-groups

# Install pre-commit hooks (if available)
uv run pre-commit install

Running Tests

# Run all tests
uv run pytest

# Run with coverage
uv run pytest --cov=linkcovery --cov-report=html

Code Quality

# Run linting
uv run ruff check

# Format code
uv run ruff format

# Type checking
uv run mypy linkcovery

Building

# Build binary
uv run python build_binary.py

� Examples

Managing Links

# Add a link with description and tags
uv run python main.py links add "https://docs.python.org" \
  --desc "Official Python Documentation" \
  --tag "python,docs,reference"

# List only unread links
uv run python main.py links list --unread-only --limit 10

# Search for Python-related links
uv run python main.py links search python

# Mark a link as read
uv run python main.py links mark-read 5

# Edit a link's description
uv run python main.py links edit 5 --desc "Updated description"

Data Management

# Export all links
uv run python main.py data export my-bookmarks-$(date +%Y%m%d).json

# Import from another file
uv run python main.py data import bookmarks-backup.json

# View statistics
uv run python main.py stats

Configuration

# Increase search result limit
uv run python main.py config set max_search_results 100

# View current configuration
uv run python main.py config show

# Reset to defaults
uv run python main.py config reset

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Make your changes following the project's coding standards
4. Run tests and linting (uv run pytest && uv run ruff check)
5. Commit your changes (git commit -m 'Add some amazing feature')
6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull Request

📝 License

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

🙏 Acknowledgments

• Built with Typer for the CLI framework
• Rich for beautiful terminal output
• SQLAlchemy for database operations
• Pydantic for data validation and settings
• platformdirs for cross-platform paths

---

LinkCovery - Because your bookmarks deserve better organization! 🔗✨