anil.recoil.org
OCaml bindings to the Typesense embeddings search API
1(*---------------------------------------------------------------------------
2 Copyright (c) 2025 Anil Madhavapeddy. All rights reserved.
3 SPDX-License-Identifier: ISC
4 ---------------------------------------------------------------------------*)
5
6(** Cmdliner helpers for Typesense CLI authentication.
7
8 This module provides reusable command-line argument definitions and command
9 builders for authentication workflows. It supports multiple profiles for
10 managing multiple server connections.
11
12 {2 Usage}
13
14 {[
15 (* In your main.ml *)
16 Eio_main.run @@ fun env ->
17 let fs = env#fs in
18 Cmd.group (Cmd.info "typesense-cli")
19 [ Typesense_auth.Cmd.auth_cmd env fs
20 ; (* other commands *)
21 ]
22 |> Cmd.eval_exn
23 ]}
24
25 {2 Environment Variables}
26
27 - [TYPESENSE_SERVER]: Default server URL
28 - [TYPESENSE_API_KEY]: Default API key
29
30 {2 Logging}
31
32 Uses Logs_cli for verbosity control:
33 - [-v] or [--verbose]: Info level logging
34 - [-v -v] or [--verbosity=debug]: Debug level logging
35 - [--verbose-http]: Enable verbose HTTP protocol logging *)
36
37open Cmdliner
38
39(** {1 Common Arguments} *)
40
41val server_arg : string Term.t
42(** Required positional argument for server URL (also reads [TYPESENSE_SERVER]). *)
43
44val server_opt : string option Term.t
45(** Optional [--server] argument (also reads [TYPESENSE_SERVER]). *)
46
47val api_key_arg : string option Term.t
48(** Optional [--api-key] argument (also reads [TYPESENSE_API_KEY]). *)
49
50val profile_arg : string option Term.t
51(** Optional [--profile] argument for selecting a specific profile. *)
52
53(** {1 Logging and Configuration} *)
54
55val setup_logging : (Fmt.style_renderer option * Logs.level option) Term.t
56(** Term that collects logging options ([-v], [--color], etc.).
57 Use with [setup_logging_with_config] to apply logging after parsing. *)
58
59val setup_logging_with_config :
60 Fmt.style_renderer option ->
61 Logs.level option ->
62 Requests.Cmd.config ->
63 unit
64(** [setup_logging_with_config style_renderer level config] sets up logging
65 with the given options. Extracts [--verbose-http] from the requests config.
66 Call this at the start of command execution. *)
67
68val requests_config_term : Eio.Fs.dir_ty Eio.Path.t -> Requests.Cmd.config Term.t
69(** Term for HTTP request configuration (timeouts, retries, proxy, etc.). *)
70
71(** {1 Commands}
72
73 Commands take an [env] parameter from the outer [Eio_main.run] context,
74 and an [fs] path for building cmdliner terms. *)
75
76val auth_cmd :
77 < fs : Eio.Fs.dir_ty Eio.Path.t
78 ; clock : _ Eio.Time.clock
79 ; net : _ Eio.Net.t
80 ; .. > ->
81 Eio.Fs.dir_ty Eio.Path.t ->
82 unit Cmd.t
83(** Complete auth command group combining login, logout, status, and profile. *)
84
85(** {1 Helper Functions} *)
86
87val with_session :
88 ?profile:string ->
89 (Eio.Fs.dir_ty Eio.Path.t -> Session.t -> 'a) ->
90 < fs : Eio.Fs.dir_ty Eio.Path.t ; .. > ->
91 'a
92(** [with_session ?profile f env] loads the session and calls
93 [f fs session]. Prints an error and exits if not logged in.
94 @param profile Profile to load (default: current profile) *)
95
96val with_client :
97 ?requests_config:Requests.Cmd.config ->
98 ?profile:string ->
99 (Eio.Fs.dir_ty Eio.Path.t -> Client.t -> 'a) ->
100 < fs : Eio.Fs.dir_ty Eio.Path.t
101 ; clock : _ Eio.Time.clock
102 ; net : _ Eio.Net.t
103 ; .. > ->
104 'a
105(** [with_client ?requests_config ?profile f env] loads the session, creates a client, and calls
106 [f fs client]. Prints an error and exits if not logged in.
107 @param requests_config HTTP request configuration
108 @param profile Profile to load (default: current profile) *)
109
110(** {1 Profile Configuration for External Programs}
111
112 These types and functions allow other programs to easily use Typesense profiles
113 that were set up with the typesense CLI. *)
114
115(** Configuration for using a Typesense profile. *)
116module Profile_config : sig
117 type t
118 (** Bundled configuration for Typesense profile access. *)
119
120 val style_renderer : t -> Fmt.style_renderer option
121 (** Terminal style renderer setting. *)
122
123 val log_level : t -> Logs.level option
124 (** Logging level. *)
125
126 val requests_config : t -> Requests.Cmd.config
127 (** HTTP request configuration. *)
128
129 val profile : t -> string option
130 (** Selected profile name, if any. *)
131
132 val setup_logging : t -> unit
133 (** [setup_logging config] initializes logging with the bundled settings.
134 Call this at the start of your command execution. *)
135end
136
137val profile_config_term : Eio.Fs.dir_ty Eio.Path.t -> Profile_config.t Term.t
138(** Cmdliner term that collects all configuration needed to use a Typesense profile.
139
140 Combines:
141 - Logging options ([-v], [--color], etc.)
142 - HTTP configuration (timeouts, retries, proxy, [--verbose-http])
143 - Profile selection ([--profile])
144
145 Use with {!with_client} to create an authenticated client. *)