My agentic slop goes here. Not intended for anyone else!
anil.recoil.org
1# Karakeepe - Karakeep/Hoarder CLI Client
2
3A command-line client for managing bookmarks in [Karakeep (Hoarder)](https://github.com/hoarder-app/hoarder).
4
5## Features
6
7- 🔖 List, search, and manage bookmarks
8- 🔐 Secure credential storage using [keyeio](../keyeio)
9- 📁 Multiple profile support (default, production, staging, etc.)
10- 🎯 Tag-based filtering and search
11- ⭐ Support for favourites and archived bookmarks
12- 📝 Add notes and titles to bookmarks
13
14## Installation
15
16```bash
17opam install karakeepe
18```
19
20## Configuration
21
22Create a configuration file at `~/.config/karakeepe/keys/karakeepe.toml`:
23
24```toml
25[default]
26api_key = "ak1_<key_id>_<secret>"
27base_url = "https://hoard.example.com"
28
29[production]
30api_key = "ak1_<prod_key_id>_<prod_secret>"
31base_url = "https://hoard.prod.example.com"
32```
33
34### Getting an API Key
35
361. Log in to your Karakeep instance
372. Navigate to Settings → API Keys
383. Create a new API key
394. Copy the key (format: `ak1_<key_id>_<secret>`)
40
41## Usage
42
43### List Bookmarks
44
45```bash
46# List all bookmarks
47karakeepe list
48
49# List with limit
50karakeepe list --limit 10
51
52# List only archived bookmarks
53karakeepe list --archived true
54
55# List only favourited bookmarks
56karakeepe list --favourited true
57
58# Filter by tags
59karakeepe list --tags "work,important"
60
61# Use production profile
62karakeepe list --profile production
63```
64
65### Get a Single Bookmark
66
67```bash
68# Get bookmark by ID
69karakeepe get <bookmark-id>
70
71# Example
72karakeepe get "clx7y8z9a0001..."
73```
74
75### Create a Bookmark
76
77```bash
78# Create a simple bookmark
79karakeepe create "https://example.com"
80
81# Create with title
82karakeepe create "https://example.com" --title "Example Site"
83
84# Create with title and tags
85karakeepe create "https://example.com" \
86 --title "Example Site" \
87 --tags "web,example,reference"
88
89# Create with note
90karakeepe create "https://example.com" \
91 --title "Example" \
92 --note "Useful reference for web development"
93
94# Create as favourited
95karakeepe create "https://example.com" --favourited
96
97# Create as archived
98karakeepe create "https://example.com" --archived
99```
100
101### Search Bookmarks
102
103```bash
104# Search by single tag
105karakeepe search --tags work
106
107# Search by multiple tags
108karakeepe search --tags "work,important"
109
110# Limit search results
111karakeepe search --tags work --limit 5
112```
113
114## Command Reference
115
116### Global Options
117
118- `--profile NAME` - Select profile to use (default: "default")
119- `--key-file FILE` - Override with direct TOML file path
120- `--url URL` - Override base URL from profile
121- `--help` - Show help for command
122
123### Commands
124
125#### `karakeepe list [OPTIONS]`
126
127List bookmarks with optional filtering.
128
129**Options:**
130- `-l, --limit NUM` - Maximum number of bookmarks to fetch (default: 50)
131- `-a, --archived BOOL` - Filter by archived status (true/false)
132- `-f, --favourited BOOL` - Filter by favourited status (true/false)
133- `-t, --tags TAGS` - Filter by tags (comma-separated)
134
135#### `karakeepe get ID`
136
137Get detailed information for a single bookmark.
138
139**Arguments:**
140- `ID` - Bookmark ID (required)
141
142#### `karakeepe create URL [OPTIONS]`
143
144Create a new bookmark.
145
146**Arguments:**
147- `URL` - URL to bookmark (required)
148
149**Options:**
150- `--title TITLE` - Bookmark title
151- `-n, --note NOTE` - Bookmark note/description
152- `-t, --tags TAGS` - Tags to add (comma-separated)
153- `-a, --archived` - Mark as archived
154- `-f, --favourited` - Mark as favourited
155
156#### `karakeepe search --tags TAGS [OPTIONS]`
157
158Search bookmarks by tags.
159
160**Options:**
161- `-t, --tags TAGS` - Tags to search for (comma-separated, required)
162- `-l, --limit NUM` - Maximum number of results (default: 50)
163
164## Examples
165
166### Daily Workflow
167
168```bash
169# Add a bookmark you found
170karakeepe create "https://blog.example.com/article" \
171 --title "Great Article on OCaml" \
172 --tags "ocaml,programming,blog"
173
174# List your work bookmarks
175karakeepe list --tags work
176
177# Search for OCaml resources
178karakeepe search --tags ocaml
179
180# Get details of a specific bookmark
181karakeepe get clx7y8z9a0001...
182
183# Mark something as favourited
184karakeepe create "https://important.example.com" --favourited
185```
186
187### Multiple Profiles
188
189```bash
190# Use default profile (personal instance)
191karakeepe list
192
193# Use work profile
194karakeepe list --profile work
195
196# Use custom file
197karakeepe list --key-file ~/my-keys.toml --profile custom
198```
199
200## Profile Setup Examples
201
202### Personal Setup
203
204`~/.config/karakeepe/keys/karakeepe.toml`:
205```toml
206[default]
207api_key = "ak1_abc123..."
208base_url = "https://hoard.example.com"
209```
210
211### Work Setup
212
213`~/.config/karakeepe/keys/karakeepe.toml`:
214```toml
215[default]
216api_key = "ak1_personal_key..."
217base_url = "https://hoard.personal.com"
218
219[work]
220api_key = "ak1_work_key..."
221base_url = "https://hoard.company.com"
222```
223
224## Library Usage
225
226The `karakeepe` library can also be used programmatically in OCaml applications:
227
228```ocaml
229let () =
230 Eio_main.run @@ fun env ->
231 Eio.Switch.run @@ fun sw ->
232
233 let api_key = "ak1_..." in
234 let base_url = "https://hoard.example.com" in
235
236 (* Fetch all bookmarks *)
237 let bookmarks = Karakeepe.fetch_all_bookmarks
238 ~sw ~env ~api_key base_url in
239
240 (* Create a bookmark *)
241 let bookmark = Karakeepe.create_bookmark
242 ~sw ~env ~api_key
243 ~url:"https://example.com"
244 ~title:"Example"
245 ~tags:["web"; "example"]
246 base_url in
247
248 Printf.printf "Created bookmark: %s\n" bookmark.id
249```
250
251See the [library documentation](karakeepe.mli) for full API reference.
252
253## Troubleshooting
254
255### "Service file not found: karakeepe.toml"
256
257Create the configuration file at `~/.config/karakeepe/keys/karakeepe.toml` with your API key.
258
259### "HTTP error: 401"
260
261Your API key is invalid or expired. Generate a new one from your Karakeep instance.
262
263### "HTTP error: 404"
264
265The bookmark ID doesn't exist or the base URL is incorrect.
266
267## See Also
268
269- [Hoarder](https://github.com/hoarder-app/hoarder) - The Karakeep/Hoarder bookmark manager
270- [keyeio](../keyeio) - Secure API key storage
271- [xdge](../xdge) - XDG Base Directory Specification for Eio
272
273## License
274
275ISC License