clinkding

What this skill does

# 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 complet