Karakeepe - Karakeep/Hoarder CLI Client#

A command-line client for managing bookmarks in Karakeep (Hoarder).

Features#

• 🔖 List, search, and manage bookmarks
• 🔐 Secure credential storage using keyeio
• 📁 Multiple profile support (default, production, staging, etc.)
• 🎯 Tag-based filtering and search
• ⭐ Support for favourites and archived bookmarks
• 📝 Add notes and titles to bookmarks

Installation#

opam install karakeepe

Configuration#

Create a configuration file at ~/.config/karakeepe/keys/karakeepe.toml:

[default]
api_key = "ak1_<key_id>_<secret>"
base_url = "https://hoard.example.com"

[production]
api_key = "ak1_<prod_key_id>_<prod_secret>"
base_url = "https://hoard.prod.example.com"

Getting an API Key#

1. Log in to your Karakeep instance
2. Navigate to Settings → API Keys
3. Create a new API key
4. Copy the key (format: ak1_<key_id>_<secret>)

Usage#

List Bookmarks#

# List all bookmarks
karakeepe list

# List with limit
karakeepe list --limit 10

# List only archived bookmarks
karakeepe list --archived true

# List only favourited bookmarks
karakeepe list --favourited true

# Filter by tags
karakeepe list --tags "work,important"

# Use production profile
karakeepe list --profile production

Get a Single Bookmark#

# Get bookmark by ID
karakeepe get <bookmark-id>

# Example
karakeepe get "clx7y8z9a0001..."

Create a Bookmark#

# Create a simple bookmark
karakeepe create "https://example.com"

# Create with title
karakeepe create "https://example.com" --title "Example Site"

# Create with title and tags
karakeepe create "https://example.com" \
  --title "Example Site" \
  --tags "web,example,reference"

# Create with note
karakeepe create "https://example.com" \
  --title "Example" \
  --note "Useful reference for web development"

# Create as favourited
karakeepe create "https://example.com" --favourited

# Create as archived
karakeepe create "https://example.com" --archived

Search Bookmarks#

# Search by single tag
karakeepe search --tags work

# Search by multiple tags
karakeepe search --tags "work,important"

# Limit search results
karakeepe search --tags work --limit 5

Command Reference#

Global Options#

• --profile NAME - Select profile to use (default: "default")
• --key-file FILE - Override with direct TOML file path
• --url URL - Override base URL from profile
• --help - Show help for command

Commands#

karakeepe list [OPTIONS]#

List bookmarks with optional filtering.

Options:

• -l, --limit NUM - Maximum number of bookmarks to fetch (default: 50)
• -a, --archived BOOL - Filter by archived status (true/false)
• -f, --favourited BOOL - Filter by favourited status (true/false)
• -t, --tags TAGS - Filter by tags (comma-separated)

karakeepe get ID#

Get detailed information for a single bookmark.

Arguments:

• ID - Bookmark ID (required)

karakeepe create URL [OPTIONS]#

Create a new bookmark.

Arguments:

• URL - URL to bookmark (required)

Options:

• --title TITLE - Bookmark title
• -n, --note NOTE - Bookmark note/description
• -t, --tags TAGS - Tags to add (comma-separated)
• -a, --archived - Mark as archived
• -f, --favourited - Mark as favourited

karakeepe search --tags TAGS [OPTIONS]#

Search bookmarks by tags.

Options:

• -t, --tags TAGS - Tags to search for (comma-separated, required)
• -l, --limit NUM - Maximum number of results (default: 50)

Examples#

Daily Workflow#

# Add a bookmark you found
karakeepe create "https://blog.example.com/article" \
  --title "Great Article on OCaml" \
  --tags "ocaml,programming,blog"

# List your work bookmarks
karakeepe list --tags work

# Search for OCaml resources
karakeepe search --tags ocaml

# Get details of a specific bookmark
karakeepe get clx7y8z9a0001...

# Mark something as favourited
karakeepe create "https://important.example.com" --favourited

Multiple Profiles#

# Use default profile (personal instance)
karakeepe list

# Use work profile
karakeepe list --profile work

# Use custom file
karakeepe list --key-file ~/my-keys.toml --profile custom

Profile Setup Examples#

Personal Setup#

~/.config/karakeepe/keys/karakeepe.toml:

[default]
api_key = "ak1_abc123..."
base_url = "https://hoard.example.com"

Work Setup#

~/.config/karakeepe/keys/karakeepe.toml:

[default]
api_key = "ak1_personal_key..."
base_url = "https://hoard.personal.com"

[work]
api_key = "ak1_work_key..."
base_url = "https://hoard.company.com"

Library Usage#

The karakeepe library can also be used programmatically in OCaml applications:

let () =
  Eio_main.run @@ fun env ->
  Eio.Switch.run @@ fun sw ->

  let api_key = "ak1_..." in
  let base_url = "https://hoard.example.com" in

  (* Fetch all bookmarks *)
  let bookmarks = Karakeepe.fetch_all_bookmarks
    ~sw ~env ~api_key base_url in

  (* Create a bookmark *)
  let bookmark = Karakeepe.create_bookmark
    ~sw ~env ~api_key
    ~url:"https://example.com"
    ~title:"Example"
    ~tags:["web"; "example"]
    base_url in

  Printf.printf "Created bookmark: %s\n" bookmark.id

See the library documentation for full API reference.

Troubleshooting#

"Service file not found: karakeepe.toml"#

Create the configuration file at ~/.config/karakeepe/keys/karakeepe.toml with your API key.

"HTTP error: 401"#

Your API key is invalid or expired. Generate a new one from your Karakeep instance.

"HTTP error: 404"#

The bookmark ID doesn't exist or the base URL is incorrect.

See Also#

• Hoarder - The Karakeep/Hoarder bookmark manager
• keyeio - Secure API key storage
• xdge - XDG Base Directory Specification for Eio

License#

ISC License