anil.recoil.org
OCaml CLI and library to the Karakeep bookmarking app
Refactor and tidy code for release
- Factor out query parameter building with add_param/add_opt/add_int/add_bool helpers
- Simplify tag_ref conversion with tag_ref_of_poly helper
- Replace manual JSON printing with jsont codecs for proper encoding
- Use proper Eio error handling for JSON encoding errors
- Update dune-project with proper metadata (homepage, bug-reports)
- Clean up dune file formatting
- Add license headers to test files
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
+16
bin/dune
+16
bin/dune
+636
bin/main.ml
+636
bin/main.ml
···
1
+
open Cmdliner
2
+
open Karakeep_cmd
3
+
4
+
(* Bookmark commands *)
5
+
6
+
let list_bookmarks_cmd =
7
+
let run config fmt () limit cursor archived favourited include_content =
8
+
handle_errors (fun () ->
9
+
with_client config (fun client ->
10
+
let result =
11
+
Karakeep.fetch_bookmarks client ?limit ?cursor ~include_content
12
+
?archived ?favourited ()
13
+
in
14
+
print_bookmarks fmt result.bookmarks;
15
+
Option.iter
16
+
(fun c -> Logs.info (fun m -> m "Next cursor: %s" c))
17
+
result.next_cursor);
18
+
0)
19
+
in
20
+
let doc = "List bookmarks with optional filters." in
21
+
let info = Cmd.info "list" ~doc in
22
+
Cmd.v info
23
+
Term.(
24
+
const run $ config_term $ output_format_term $ setup_logging $ limit_term
25
+
$ cursor_term $ archived_term $ favourited_term $ include_content_term)
26
+
27
+
let list_all_bookmarks_cmd =
28
+
let run config fmt () archived favourited =
29
+
handle_errors (fun () ->
30
+
with_client config (fun client ->
31
+
let bookmarks =
32
+
Karakeep.fetch_all_bookmarks client ?archived ?favourited ()
33
+
in
34
+
print_bookmarks fmt bookmarks);
35
+
0)
36
+
in
37
+
let doc = "List all bookmarks (handles pagination automatically)." in
38
+
let info = Cmd.info "list-all" ~doc in
39
+
Cmd.v info
40
+
Term.(
41
+
const run $ config_term $ output_format_term $ setup_logging
42
+
$ archived_term $ favourited_term)
43
+
44
+
let get_bookmark_cmd =
45
+
let run config fmt () bookmark_id =
46
+
handle_errors (fun () ->
47
+
with_client config (fun client ->
48
+
let bookmark = Karakeep.fetch_bookmark_details client bookmark_id in
49
+
print_bookmark fmt bookmark);
50
+
0)
51
+
in
52
+
let doc = "Get details of a specific bookmark." in
53
+
let info = Cmd.info "get" ~doc in
54
+
Cmd.v info
55
+
Term.(const run $ config_term $ output_format_term $ setup_logging $ bookmark_id_term)
56
+
57
+
let create_bookmark_cmd =
58
+
let run config fmt () url title note summary tags favourited archived =
59
+
handle_errors (fun () ->
60
+
with_client config (fun client ->
61
+
let tags = if tags = [] then None else Some tags in
62
+
let bookmark =
63
+
Karakeep.create_bookmark client ~url ?title ?note ?summary ?tags
64
+
?favourited ?archived ()
65
+
in
66
+
print_bookmark fmt bookmark);
67
+
0)
68
+
in
69
+
let doc = "Create a new bookmark." in
70
+
let info = Cmd.info "create" ~doc in
71
+
let fav_term =
72
+
Arg.(value & flag & info [ "fav"; "favourited" ] ~doc:"Mark as favourite.")
73
+
in
74
+
let arch_term =
75
+
Arg.(value & flag & info [ "archive"; "archived" ] ~doc:"Mark as archived.")
76
+
in
77
+
let fav_opt = Term.(const (fun b -> if b then Some true else None) $ fav_term) in
78
+
let arch_opt = Term.(const (fun b -> if b then Some true else None) $ arch_term) in
79
+
Cmd.v info
80
+
Term.(
81
+
const run $ config_term $ output_format_term $ setup_logging $ url_term
82
+
$ title_term $ note_term $ summary_term $ tags_term $ fav_opt $ arch_opt)
83
+
84
+
let update_bookmark_cmd =
85
+
let run config fmt () bookmark_id title note summary =
86
+
handle_errors (fun () ->
87
+
with_client config (fun client ->
88
+
let bookmark =
89
+
Karakeep.update_bookmark client bookmark_id ?title ?note ?summary ()
90
+
in
91
+
print_bookmark fmt bookmark);
92
+
0)
93
+
in
94
+
let doc = "Update a bookmark." in
95
+
let info = Cmd.info "update" ~doc in
96
+
Cmd.v info
97
+
Term.(
98
+
const run $ config_term $ output_format_term $ setup_logging
99
+
$ bookmark_id_term $ title_term $ note_term $ summary_term)
100
+
101
+
let delete_bookmark_cmd =
102
+
let run config () bookmark_id =
103
+
handle_errors (fun () ->
104
+
with_client config (fun client ->
105
+
Karakeep.delete_bookmark client bookmark_id;
106
+
Logs.app (fun m -> m "Deleted bookmark %s" bookmark_id));
107
+
0)
108
+
in
109
+
let doc = "Delete a bookmark." in
110
+
let info = Cmd.info "delete" ~doc in
111
+
Cmd.v info Term.(const run $ config_term $ setup_logging $ bookmark_id_term)
112
+
113
+
let archive_bookmark_cmd =
114
+
let run config fmt () bookmark_id =
115
+
handle_errors (fun () ->
116
+
with_client config (fun client ->
117
+
let bookmark =
118
+
Karakeep.update_bookmark client bookmark_id ~archived:true ()
119
+
in
120
+
print_bookmark fmt bookmark);
121
+
0)
122
+
in
123
+
let doc = "Archive a bookmark." in
124
+
let info = Cmd.info "archive" ~doc in
125
+
Cmd.v info
126
+
Term.(const run $ config_term $ output_format_term $ setup_logging $ bookmark_id_term)
127
+
128
+
let unarchive_bookmark_cmd =
129
+
let run config fmt () bookmark_id =
130
+
handle_errors (fun () ->
131
+
with_client config (fun client ->
132
+
let bookmark =
133
+
Karakeep.update_bookmark client bookmark_id ~archived:false ()
134
+
in
135
+
print_bookmark fmt bookmark);
136
+
0)
137
+
in
138
+
let doc = "Unarchive a bookmark." in
139
+
let info = Cmd.info "unarchive" ~doc in
140
+
Cmd.v info
141
+
Term.(const run $ config_term $ output_format_term $ setup_logging $ bookmark_id_term)
142
+
143
+
let favourite_bookmark_cmd =
144
+
let run config fmt () bookmark_id =
145
+
handle_errors (fun () ->
146
+
with_client config (fun client ->
147
+
let bookmark =
148
+
Karakeep.update_bookmark client bookmark_id ~favourited:true ()
149
+
in
150
+
print_bookmark fmt bookmark);
151
+
0)
152
+
in
153
+
let doc = "Mark a bookmark as favourite." in
154
+
let info = Cmd.info "fav" ~doc in
155
+
Cmd.v info
156
+
Term.(const run $ config_term $ output_format_term $ setup_logging $ bookmark_id_term)
157
+
158
+
let unfavourite_bookmark_cmd =
159
+
let run config fmt () bookmark_id =
160
+
handle_errors (fun () ->
161
+
with_client config (fun client ->
162
+
let bookmark =
163
+
Karakeep.update_bookmark client bookmark_id ~favourited:false ()
164
+
in
165
+
print_bookmark fmt bookmark);
166
+
0)
167
+
in
168
+
let doc = "Remove favourite mark from a bookmark." in
169
+
let info = Cmd.info "unfav" ~doc in
170
+
Cmd.v info
171
+
Term.(const run $ config_term $ output_format_term $ setup_logging $ bookmark_id_term)
172
+
173
+
let summarize_bookmark_cmd =
174
+
let run config fmt () bookmark_id =
175
+
handle_errors (fun () ->
176
+
with_client config (fun client ->
177
+
let response = Karakeep.summarize_bookmark client bookmark_id in
178
+
match fmt with
179
+
| Text -> print_endline response.summary
180
+
| Json ->
181
+
let json = Jsont_bytesrw.encode_string Karakeep.summarize_response_jsont response in
182
+
(match json with
183
+
| Ok s -> print_endline s
184
+
| Error e -> Logs.err (fun m -> m "JSON encoding error: %s" e))
185
+
| Quiet -> print_endline response.summary);
186
+
0)
187
+
in
188
+
let doc = "Generate an AI summary for a bookmark." in
189
+
let info = Cmd.info "summarize" ~doc in
190
+
Cmd.v info
191
+
Term.(const run $ config_term $ output_format_term $ setup_logging $ bookmark_id_term)
192
+
193
+
let search_bookmarks_cmd =
194
+
let run config fmt () query limit cursor =
195
+
handle_errors (fun () ->
196
+
with_client config (fun client ->
197
+
let result =
198
+
Karakeep.search_bookmarks client ~query ?limit ?cursor ()
199
+
in
200
+
print_bookmarks fmt result.bookmarks;
201
+
Option.iter
202
+
(fun c -> Logs.info (fun m -> m "Next cursor: %s" c))
203
+
result.next_cursor);
204
+
0)
205
+
in
206
+
let doc = "Search bookmarks." in
207
+
let info = Cmd.info "search" ~doc in
208
+
Cmd.v info
209
+
Term.(
210
+
const run $ config_term $ output_format_term $ setup_logging
211
+
$ search_query_term $ limit_term $ cursor_term)
212
+
213
+
let bookmarks_cmd =
214
+
let doc = "Bookmark operations." in
215
+
let info = Cmd.info "bookmarks" ~doc in
216
+
Cmd.group info
217
+
[
218
+
list_bookmarks_cmd;
219
+
list_all_bookmarks_cmd;
220
+
get_bookmark_cmd;
221
+
create_bookmark_cmd;
222
+
update_bookmark_cmd;
223
+
delete_bookmark_cmd;
224
+
archive_bookmark_cmd;
225
+
unarchive_bookmark_cmd;
226
+
favourite_bookmark_cmd;
227
+
unfavourite_bookmark_cmd;
228
+
summarize_bookmark_cmd;
229
+
search_bookmarks_cmd;
230
+
]
231
+
232
+
(* Tag commands *)
233
+
234
+
let list_tags_cmd =
235
+
let run config fmt () =
236
+
handle_errors (fun () ->
237
+
with_client config (fun client ->
238
+
let tags = Karakeep.fetch_all_tags client in
239
+
print_tags fmt tags);
240
+
0)
241
+
in
242
+
let doc = "List all tags." in
243
+
let info = Cmd.info "list" ~doc in
244
+
Cmd.v info Term.(const run $ config_term $ output_format_term $ setup_logging)
245
+
246
+
let get_tag_cmd =
247
+
let run config fmt () tag_id =
248
+
handle_errors (fun () ->
249
+
with_client config (fun client ->
250
+
let tag = Karakeep.fetch_tag_details client tag_id in
251
+
print_tag fmt tag);
252
+
0)
253
+
in
254
+
let doc = "Get details of a specific tag." in
255
+
let info = Cmd.info "get" ~doc in
256
+
Cmd.v info
257
+
Term.(const run $ config_term $ output_format_term $ setup_logging $ tag_id_term)
258
+
259
+
let tag_bookmarks_cmd =
260
+
let run config fmt () tag_id limit cursor =
261
+
handle_errors (fun () ->
262
+
with_client config (fun client ->
263
+
let result =
264
+
Karakeep.fetch_bookmarks_with_tag client ?limit ?cursor tag_id
265
+
in
266
+
print_bookmarks fmt result.bookmarks);
267
+
0)
268
+
in
269
+
let doc = "List bookmarks with a specific tag." in
270
+
let info = Cmd.info "bookmarks" ~doc in
271
+
Cmd.v info
272
+
Term.(
273
+
const run $ config_term $ output_format_term $ setup_logging $ tag_id_term
274
+
$ limit_term $ cursor_term)
275
+
276
+
let rename_tag_cmd =
277
+
let run config fmt () tag_id name =
278
+
handle_errors (fun () ->
279
+
with_client config (fun client ->
280
+
let tag = Karakeep.update_tag client ~name tag_id in
281
+
print_tag fmt tag);
282
+
0)
283
+
in
284
+
let doc = "Rename a tag." in
285
+
let info = Cmd.info "rename" ~doc in
286
+
Cmd.v info
287
+
Term.(
288
+
const run $ config_term $ output_format_term $ setup_logging $ tag_id_term
289
+
$ name_term)
290
+
291
+
let delete_tag_cmd =
292
+
let run config () tag_id =
293
+
handle_errors (fun () ->
294
+
with_client config (fun client ->
295
+
Karakeep.delete_tag client tag_id;
296
+
Logs.app (fun m -> m "Deleted tag %s" tag_id));
297
+
0)
298
+
in
299
+
let doc = "Delete a tag." in
300
+
let info = Cmd.info "delete" ~doc in
301
+
Cmd.v info Term.(const run $ config_term $ setup_logging $ tag_id_term)
302
+
303
+
let attach_tags_cmd =
304
+
let run config () bookmark_id tags =
305
+
handle_errors (fun () ->
306
+
with_client config (fun client ->
307
+
let tag_refs = List.map (fun t -> `TagName t) tags in
308
+
let _ = Karakeep.attach_tags client ~tag_refs bookmark_id in
309
+
Logs.app (fun m ->
310
+
m "Attached %d tags to bookmark %s" (List.length tags) bookmark_id));
311
+
0)
312
+
in
313
+
let doc = "Attach tags to a bookmark." in
314
+
let info = Cmd.info "attach" ~doc in
315
+
Cmd.v info
316
+
Term.(const run $ config_term $ setup_logging $ bookmark_id_term $ tags_term)
317
+
318
+
let detach_tags_cmd =
319
+
let run config () bookmark_id tags =
320
+
handle_errors (fun () ->
321
+
with_client config (fun client ->
322
+
let tag_refs = List.map (fun t -> `TagName t) tags in
323
+
let _ = Karakeep.detach_tags client ~tag_refs bookmark_id in
324
+
Logs.app (fun m ->
325
+
m "Detached %d tags from bookmark %s" (List.length tags) bookmark_id));
326
+
0)
327
+
in
328
+
let doc = "Detach tags from a bookmark." in
329
+
let info = Cmd.info "detach" ~doc in
330
+
Cmd.v info
331
+
Term.(const run $ config_term $ setup_logging $ bookmark_id_term $ tags_term)
332
+
333
+
let tags_cmd =
334
+
let doc = "Tag operations." in
335
+
let info = Cmd.info "tags" ~doc in
336
+
Cmd.group info
337
+
[
338
+
list_tags_cmd;
339
+
get_tag_cmd;
340
+
tag_bookmarks_cmd;
341
+
rename_tag_cmd;
342
+
delete_tag_cmd;
343
+
attach_tags_cmd;
344
+
detach_tags_cmd;
345
+
]
346
+
347
+
(* List commands *)
348
+
349
+
let list_lists_cmd =
350
+
let run config fmt () =
351
+
handle_errors (fun () ->
352
+
with_client config (fun client ->
353
+
let lists = Karakeep.fetch_all_lists client in
354
+
print_lists fmt lists);
355
+
0)
356
+
in
357
+
let doc = "List all lists." in
358
+
let info = Cmd.info "list" ~doc in
359
+
Cmd.v info Term.(const run $ config_term $ output_format_term $ setup_logging)
360
+
361
+
let get_list_cmd =
362
+
let run config fmt () list_id =
363
+
handle_errors (fun () ->
364
+
with_client config (fun client ->
365
+
let lst = Karakeep.fetch_list_details client list_id in
366
+
print_list fmt lst);
367
+
0)
368
+
in
369
+
let doc = "Get details of a specific list." in
370
+
let info = Cmd.info "get" ~doc in
371
+
Cmd.v info
372
+
Term.(const run $ config_term $ output_format_term $ setup_logging $ list_id_term)
373
+
374
+
let create_list_cmd =
375
+
let run config fmt () name icon description parent_id query =
376
+
handle_errors (fun () ->
377
+
with_client config (fun client ->
378
+
let list_type =
379
+
match query with Some _ -> Some Karakeep.Smart | None -> None
380
+
in
381
+
let lst =
382
+
Karakeep.create_list client ~name ~icon ?description ?parent_id
383
+
?list_type ?query ()
384
+
in
385
+
print_list fmt lst);
386
+
0)
387
+
in
388
+
let doc = "Create a new list." in
389
+
let info = Cmd.info "create" ~doc in
390
+
Cmd.v info
391
+
Term.(
392
+
const run $ config_term $ output_format_term $ setup_logging $ name_term
393
+
$ icon_term $ description_term $ parent_id_term $ query_term)
394
+
395
+
let update_list_cmd =
396
+
let run config fmt () list_id name icon description query =
397
+
handle_errors (fun () ->
398
+
with_client config (fun client ->
399
+
let lst =
400
+
Karakeep.update_list client ?name ?icon ?description ?query list_id
401
+
in
402
+
print_list fmt lst);
403
+
0)
404
+
in
405
+
let doc = "Update a list." in
406
+
let info = Cmd.info "update" ~doc in
407
+
Cmd.v info
408
+
Term.(
409
+
const run $ config_term $ output_format_term $ setup_logging $ list_id_term
410
+
$ name_opt_term $ icon_opt_term $ description_term $ query_term)
411
+
412
+
let delete_list_cmd =
413
+
let run config () list_id =
414
+
handle_errors (fun () ->
415
+
with_client config (fun client ->
416
+
Karakeep.delete_list client list_id;
417
+
Logs.app (fun m -> m "Deleted list %s" list_id));
418
+
0)
419
+
in
420
+
let doc = "Delete a list." in
421
+
let info = Cmd.info "delete" ~doc in
422
+
Cmd.v info Term.(const run $ config_term $ setup_logging $ list_id_term)
423
+
424
+
let list_bookmarks_in_list_cmd =
425
+
let run config fmt () list_id limit cursor =
426
+
handle_errors (fun () ->
427
+
with_client config (fun client ->
428
+
let result =
429
+
Karakeep.fetch_bookmarks_in_list client ?limit ?cursor list_id
430
+
in
431
+
print_bookmarks fmt result.bookmarks);
432
+
0)
433
+
in
434
+
let doc = "List bookmarks in a list." in
435
+
let info = Cmd.info "bookmarks" ~doc in
436
+
Cmd.v info
437
+
Term.(
438
+
const run $ config_term $ output_format_term $ setup_logging $ list_id_term
439
+
$ limit_term $ cursor_term)
440
+
441
+
let add_to_list_cmd =
442
+
let run config () list_id bookmark_id =
443
+
handle_errors (fun () ->
444
+
with_client config (fun client ->
445
+
Karakeep.add_bookmark_to_list client list_id bookmark_id;
446
+
Logs.app (fun m ->
447
+
m "Added bookmark %s to list %s" bookmark_id list_id));
448
+
0)
449
+
in
450
+
let doc = "Add a bookmark to a list." in
451
+
let info = Cmd.info "add" ~doc in
452
+
let bid_term =
453
+
let doc = "Bookmark ID to add." in
454
+
Arg.(required & pos 1 (some string) None & info [] ~docv:"BOOKMARK_ID" ~doc)
455
+
in
456
+
Cmd.v info Term.(const run $ config_term $ setup_logging $ list_id_term $ bid_term)
457
+
458
+
let remove_from_list_cmd =
459
+
let run config () list_id bookmark_id =
460
+
handle_errors (fun () ->
461
+
with_client config (fun client ->
462
+
Karakeep.remove_bookmark_from_list client list_id bookmark_id;
463
+
Logs.app (fun m ->
464
+
m "Removed bookmark %s from list %s" bookmark_id list_id));
465
+
0)
466
+
in
467
+
let doc = "Remove a bookmark from a list." in
468
+
let info = Cmd.info "remove" ~doc in
469
+
let bid_term =
470
+
let doc = "Bookmark ID to remove." in
471
+
Arg.(required & pos 1 (some string) None & info [] ~docv:"BOOKMARK_ID" ~doc)
472
+
in
473
+
Cmd.v info Term.(const run $ config_term $ setup_logging $ list_id_term $ bid_term)
474
+
475
+
let lists_cmd =
476
+
let doc = "List operations." in
477
+
let info = Cmd.info "lists" ~doc in
478
+
Cmd.group info
479
+
[
480
+
list_lists_cmd;
481
+
get_list_cmd;
482
+
create_list_cmd;
483
+
update_list_cmd;
484
+
delete_list_cmd;
485
+
list_bookmarks_in_list_cmd;
486
+
add_to_list_cmd;
487
+
remove_from_list_cmd;
488
+
]
489
+
490
+
(* Highlight commands *)
491
+
492
+
let list_highlights_cmd =
493
+
let run config fmt () limit cursor =
494
+
handle_errors (fun () ->
495
+
with_client config (fun client ->
496
+
let result = Karakeep.fetch_all_highlights client ?limit ?cursor () in
497
+
print_highlights fmt result.highlights);
498
+
0)
499
+
in
500
+
let doc = "List all highlights." in
501
+
let info = Cmd.info "list" ~doc in
502
+
Cmd.v info
503
+
Term.(
504
+
const run $ config_term $ output_format_term $ setup_logging $ limit_term
505
+
$ cursor_term)
506
+
507
+
let get_highlight_cmd =
508
+
let run config fmt () highlight_id =
509
+
handle_errors (fun () ->
510
+
with_client config (fun client ->
511
+
let highlight = Karakeep.fetch_highlight_details client highlight_id in
512
+
print_highlight fmt highlight);
513
+
0)
514
+
in
515
+
let doc = "Get details of a specific highlight." in
516
+
let info = Cmd.info "get" ~doc in
517
+
Cmd.v info
518
+
Term.(const run $ config_term $ output_format_term $ setup_logging $ highlight_id_term)
519
+
520
+
let bookmark_highlights_cmd =
521
+
let run config fmt () bookmark_id =
522
+
handle_errors (fun () ->
523
+
with_client config (fun client ->
524
+
let highlights = Karakeep.fetch_bookmark_highlights client bookmark_id in
525
+
print_highlights fmt highlights);
526
+
0)
527
+
in
528
+
let doc = "List highlights for a bookmark." in
529
+
let info = Cmd.info "for-bookmark" ~doc in
530
+
Cmd.v info
531
+
Term.(const run $ config_term $ output_format_term $ setup_logging $ bookmark_id_term)
532
+
533
+
let delete_highlight_cmd =
534
+
let run config () highlight_id =
535
+
handle_errors (fun () ->
536
+
with_client config (fun client ->
537
+
Karakeep.delete_highlight client highlight_id;
538
+
Logs.app (fun m -> m "Deleted highlight %s" highlight_id));
539
+
0)
540
+
in
541
+
let doc = "Delete a highlight." in
542
+
let info = Cmd.info "delete" ~doc in
543
+
Cmd.v info Term.(const run $ config_term $ setup_logging $ highlight_id_term)
544
+
545
+
let highlights_cmd =
546
+
let doc = "Highlight operations." in
547
+
let info = Cmd.info "highlights" ~doc in
548
+
Cmd.group info
549
+
[
550
+
list_highlights_cmd;
551
+
get_highlight_cmd;
552
+
bookmark_highlights_cmd;
553
+
delete_highlight_cmd;
554
+
]
555
+
556
+
(* User commands *)
557
+
558
+
let whoami_cmd =
559
+
let run config fmt () =
560
+
handle_errors (fun () ->
561
+
with_client config (fun client ->
562
+
let user = Karakeep.get_current_user client in
563
+
print_user fmt user);
564
+
0)
565
+
in
566
+
let doc = "Show current user info." in
567
+
let info = Cmd.info "whoami" ~doc in
568
+
Cmd.v info Term.(const run $ config_term $ output_format_term $ setup_logging)
569
+
570
+
let stats_cmd =
571
+
let run config fmt () =
572
+
handle_errors (fun () ->
573
+
with_client config (fun client ->
574
+
let stats = Karakeep.get_user_stats client in
575
+
print_stats fmt stats);
576
+
0)
577
+
in
578
+
let doc = "Show user statistics." in
579
+
let info = Cmd.info "stats" ~doc in
580
+
Cmd.v info Term.(const run $ config_term $ output_format_term $ setup_logging)
581
+
582
+
(* Main command *)
583
+
584
+
let main_cmd =
585
+
let doc = "Karakeep CLI - interact with a Karakeep bookmark service." in
586
+
let man =
587
+
[
588
+
`S Manpage.s_description;
589
+
`P
590
+
"karakeep is a command-line tool for interacting with a Karakeep \
591
+
bookmark service instance.";
592
+
`S Manpage.s_common_options;
593
+
`P "These options are common to all commands.";
594
+
`P "$(b,--base-url)=$(i,URL), $(b,-u) $(i,URL)";
595
+
`Noblank;
596
+
`P " Base URL of the Karakeep instance (default: https://hoard.recoil.org).";
597
+
`P "$(b,--api-key)=$(i,KEY), $(b,-k) $(i,KEY)";
598
+
`Noblank;
599
+
`P " API key for authentication.";
600
+
`P "$(b,--api-key-file)=$(i,FILE)";
601
+
`Noblank;
602
+
`P " File containing the API key (default: .karakeep-api).";
603
+
`P "$(b,-v), $(b,--verbose)";
604
+
`Noblank;
605
+
`P " Increase verbosity. Repeatable.";
606
+
`P "$(b,-q), $(b,--quiet)";
607
+
`Noblank;
608
+
`P " Be quiet. Takes over $(b,-v).";
609
+
`P "$(b,--verbose-http)";
610
+
`Noblank;
611
+
`P " Enable verbose HTTP-level logging including TLS details and hexdumps.";
612
+
`P "$(b,--json), $(b,-J)";
613
+
`Noblank;
614
+
`P " Output in JSON format.";
615
+
`P "$(b,--ids-only)";
616
+
`Noblank;
617
+
`P " Output only IDs (one per line).";
618
+
`S "ENVIRONMENT";
619
+
`P "$(b,KARAKEEP_BASE_URL) - Base URL of the Karakeep instance.";
620
+
`P "$(b,KARAKEEP_API_KEY) - API key for authentication.";
621
+
`S Manpage.s_bugs;
622
+
`P "Report bugs at https://github.com/avsm/ocaml-karakeep/issues";
623
+
]
624
+
in
625
+
let info = Cmd.info "karakeep" ~version:"0.1.0" ~doc ~man in
626
+
Cmd.group info
627
+
[
628
+
bookmarks_cmd;
629
+
tags_cmd;
630
+
lists_cmd;
631
+
highlights_cmd;
632
+
whoami_cmd;
633
+
stats_cmd;
634
+
]
635
+
636
+
let () = exit (Cmd.eval' main_cmd)
+18
-9
dune-project
+18
-9
dune-project
···
4
4
(license ISC)
5
5
(authors "Anil Madhavapeddy")
6
6
(maintainers "anil@recoil.org")
7
+
(homepage "https://tangled.org/@anil.recoil.org/ocaml-karakeep")
8
+
(bug_reports "https://tangled.org/@anil.recoil.org/ocaml-karakeep/issues")
7
9
8
10
(generate_opam_files true)
9
11
10
12
(package
11
13
(name karakeep)
12
-
(synopsis "Karakeep API client")
13
-
(description "OCaml client library for the Karakeep bookmark service API")
14
+
(synopsis "Karakeep API client library for OCaml")
15
+
(description
16
+
"An OCaml client library for the Karakeep bookmark service API.
17
+
Provides full API coverage for bookmarks, tags, lists, highlights,
18
+
and user operations. Built on Eio for structured concurrency with
19
+
a type-safe interface using jsont for JSON encoding/decoding.")
14
20
(depends
15
21
(ocaml (>= "5.2.0"))
16
-
karakeep-proto
17
-
requests
18
-
eio
19
-
jsont
22
+
(requests (>= "0.0.1"))
23
+
(eio (>= "1.2"))
24
+
eio_main
25
+
(jsont (>= "0.1.0"))
20
26
bytesrw
21
-
ptime
22
-
fmt
23
-
uri))
27
+
(ptime (>= "1.2.0"))
28
+
(fmt (>= "0.9.0"))
29
+
(uri (>= "4.0.0"))
30
+
(cmdliner (>= "1.3.0"))
31
+
(logs (>= "0.7.0"))
32
+
(odoc :with-doc)))
+17
-9
karakeep.opam
+17
-9
karakeep.opam
···
1
1
# This file is generated by dune, edit dune-project instead
2
2
opam-version: "2.0"
3
-
synopsis: "Karakeep API client"
4
-
description: "OCaml client library for the Karakeep bookmark service API"
3
+
synopsis: "Karakeep API client library for OCaml"
4
+
description: """
5
+
An OCaml client library for the Karakeep bookmark service API.
6
+
Provides full API coverage for bookmarks, tags, lists, highlights,
7
+
and user operations. Built on Eio for structured concurrency with
8
+
a type-safe interface using jsont for JSON encoding/decoding."""
5
9
maintainer: ["anil@recoil.org"]
6
10
authors: ["Anil Madhavapeddy"]
7
11
license: "ISC"
12
+
homepage: "https://tangled.org/@anil.recoil.org/ocaml-karakeep"
13
+
bug-reports: "https://tangled.org/@anil.recoil.org/ocaml-karakeep/issues"
8
14
depends: [
9
15
"dune" {>= "3.17"}
10
16
"ocaml" {>= "5.2.0"}
11
-
"karakeep-proto"
12
-
"requests"
13
-
"eio"
14
-
"jsont"
17
+
"requests" {>= "0.0.1"}
18
+
"eio" {>= "1.2"}
19
+
"eio_main"
20
+
"jsont" {>= "0.1.0"}
15
21
"bytesrw"
16
-
"ptime"
17
-
"fmt"
18
-
"uri"
22
+
"ptime" {>= "1.2.0"}
23
+
"fmt" {>= "0.9.0"}
24
+
"uri" {>= "4.0.0"}
25
+
"cmdliner" {>= "1.3.0"}
26
+
"logs" {>= "0.7.0"}
19
27
"odoc" {with-doc}
20
28
]
21
29
build: [
+16
lib/cmd/dune
+16
lib/cmd/dune
+346
lib/cmd/karakeep_cmd.ml
+346
lib/cmd/karakeep_cmd.ml
···
1
+
open Cmdliner
2
+
3
+
type config = {
4
+
base_url : string;
5
+
api_key : string;
6
+
}
7
+
8
+
(* Helper to read API key from file *)
9
+
let read_api_key_file path =
10
+
try
11
+
let ic = open_in path in
12
+
let key = input_line ic in
13
+
close_in ic;
14
+
String.trim key
15
+
with _ -> ""
16
+
17
+
(* Base URL term *)
18
+
let base_url_term =
19
+
let doc = "Base URL of the Karakeep instance." in
20
+
let env = Cmd.Env.info "KARAKEEP_BASE_URL" ~doc in
21
+
Arg.(
22
+
value
23
+
& opt string "https://hoard.recoil.org"
24
+
& info [ "base-url"; "u" ] ~docv:"URL" ~doc ~env)
25
+
26
+
(* API key file term *)
27
+
let api_key_file_term =
28
+
let doc = "File containing the API key (one key per line)." in
29
+
Arg.(
30
+
value
31
+
& opt string ".karakeep-api"
32
+
& info [ "api-key-file" ] ~docv:"FILE" ~doc)
33
+
34
+
(* API key direct term *)
35
+
let api_key_direct_term =
36
+
let doc = "API key for authentication." in
37
+
let env = Cmd.Env.info "KARAKEEP_API_KEY" ~doc in
38
+
Arg.(value & opt (some string) None & info [ "api-key"; "k" ] ~docv:"KEY" ~doc ~env)
39
+
40
+
(* Combined API key term *)
41
+
let api_key_term =
42
+
let resolve direct file =
43
+
match direct with
44
+
| Some key -> key
45
+
| None ->
46
+
let env_key =
47
+
try Sys.getenv "KARAKEEP_API_KEY" with Not_found -> ""
48
+
in
49
+
if env_key <> "" then env_key
50
+
else
51
+
let file_key = read_api_key_file file in
52
+
if file_key <> "" then file_key
53
+
else failwith "No API key provided. Use --api-key, KARAKEEP_API_KEY, or --api-key-file"
54
+
in
55
+
Term.(const resolve $ api_key_direct_term $ api_key_file_term)
56
+
57
+
(* Config term *)
58
+
let config_term =
59
+
let make base_url api_key = { base_url; api_key } in
60
+
Term.(const make $ base_url_term $ api_key_term)
61
+
62
+
(* Pagination terms *)
63
+
let limit_term =
64
+
let doc = "Maximum number of items to return." in
65
+
Arg.(value & opt (some int) None & info [ "limit"; "n" ] ~docv:"N" ~doc)
66
+
67
+
let cursor_term =
68
+
let doc = "Pagination cursor for fetching next page." in
69
+
Arg.(value & opt (some string) None & info [ "cursor"; "c" ] ~docv:"CURSOR" ~doc)
70
+
71
+
(* Filter terms *)
72
+
let archived_term =
73
+
let doc = "Filter for archived items." in
74
+
let archived = (Some true, Arg.info [ "archived" ] ~doc) in
75
+
let not_archived =
76
+
(Some false, Arg.info [ "no-archived" ] ~doc:"Filter for non-archived items.")
77
+
in
78
+
Arg.(value & vflag None [ archived; not_archived ])
79
+
80
+
let favourited_term =
81
+
let doc = "Filter for favourited items." in
82
+
let fav = (Some true, Arg.info [ "favourited"; "fav" ] ~doc) in
83
+
let not_fav =
84
+
(Some false, Arg.info [ "no-favourited"; "no-fav" ] ~doc:"Filter for non-favourited items.")
85
+
in
86
+
Arg.(value & vflag None [ fav; not_fav ])
87
+
88
+
let include_content_term =
89
+
let doc = "Include full content in response." in
90
+
let include_it = (true, Arg.info [ "include-content" ] ~doc) in
91
+
let exclude_it = (false, Arg.info [ "no-content" ] ~doc:"Exclude content from response.") in
92
+
Arg.(value & vflag true [ include_it; exclude_it ])
93
+
94
+
(* Entity ID terms *)
95
+
let bookmark_id_term =
96
+
let doc = "Bookmark ID." in
97
+
Arg.(required & pos 0 (some string) None & info [] ~docv:"BOOKMARK_ID" ~doc)
98
+
99
+
let tag_id_term =
100
+
let doc = "Tag ID." in
101
+
Arg.(required & pos 0 (some string) None & info [] ~docv:"TAG_ID" ~doc)
102
+
103
+
let list_id_term =
104
+
let doc = "List ID." in
105
+
Arg.(required & pos 0 (some string) None & info [] ~docv:"LIST_ID" ~doc)
106
+
107
+
let highlight_id_term =
108
+
let doc = "Highlight ID." in
109
+
Arg.(required & pos 0 (some string) None & info [] ~docv:"HIGHLIGHT_ID" ~doc)
110
+
111
+
(* Bookmark terms *)
112
+
let url_term =
113
+
let doc = "URL to bookmark." in
114
+
Arg.(required & pos 0 (some string) None & info [] ~docv:"URL" ~doc)
115
+
116
+
let title_term =
117
+
let doc = "Title for the bookmark." in
118
+
Arg.(value & opt (some string) None & info [ "title"; "t" ] ~docv:"TITLE" ~doc)
119
+
120
+
let note_term =
121
+
let doc = "Note to attach to the bookmark." in
122
+
Arg.(value & opt (some string) None & info [ "note" ] ~docv:"NOTE" ~doc)
123
+
124
+
let summary_term =
125
+
let doc = "Summary text for the bookmark." in
126
+
Arg.(value & opt (some string) None & info [ "summary" ] ~docv:"TEXT" ~doc)
127
+
128
+
let tags_term =
129
+
let doc = "Tag to attach (can be repeated)." in
130
+
Arg.(value & opt_all string [] & info [ "tag" ] ~docv:"TAG" ~doc)
131
+
132
+
(* List terms *)
133
+
let name_term =
134
+
let doc = "Name for the list." in
135
+
Arg.(required & opt (some string) None & info [ "name" ] ~docv:"NAME" ~doc)
136
+
137
+
let name_opt_term =
138
+
let doc = "Name for the list." in
139
+
Arg.(value & opt (some string) None & info [ "name" ] ~docv:"NAME" ~doc)
140
+
141
+
let icon_term =
142
+
let doc = "Icon for the list (emoji or identifier)." in
143
+
Arg.(required & opt (some string) None & info [ "icon" ] ~docv:"ICON" ~doc)
144
+
145
+
let icon_opt_term =
146
+
let doc = "Icon for the list (emoji or identifier)." in
147
+
Arg.(value & opt (some string) None & info [ "icon" ] ~docv:"ICON" ~doc)
148
+
149
+
let description_term =
150
+
let doc = "Description for the list." in
151
+
Arg.(value & opt (some string) None & info [ "description"; "d" ] ~docv:"TEXT" ~doc)
152
+
153
+
let parent_id_term =
154
+
let doc = "Parent list ID for nesting." in
155
+
Arg.(value & opt (some string) None & info [ "parent-id" ] ~docv:"ID" ~doc)
156
+
157
+
let query_term =
158
+
let doc = "Query for smart list." in
159
+
Arg.(value & opt (some string) None & info [ "query"; "q" ] ~docv:"QUERY" ~doc)
160
+
161
+
let search_query_term =
162
+
let doc = "Search query." in
163
+
Arg.(required & pos 0 (some string) None & info [] ~docv:"QUERY" ~doc)
164
+
165
+
(* Highlight terms *)
166
+
let color_term =
167
+
let color_conv =
168
+
let parse s =
169
+
match String.lowercase_ascii s with
170
+
| "yellow" -> Ok Karakeep.Yellow
171
+
| "red" -> Ok Karakeep.Red
172
+
| "green" -> Ok Karakeep.Green
173
+
| "blue" -> Ok Karakeep.Blue
174
+
| _ -> Error (`Msg "Invalid color. Use: yellow, red, green, blue")
175
+
in
176
+
let print fmt c =
177
+
let s =
178
+
match c with
179
+
| Karakeep.Yellow -> "yellow"
180
+
| Karakeep.Red -> "red"
181
+
| Karakeep.Green -> "green"
182
+
| Karakeep.Blue -> "blue"
183
+
in
184
+
Format.pp_print_string fmt s
185
+
in
186
+
Arg.conv (parse, print)
187
+
in
188
+
let doc = "Highlight color (yellow, red, green, blue)." in
189
+
Arg.(value & opt (some color_conv) None & info [ "color" ] ~docv:"COLOR" ~doc)
190
+
191
+
(* Output format *)
192
+
type output_format = Text | Json | Quiet
193
+
194
+
let output_format_term =
195
+
let json = (Json, Arg.info [ "json"; "J" ] ~doc:"Output in JSON format.") in
196
+
let ids_only = (Quiet, Arg.info [ "ids-only" ] ~doc:"Output only IDs (one per line).") in
197
+
Arg.(value & vflag Text [ json; ids_only ])
198
+
199
+
(* Logging setup *)
200
+
let logs_term = Logs_cli.level ()
201
+
let fmt_styler_term = Fmt_cli.style_renderer ()
202
+
203
+
let verbose_http_term =
204
+
let doc = "Enable verbose HTTP-level logging (hexdumps, TLS details)." in
205
+
Arg.(value & flag & info [ "verbose-http" ] ~doc)
206
+
207
+
let setup_logging =
208
+
let setup style_renderer level verbose_http =
209
+
Fmt_tty.setup_std_outputs ?style_renderer ();
210
+
Logs.set_level level;
211
+
Logs.set_reporter (Logs_fmt.reporter ());
212
+
(* Configure Requests log sources - suppress HTTP noise unless --verbose-http *)
213
+
Requests.Cmd.setup_log_sources ~verbose_http level
214
+
in
215
+
Term.(const setup $ fmt_styler_term $ logs_term $ verbose_http_term)
216
+
217
+
(* Client helper *)
218
+
let with_client config f =
219
+
Eio_main.run @@ fun env ->
220
+
Eio.Switch.run @@ fun sw ->
221
+
let client =
222
+
Karakeep.create ~sw ~env ~base_url:config.base_url ~api_key:config.api_key
223
+
in
224
+
f client
225
+
226
+
(* JSON encoding helpers using jsont *)
227
+
let encode_json codec v =
228
+
match Jsont_bytesrw.encode_string codec v with
229
+
| Ok s -> s
230
+
| Error e -> raise (Karakeep.err (Karakeep.Json_error { reason = e }))
231
+
232
+
let json_of_bookmark b = encode_json Karakeep.bookmark_jsont b
233
+
let json_of_tag t = encode_json Karakeep.tag_jsont t
234
+
let json_of_list l = encode_json Karakeep.list_jsont l
235
+
let json_of_highlight h = encode_json Karakeep.highlight_jsont h
236
+
let json_of_user u = encode_json Karakeep.user_info_jsont u
237
+
let json_of_stats s = encode_json Karakeep.user_stats_jsont s
238
+
239
+
(* Output helpers *)
240
+
241
+
let print_json_array to_json items =
242
+
print_string "[";
243
+
List.iteri (fun i item ->
244
+
if i > 0 then print_string ",";
245
+
print_string (to_json item)) items;
246
+
print_endline "]"
247
+
248
+
let print_bookmark fmt (b : Karakeep.bookmark) =
249
+
match fmt with
250
+
| Text ->
251
+
let title = Karakeep.bookmark_title b in
252
+
let status =
253
+
(if b.archived then "[A]" else "")
254
+
^ if b.favourited then "[*]" else ""
255
+
in
256
+
Printf.printf "%s %s %s\n" b.id title status
257
+
| Json -> print_endline (json_of_bookmark b)
258
+
| Quiet -> print_endline b.id
259
+
260
+
let print_bookmarks fmt bookmarks =
261
+
match fmt with
262
+
| Json -> print_json_array json_of_bookmark bookmarks
263
+
| _ -> List.iter (print_bookmark fmt) bookmarks
264
+
265
+
let print_tag fmt (t : Karakeep.tag) =
266
+
match fmt with
267
+
| Text -> Printf.printf "%s %s (%d)\n" t.id t.name t.num_bookmarks
268
+
| Json -> print_endline (json_of_tag t)
269
+
| Quiet -> print_endline t.id
270
+
271
+
let print_tags fmt tags =
272
+
match fmt with
273
+
| Json -> print_json_array json_of_tag tags
274
+
| _ -> List.iter (print_tag fmt) tags
275
+
276
+
let print_list fmt (l : Karakeep._list) =
277
+
match fmt with
278
+
| Text ->
279
+
let type_str =
280
+
match l.list_type with Karakeep.Manual -> "" | Karakeep.Smart -> "[smart]"
281
+
in
282
+
Printf.printf "%s %s %s %s\n" l.id l.icon l.name type_str
283
+
| Json -> print_endline (json_of_list l)
284
+
| Quiet -> print_endline l.id
285
+
286
+
let print_lists fmt lists =
287
+
match fmt with
288
+
| Json -> print_json_array json_of_list lists
289
+
| _ -> List.iter (print_list fmt) lists
290
+
291
+
let print_highlight fmt (h : Karakeep.highlight) =
292
+
match fmt with
293
+
| Text ->
294
+
let text = Option.value ~default:"" h.text in
295
+
let note = Option.value ~default:"" h.note in
296
+
Printf.printf "%s \"%s\" %s\n" h.id text note
297
+
| Json -> print_endline (json_of_highlight h)
298
+
| Quiet -> print_endline h.id
299
+
300
+
let print_highlights fmt highlights =
301
+
match fmt with
302
+
| Json -> print_json_array json_of_highlight highlights
303
+
| _ -> List.iter (print_highlight fmt) highlights
304
+
305
+
let print_user fmt (u : Karakeep.user_info) =
306
+
match fmt with
307
+
| Text ->
308
+
Printf.printf "User: %s\n" (Option.value ~default:"(no name)" u.name);
309
+
Printf.printf "Email: %s\n" (Option.value ~default:"(no email)" u.email);
310
+
Printf.printf "ID: %s\n" u.id
311
+
| Json -> print_endline (json_of_user u)
312
+
| Quiet -> print_endline u.id
313
+
314
+
let print_stats fmt (s : Karakeep.user_stats) =
315
+
match fmt with
316
+
| Text ->
317
+
Printf.printf "Bookmarks: %d\n" s.num_bookmarks;
318
+
Printf.printf "Favorites: %d\n" s.num_favorites;
319
+
Printf.printf "Archived: %d\n" s.num_archived;
320
+
Printf.printf "Tags: %d\n" s.num_tags;
321
+
Printf.printf "Lists: %d\n" s.num_lists;
322
+
Printf.printf "Highlights: %d\n" s.num_highlights
323
+
| Json -> print_endline (json_of_stats s)
324
+
| Quiet ->
325
+
Printf.printf "%d %d %d %d %d %d\n" s.num_bookmarks s.num_favorites
326
+
s.num_archived s.num_tags s.num_lists s.num_highlights
327
+
328
+
(* Error handling *)
329
+
let handle_errors f =
330
+
try f () with
331
+
| Eio.Io (Karakeep.E err, _) ->
332
+
Logs.err (fun m -> m "Karakeep error: %s" (Karakeep.error_to_string err));
333
+
(match err with
334
+
| Karakeep.Api_error { status; _ } when status = 404 -> 2
335
+
| Karakeep.Api_error { status; _ } when status >= 400 && status < 500 -> 2
336
+
| Karakeep.Api_error _ -> 2
337
+
| Karakeep.Json_error _ -> 1)
338
+
| Eio.Io (Eio.Net.E _, _) as e ->
339
+
Logs.err (fun m -> m "Network error: %a" Eio.Exn.pp e);
340
+
3
341
+
| Failure msg ->
342
+
Logs.err (fun m -> m "Error: %s" msg);
343
+
1
344
+
| e ->
345
+
Logs.err (fun m -> m "Unexpected error: %s" (Printexc.to_string e));
346
+
1
+211
lib/cmd/karakeep_cmd.mli
+211
lib/cmd/karakeep_cmd.mli
···
1
+
(** Karakeep CLI support library
2
+
3
+
This module provides cmdliner terms and utilities for building command-line
4
+
tools that interact with the Karakeep API. It can be used standalone or
5
+
embedded into larger applications.
6
+
7
+
{2 Basic Usage}
8
+
9
+
{[
10
+
open Cmdliner
11
+
12
+
let my_command =
13
+
let open Karakeep_cmd in
14
+
let run config =
15
+
with_client config (fun client ->
16
+
let bookmarks = Karakeep.fetch_all_bookmarks client () in
17
+
List.iter (fun b -> print_endline (Karakeep.bookmark_title b)) bookmarks)
18
+
in
19
+
Cmd.v (Cmd.info "my-command") Term.(const run $ config_term)
20
+
]} *)
21
+
22
+
(** {1 Configuration} *)
23
+
24
+
type config = {
25
+
base_url : string; (** Base URL of the Karakeep instance *)
26
+
api_key : string; (** API key for authentication *)
27
+
}
28
+
(** Configuration for connecting to a Karakeep instance. *)
29
+
30
+
val config_term : config Cmdliner.Term.t
31
+
(** Cmdliner term that parses configuration from command-line arguments
32
+
and environment variables.
33
+
34
+
Options:
35
+
- [--base-url URL] or [KARAKEEP_BASE_URL]: Karakeep instance URL
36
+
- [--api-key KEY] or [KARAKEEP_API_KEY]: API key
37
+
- [--api-key-file FILE]: Read API key from file (default: .karakeep-api)
38
+
39
+
The API key is resolved in order: [--api-key], [KARAKEEP_API_KEY],
40
+
contents of [--api-key-file]. *)
41
+
42
+
(** {1 Common Terms} *)
43
+
44
+
val base_url_term : string Cmdliner.Term.t
45
+
(** Term for the base URL option only. *)
46
+
47
+
val api_key_term : string Cmdliner.Term.t
48
+
(** Term for the API key option only. *)
49
+
50
+
(** {1 Pagination Terms} *)
51
+
52
+
val limit_term : int option Cmdliner.Term.t
53
+
(** Term for [--limit N] pagination option. *)
54
+
55
+
val cursor_term : string option Cmdliner.Term.t
56
+
(** Term for [--cursor CURSOR] pagination option. *)
57
+
58
+
(** {1 Filter Terms} *)
59
+
60
+
val archived_term : bool option Cmdliner.Term.t
61
+
(** Term for [--archived] / [--no-archived] filter. *)
62
+
63
+
val favourited_term : bool option Cmdliner.Term.t
64
+
(** Term for [--favourited] / [--no-favourited] filter. *)
65
+
66
+
val include_content_term : bool Cmdliner.Term.t
67
+
(** Term for [--include-content] / [--no-content] option. *)
68
+
69
+
(** {1 Entity ID Terms} *)
70
+
71
+
val bookmark_id_term : Karakeep.bookmark_id Cmdliner.Term.t
72
+
(** Positional argument for bookmark ID. *)
73
+
74
+
val tag_id_term : Karakeep.tag_id Cmdliner.Term.t
75
+
(** Positional argument for tag ID. *)
76
+
77
+
val list_id_term : Karakeep.list_id Cmdliner.Term.t
78
+
(** Positional argument for list ID. *)
79
+
80
+
val highlight_id_term : Karakeep.highlight_id Cmdliner.Term.t
81
+
(** Positional argument for highlight ID. *)
82
+
83
+
(** {1 Bookmark Terms} *)
84
+
85
+
val url_term : string Cmdliner.Term.t
86
+
(** Positional argument for URL. *)
87
+
88
+
val title_term : string option Cmdliner.Term.t
89
+
(** Term for [--title TITLE] option. *)
90
+
91
+
val note_term : string option Cmdliner.Term.t
92
+
(** Term for [--note NOTE] option. *)
93
+
94
+
val summary_term : string option Cmdliner.Term.t
95
+
(** Term for [--summary TEXT] option. *)
96
+
97
+
val tags_term : string list Cmdliner.Term.t
98
+
(** Term for [--tag TAG] option (repeatable). *)
99
+
100
+
(** {1 List Terms} *)
101
+
102
+
val name_term : string Cmdliner.Term.t
103
+
(** Term for [--name NAME] required option. *)
104
+
105
+
val name_opt_term : string option Cmdliner.Term.t
106
+
(** Term for [--name NAME] optional option. *)
107
+
108
+
val icon_term : string Cmdliner.Term.t
109
+
(** Term for [--icon ICON] required option. *)
110
+
111
+
val icon_opt_term : string option Cmdliner.Term.t
112
+
(** Term for [--icon ICON] optional option. *)
113
+
114
+
val description_term : string option Cmdliner.Term.t
115
+
(** Term for [--description TEXT] option. *)
116
+
117
+
val parent_id_term : Karakeep.list_id option Cmdliner.Term.t
118
+
(** Term for [--parent-id ID] option. *)
119
+
120
+
val query_term : string option Cmdliner.Term.t
121
+
(** Term for [--query QUERY] smart list option. *)
122
+
123
+
val search_query_term : string Cmdliner.Term.t
124
+
(** Positional argument for search query. *)
125
+
126
+
(** {1 Highlight Terms} *)
127
+
128
+
val color_term : Karakeep.highlight_color option Cmdliner.Term.t
129
+
(** Term for [--color COLOR] option. *)
130
+
131
+
(** {1 Output Terms} *)
132
+
133
+
type output_format =
134
+
| Text (** Human-readable text output *)
135
+
| Json (** JSON output *)
136
+
| Quiet (** Minimal output (IDs only) *)
137
+
138
+
val output_format_term : output_format Cmdliner.Term.t
139
+
(** Term for [--json] / [--ids-only] output format options. *)
140
+
141
+
(** {1 Logging Setup} *)
142
+
143
+
val setup_logging : unit Cmdliner.Term.t
144
+
(** Term that sets up logging based on verbosity flags.
145
+
Use with [Logs_cli] and [Fmt_cli] for standard options. *)
146
+
147
+
val logs_term : Logs.level option Cmdliner.Term.t
148
+
(** Term for log level from [Logs_cli]. *)
149
+
150
+
val fmt_styler_term : Fmt.style_renderer option Cmdliner.Term.t
151
+
(** Term for formatter style from [Fmt_cli]. *)
152
+
153
+
(** {1 Client Helpers} *)
154
+
155
+
val with_client :
156
+
config ->
157
+
(Karakeep.t -> 'a) ->
158
+
'a
159
+
(** [with_client config f] runs [f] with a Karakeep client configured
160
+
using the given config. Handles Eio setup internally.
161
+
162
+
{[
163
+
let run config =
164
+
with_client config (fun client ->
165
+
let bookmarks = Karakeep.fetch_all_bookmarks client () in
166
+
(* ... *))
167
+
]} *)
168
+
169
+
(** {1 Output Helpers} *)
170
+
171
+
val print_bookmark : output_format -> Karakeep.bookmark -> unit
172
+
(** Print a bookmark in the specified format. *)
173
+
174
+
val print_bookmarks : output_format -> Karakeep.bookmark list -> unit
175
+
(** Print a list of bookmarks in the specified format. *)
176
+
177
+
val print_tag : output_format -> Karakeep.tag -> unit
178
+
(** Print a tag in the specified format. *)
179
+
180
+
val print_tags : output_format -> Karakeep.tag list -> unit
181
+
(** Print a list of tags in the specified format. *)
182
+
183
+
val print_list : output_format -> Karakeep._list -> unit
184
+
(** Print a list in the specified format. *)
185
+
186
+
val print_lists : output_format -> Karakeep._list list -> unit
187
+
(** Print lists in the specified format. *)
188
+
189
+
val print_highlight : output_format -> Karakeep.highlight -> unit
190
+
(** Print a highlight in the specified format. *)
191
+
192
+
val print_highlights : output_format -> Karakeep.highlight list -> unit
193
+
(** Print highlights in the specified format. *)
194
+
195
+
val print_user : output_format -> Karakeep.user_info -> unit
196
+
(** Print user info in the specified format. *)
197
+
198
+
val print_stats : output_format -> Karakeep.user_stats -> unit
199
+
(** Print user stats in the specified format. *)
200
+
201
+
(** {1 Error Handling} *)
202
+
203
+
val handle_errors : (unit -> int) -> int
204
+
(** [handle_errors f] runs [f ()] and catches Karakeep errors,
205
+
printing them to stderr and returning appropriate exit codes.
206
+
207
+
Exit codes:
208
+
- 0: Success
209
+
- 1: General error
210
+
- 2: API error (e.g., not found, unauthorized)
211
+
- 3: Network error *)
+40
-78
lib/karakeep.ml
+40
-78
lib/karakeep.ml
···
62
62
^ String.concat "&"
63
63
(List.map (fun (k, v) -> Uri.pct_encode k ^ "=" ^ Uri.pct_encode v) params)
64
64
65
+
(** Helpers for building query parameters *)
66
+
67
+
let add_param key f = function
68
+
| None -> Fun.id
69
+
| Some v -> fun params -> (key, f v) :: params
70
+
71
+
let add_opt key = add_param key Fun.id
72
+
let add_int key = add_param key string_of_int
73
+
let add_bool key = add_param key (function true -> "true" | false -> "false")
74
+
65
75
let decode_json codec body_str =
66
76
match Jsont_bytesrw.decode_string' codec body_str with
67
77
| Ok v -> v
···
131
141
(** {1 Bookmark Operations} *)
132
142
133
143
let fetch_bookmarks t ?limit ?cursor ?include_content ?archived ?favourited () =
134
-
let params = [] in
135
144
let params =
136
-
match limit with Some l -> ("limit", string_of_int l) :: params | None -> params
137
-
in
138
-
let params =
139
-
match cursor with Some c -> ("cursor", c) :: params | None -> params
140
-
in
141
-
let params =
142
-
match include_content with
143
-
| Some true -> ("includeContent", "true") :: params
144
-
| Some false -> ("includeContent", "false") :: params
145
-
| None -> params
146
-
in
147
-
let params =
148
-
match archived with
149
-
| Some true -> ("archived", "true") :: params
150
-
| Some false -> ("archived", "false") :: params
151
-
| None -> params
152
-
in
153
-
let params =
154
-
match favourited with
155
-
| Some true -> ("favourited", "true") :: params
156
-
| Some false -> ("favourited", "false") :: params
157
-
| None -> params
145
+
[]
146
+
|> add_int "limit" limit
147
+
|> add_opt "cursor" cursor
148
+
|> add_bool "includeContent" include_content
149
+
|> add_bool "archived" archived
150
+
|> add_bool "favourited" favourited
158
151
in
159
152
let url = t.base_url / "api/v1/bookmarks" ^ query_string params in
160
153
get_json t url paginated_bookmarks_jsont
···
174
167
fetch_all [] None 0
175
168
176
169
let search_bookmarks t ~query ?limit ?cursor ?include_content () =
177
-
let params = [ ("q", query) ] in
178
170
let params =
179
-
match limit with Some l -> ("limit", string_of_int l) :: params | None -> params
180
-
in
181
-
let params =
182
-
match cursor with Some c -> ("cursor", c) :: params | None -> params
183
-
in
184
-
let params =
185
-
match include_content with
186
-
| Some true -> ("includeContent", "true") :: params
187
-
| Some false -> ("includeContent", "false") :: params
188
-
| None -> params
171
+
[ ("q", query) ]
172
+
|> add_int "limit" limit
173
+
|> add_opt "cursor" cursor
174
+
|> add_bool "includeContent" include_content
189
175
in
190
176
let url = t.base_url / "api/v1/bookmarks/search" ^ query_string params in
191
177
get_json t url paginated_bookmarks_jsont
···
193
179
let fetch_bookmark_details t bookmark_id =
194
180
let url = t.base_url / "api/v1/bookmarks" / bookmark_id in
195
181
get_json t url bookmark_jsont
182
+
183
+
let tag_ref_of_poly = function `TagId id -> TagId id | `TagName name -> TagName name
196
184
197
185
let rec create_bookmark t ~url ?title ?note ?summary ?favourited ?archived ?created_at
198
186
?tags () =
···
215
203
match tags with
216
204
| None | Some [] -> bookmark
217
205
| Some tag_names ->
218
-
let tag_refs = List.map (fun n -> TagName n) tag_names in
219
-
let _ =
220
-
attach_tags t ~tag_refs:(List.map (fun r -> match r with TagName n -> `TagName n | TagId i -> `TagId i) tag_refs) bookmark.id
221
-
in
206
+
let tag_refs = List.map (fun n -> `TagName n) tag_names in
207
+
let _ = attach_tags t ~tag_refs bookmark.id in
222
208
(* Refetch the bookmark to get updated tags *)
223
209
fetch_bookmark_details t bookmark.id
224
210
225
211
and attach_tags t ~tag_refs bookmark_id =
226
212
let url = t.base_url / "api/v1/bookmarks" / bookmark_id / "tags" in
227
-
let tags =
228
-
List.map
229
-
(function `TagId id -> TagId id | `TagName name -> TagName name)
230
-
tag_refs
231
-
in
213
+
let tags = List.map tag_ref_of_poly tag_refs in
232
214
let req = { tags } in
233
215
let resp = post_json t url attach_tags_request_jsont req attach_tags_response_jsont in
234
216
resp.attached
···
244
226
245
227
let summarize_bookmark t bookmark_id =
246
228
let url = t.base_url / "api/v1/bookmarks" / bookmark_id / "summarize" in
247
-
post_json_no_body t url bookmark_jsont
229
+
post_json_no_body t url summarize_response_jsont
248
230
249
231
(** {1 Tag Operations} *)
250
232
251
233
let detach_tags t ~tag_refs bookmark_id =
252
234
let url = t.base_url / "api/v1/bookmarks" / bookmark_id / "tags" in
253
-
let tags =
254
-
List.map
255
-
(function `TagId id -> TagId id | `TagName name -> TagName name)
256
-
tag_refs
257
-
in
235
+
let tags = List.map tag_ref_of_poly tag_refs in
258
236
let req = { tags } in
259
237
(* DELETE with body - use request function directly *)
260
238
let body_str = encode_json attach_tags_request_jsont req in
···
276
254
get_json t url tag_jsont
277
255
278
256
let fetch_bookmarks_with_tag t ?limit ?cursor ?include_content tag_id =
279
-
let params = [] in
280
257
let params =
281
-
match limit with Some l -> ("limit", string_of_int l) :: params | None -> params
282
-
in
283
-
let params =
284
-
match cursor with Some c -> ("cursor", c) :: params | None -> params
285
-
in
286
-
let params =
287
-
match include_content with
288
-
| Some true -> ("includeContent", "true") :: params
289
-
| Some false -> ("includeContent", "false") :: params
290
-
| None -> params
258
+
[]
259
+
|> add_int "limit" limit
260
+
|> add_opt "cursor" cursor
261
+
|> add_bool "includeContent" include_content
291
262
in
292
263
let url = t.base_url / "api/v1/tags" / tag_id / "bookmarks" ^ query_string params in
293
264
get_json t url paginated_bookmarks_jsont
···
333
304
delete_json t url
334
305
335
306
let fetch_bookmarks_in_list t ?limit ?cursor ?include_content list_id =
336
-
let params = [] in
337
307
let params =
338
-
match limit with Some l -> ("limit", string_of_int l) :: params | None -> params
339
-
in
340
-
let params =
341
-
match cursor with Some c -> ("cursor", c) :: params | None -> params
342
-
in
343
-
let params =
344
-
match include_content with
345
-
| Some true -> ("includeContent", "true") :: params
346
-
| Some false -> ("includeContent", "false") :: params
347
-
| None -> params
308
+
[]
309
+
|> add_int "limit" limit
310
+
|> add_opt "cursor" cursor
311
+
|> add_bool "includeContent" include_content
348
312
in
349
313
let url = t.base_url / "api/v1/lists" / list_id / "bookmarks" ^ query_string params in
350
314
get_json t url paginated_bookmarks_jsont
···
363
327
(** {1 Highlight Operations} *)
364
328
365
329
let fetch_all_highlights t ?limit ?cursor () =
366
-
let params = [] in
367
-
let params =
368
-
match limit with Some l -> ("limit", string_of_int l) :: params | None -> params
369
-
in
370
330
let params =
371
-
match cursor with Some c -> ("cursor", c) :: params | None -> params
331
+
[]
332
+
|> add_int "limit" limit
333
+
|> add_opt "cursor" cursor
372
334
in
373
335
let url = t.base_url / "api/v1/highlights" ^ query_string params in
374
336
get_json t url paginated_highlights_jsont
···
428
390
(** {1 User Operations} *)
429
391
430
392
let get_current_user t =
431
-
let url = t.base_url / "api/v1/user" in
393
+
let url = t.base_url / "api/v1/users/me" in
432
394
get_json t url user_info_jsont
433
395
434
396
let get_user_stats t =
435
-
let url = t.base_url / "api/v1/user/stats" in
397
+
let url = t.base_url / "api/v1/users/me/stats" in
436
398
get_json t url user_stats_jsont
+2
-1
lib/karakeep.mli
+2
-1
lib/karakeep.mli
···
197
197
(** [delete_bookmark client id] deletes a bookmark.
198
198
@raise Eio.Io with {!E} on API or network errors *)
199
199
200
-
val summarize_bookmark : t -> bookmark_id -> bookmark
200
+
val summarize_bookmark : t -> bookmark_id -> summarize_response
201
201
(** [summarize_bookmark client id] generates an AI summary for a bookmark.
202
+
Returns a response containing the summary text.
202
203
@raise Eio.Io with {!E} on API or network errors *)
203
204
204
205
(** {1 Tag Operations} *)
+8
lib/proto/karakeep_proto.ml
+8
lib/proto/karakeep_proto.ml
···
739
739
Jsont.Object.map ~kind:"replace_asset_request" make
740
740
|> Jsont.Object.mem "assetId" Jsont.string ~enc:(fun r -> r.asset_id)
741
741
|> Jsont.Object.finish
742
+
743
+
type summarize_response = { summary : string }
744
+
745
+
let summarize_response_jsont =
746
+
let make summary = { summary } in
747
+
Jsont.Object.map ~kind:"summarize_response" make
748
+
|> Jsont.Object.mem "summary" Jsont.string ~enc:(fun r -> r.summary)
749
+
|> Jsont.Object.finish
+5
lib/proto/karakeep_proto.mli
+5
lib/proto/karakeep_proto.mli
···
399
399
400
400
val replace_asset_request_jsont : replace_asset_request Jsont.t
401
401
402
+
type summarize_response = { summary : string }
403
+
(** Response from summarize bookmark endpoint *)
404
+
405
+
val summarize_response_jsont : summarize_response Jsont.t
406
+
402
407
(** {1 Helper Codecs} *)
403
408
404
409
val ptime_jsont : Ptime.t Jsont.t
+3
test/asset_test.ml
+3
test/asset_test.ml
+3
test/create_test.ml
+3
test/create_test.ml
+3
test/search_test.ml
+3
test/search_test.ml