clinkding

# clinkding - Linkding Bookmark Manager CLI A modern Go-based CLI for managing bookmarks in [linkding](https://github.com/sissbruecker/linkding), a self-hosted bookmark manager. ## What This Does **Linkding** is a self-hosted bookmark manager (like Pocket, Instapaper). **clinkding** is the CLI that lets you manage your bookmarks from the terminal or via AI agents. Think of it as: - **Save for later** - Capture URLs you want to read - **Searchable library** - Full-text search across titles, descriptions, tags - **Organized collections** - Tag and bundle related bookmarks - **Personal archive** - Keep important links with notes and metadata ## Quick Start ### Initial Setup ```bash # Interactive configuration clinkding config init # Or manually configure clinkding config set url https://your-linkding-instance.com clinkding config set token YOUR_API_TOKEN # Test connection clinkding config test ``` ### Configuration File Location: `~/.config/clinkding/config.yaml` ```yaml url: https://linkding.example.com token: your-api-token-here defaults: bookmark_limit: 100 output_format: auto ``` ### Environment Variables ```bash export LINKDING_URL="https://linkding.example.com" export LINKDING_TOKEN="your-api-token-here" ``` ## Core Commands ### Bookmarks #### List & Search ```bash # List recent bookmarks clinkding bookmarks list # Search by keyword clinkding bookmarks list --query "golang tutorial" # Filter by tag clinkding bookmarks list --query "tag:programming" # Recent bookmarks (last 7 days) clinkding bookmarks list --added-since "7d" # Unread bookmarks clinkding bookmarks list --query "unread:yes" # JSON output for scripting clinkding bookmarks list --json # Plain text (tab-separated) clinkding bookmarks list --plain ``` #### Create Bookmarks ```bash # Simple bookmark clinkding bookmarks create https://go.dev # With metadata clinkding bookmarks create https://go.dev \ --title "Go Programming Language" \ --tags "golang,programming,reference" \ --description "Official Go website" \ --unread # Check if URL already exists before creating clinkding bookmarks check https://go.dev ``` #### Update Bookmarks ```bash # Update title clinkding bookmarks update 42 --title "New Title" # Add tags clinkding bookmarks update 42 --add-tags "important,work" # Remove tags clinkding bookmarks update 42 --remove-tags "old-tag" # Mark as read clinkding bookmarks update 42 --read # Update description clinkding bookmarks update 42 --description "Updated notes" ``` #### Get Bookmark Details ```bash # Full details clinkding bookmarks get 42 # JSON output clinkding bookmarks get 42 --json ``` #### Archive & Delete ```bash # Archive (hide from main list) clinkding bookmarks archive 42 # Unarchive clinkding bookmarks unarchive 42 # Delete permanently clinkding bookmarks delete 42 ``` ### Tags ```bash # List all tags clinkding tags list # Create a tag clinkding tags create "golang" # Get tag details clinkding tags get 1 # Plain text output clinkding tags list --plain ``` ### Bundles Bundles are collections of related bookmarks. ```bash # List bundles clinkding bundles list # Create a bundle clinkding bundles create "Go Resources" \ --description "Everything related to Go programming" # Update a bundle clinkding bundles update 1 --name "Go Lang Resources" # Get bundle details clinkding bundles get 1 # Delete a bundle clinkding bundles delete 1 ``` ### Assets Upload and manage file attachments for bookmarks. ```bash # List assets for a bookmark clinkding assets list 42 # Upload a file clinkding assets upload 42 ~/Documents/screenshot.png # Download an asset clinkding assets download 42 1 -o ./downloaded-file.png # Delete an asset clinkding assets delete 42 1 ``` ### User Profile ```bash # Get user profile info clinkding user profile ``` ## Agent Usage Patterns ### Save URL from Conversation ```bash # User: "Save this for later: https://example.com" clinkding bookmarks create https://example.com \ --title "Article Title" \ --description "Context from conversation" \ --tags "topic,context" ``` ### Search Bookmarks ```bash # User: "Find my golang bookmarks" clinkding bookmarks list --query "golang" # User: "Show me unread programming articles" clinkding bookmarks list --query "tag:programming unread:yes" # User: "What did I save last week?" clinkding bookmarks list --added-since "7d" ``` ### Organize & Tag ```bash # User: "Tag bookmark 42 as important" clinkding bookmarks update 42 --add-tags "important" # User: "Create a bundle for my AI research links" clinkding bundles create "AI Research" \ --description "Machine learning and AI papers" ``` ### Retrieve for Reading ```bash # User: "Give me something to read" clinkding bookmarks list --query "unread:yes" --limit 5 # User: "Show me my golang tutorials" clinkding bookmarks list --query "tag:golang tag:tutorial" ``` ## Output Formats ### Auto (Default) Human-friendly tables and colors for terminal display. ### JSON ```bash clinkding bookmarks list --json ``` Machine-readable for scripting and agent parsing. ### Plain Text ```bash clinkding bookmarks list --plain ``` Tab-separated values for pipe-friendly parsing. ## Relative Date Filtering Supports human-friendly time ranges: ```bash # Last 24 hours clinkding bookmarks list --added-since "24h" # Last 7 days clinkding bookmarks list --added-since "7d" # Last 6 months clinkding bookmarks list --modified-since "180d" ``` **Supported units:** `h` (hours), `d` (days), `y` (years) ## Common Workflows ### Morning Reading Routine ```bash # Check unread bookmarks clinkding bookmarks list --query "unread:yes" # Get top 5 most recent clinkding bookmarks list --limit 5 ``` ### Save from Clipboard ```bash # macOS pbpaste | xargs -I {} clinkding bookmarks create {} # Linux xclip -o | xargs -I {} clinkding bookmarks create {} ``` ### Batch Operations ```bash # Tag multiple bookmarks for id in 42 43 44; do clinkding bookmarks update $id --add-tags "important" done # Archive old unread bookmarks clinkding bookmarks list --query "unread:yes" --added-since "30d" --plain | \ while read id _; do clinkding bookmarks archive "$id" done ``` ### Backup Bookmarks ```bash # Export all bookmarks as JSON clinkding bookmarks list --json > bookmarks-backup-$(date +%Y%m%d).json # Export specific tag clinkding bookmarks list --query "tag:important" --json > important.json ``` ## Global Flags Available on all commands: | Flag | Description | |------|-------------| | `-c, --config <file>` | Config file path | | `-u, --url <url>` | Linkding instance URL | | `-t, --token <token>` | API token | | `--json` | Output as JSON | | `--plain` | Output as plain text | | `--no-color` | Disable colors | | `-q, --quiet` | Minimal output | | `-v, --verbose` | Verbose output | ## Exit Codes | Code | Meaning | |------|---------| | 0 | Success | | 1 | General error (API/network) | | 2 | Invalid usage (bad flags/args) | | 3 | Authentication error | | 4 | Not found | | 130 | Interrupted (Ctrl-C) | ## Troubleshooting ### Test Configuration ```bash # Verify settings clinkding config show # Test connection clinkding config test ``` ### Common Issues **Authentication Error:** - Verify API token in linkding web interface - Check URL includes protocol (`https://`) - Remove trailing slashes from URL **Command-Specific Help:** ```bash clinkding bookmarks --help clinkding bookmarks create --help ``` ## Links - **GitHub:** https://github.com/daveonkels/clinkding - **Linkding:** https://github.com/sissbruecker/linkding - **Homebrew:** `brew install daveonkels/tap/clinkding` ## Installation ### Homebrew (macOS/Linux) ```bash brew install daveonkels/tap/clinkding ``` ### Go Install ```bash go install github.com/daveonkels/clinkding@latest ``` ### Binary Download Download from [releases](https://github.com/daveonkels/clinkding/releases) for your platform. ## Shell Completion ```bash # Bash clinkding completion bash > /etc/bash_completion.d/clinkding # Zsh clinkding completion zsh > "${fpath[1]}/_clinkding" # Fish clinkding completion fish > ~/.config/fish/completions/clinkding.fish ``` --- **Built by:** [@daveonkels](https://github.com/daveonkels) **License:** MIT ## Agent Workflows for Smart Bookmark Creation ### Adding URLs with Automatic Metadata When a user says "Add this to linkding" or "Save this URL", follow this workflow: **1. Extract metadata from the URL** Use the `summarize` skill to get title and description: ```bash # Get page metadata summarize url https://example.com --format json ``` This returns structured data with: - Title - Description/summary - Main content **2. Infer appropriate tags from content** Map the content to **existing canonical tags only**. Do NOT create new tags. Use this canonical tag list (263 tags total): - **Tech:** webdev, design, programming, ai, cloud, devops, docker, linux, networking, security, privacy - **Content:** content, media, photography, video, audio, books, podcasting - **Business:** business, marketing, ecommerce, finance, career, productivity - **Home:** smart-home, home-assistant, esphome, iot, home-improvement - **Tools:** tools, cli, git, github, editor, reference, documentation - **Data:** data, analytics, mysql, nosql - **Communication:** communication, email, messaging, slack - **Education:** education, guide, howto, research, testing - **Locations:** texas, seattle, dallas (use sparingly) **Tag Selection Rules:** - Use 2-5 tags maximum - Choose the most specific applicable tags - If unsure, default to broader categories (e.g., `tools` over `generator`) - Check existing tags first: `clinkding tags list --plain | grep -i <keyword>` - Never create tags like: `awesome`, `cool`, `interesting`, `resources`, `tips` **3. Create the bookmark with metadata** ```bash clinkding bookmarks create "https://example.com" \ --title "Title from summarize" \ --description "Summary from summarize (1-2 sentences)" \ --tags "webdev,tools,reference" ``` ### Example Workflow **User:** "Save this to linkding: https://github.com/awesome/project" **Agent Actions:** ```bash # 1. Check if already bookmarked clinkding bookmarks check https://github.com/awesome/project # 2. Get metadata (use summarize skill) summarize url https://github.com/awesome/project --format json # 3. Analyze content and infer tags # From summary: "A CLI tool for Docker container management" # Canonical tags: docker, devops, cli, tools # 4. Create bookmark clinkding bookmarks create https://github.com/awesome/project \ --title "Awesome Project - Docker Container CLI" \ --description "Command-line tool for managing Docker containers with enhanced features" \ --tags "docker,devops,cli" ``` ### Tag Mapping Heuristics Use these rules to map content → canonical tags: | Content Type | Canonical Tags | |--------------|----------------| | Web development, HTML, CSS, JavaScript | `webdev`, `css`, `javascript` | | React, frameworks, frontend | `webdev`, `react` | | Design, UI/UX, mockups | `design` | | Python, Go, Ruby code | `programming`, `python`/`ruby` | | Docker, K8s, DevOps | `docker`, `devops`, `cloud` | | Home automation, ESP32, sensors | `smart-home`, `esphome`, `iot` | | AI, ML, LLMs | `ai`, `llm` | | Productivity tools, workflows | `productivity`, `tools` | | Finance, investing, crypto | `finance` | | Marketing, SEO, ads | `marketing` | | Shopping, deals, stores | `ecommerce` | | Tutorials, guides, docs | `guide`, `howto`, `documentation` | | Security, privacy, encryption | `security`, `privacy` | | Local (DFW/Seattle) | `texas`, `seattle` | ### Validation Before Creating Always run these checks: ```bash # 1. Does URL already exist? clinkding bookmarks check <url> # 2. Do the tags exist? clinkding tags list --plain | grep -iE "^(tag1|tag2|tag3)$" # 3. Are we using canonical tags? # Cross-reference against the 263 canonical tags # Never create new tags without explicit user request ``` ### User Requests to Save Multiple Links If user provides multiple URLs: ```bash # Process each URL separately with metadata extraction for url in url1 url2 url3; do # Get metadata # Infer tags # Create bookmark done ``` ### Updating Existing Bookmarks If user says "Update that bookmark" or "Add tags to my last save": ```bash # Get most recent bookmark recent_id=$(clinkding bookmarks list --limit 1 --plain | cut -f1) # Add tags (don't remove existing ones unless asked) clinkding bookmarks update $recent_id --add-tags "new-tag" # Update description clinkding bookmarks update $recent_id --description "Updated notes" ``` ### Key Principles 1. **Always fetch metadata** - Use `summarize` to get good titles/descriptions 2. **Use existing tags** - Never create new tags without checking canonical list 3. **Be selective** - 2-5 tags max, choose the most specific applicable 4. **Validate first** - Check for duplicates before creating 5. **Provide context** - Include brief description explaining why it's useful --- ## Current Canonical Tag Structure Dave's linkding instance has **263 canonical tags** after consolidation from 17,189 duplicates. Top categories (by bookmark count): - `pinboard` (4,987) - Legacy import tag - `ifttt` (2,639) - Legacy import tag - `webdev` (1,679) - Web development - `design` (561) - Design/UI/UX - `content` (416) - Content/writing - `cloud` (383) - Cloud/hosting/SaaS - `business` (364) - Business/strategy - `ecommerce` (308) - Shopping/marketplace - `smart-home` (295) - Home automation - `productivity` (291) - Productivity tools **Golden Rule:** When in doubt, use broader existing tags rather than creating new specific ones.