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.