My agentic slop goes here. Not intended for anyone else!
anil.recoil.org
1# Eiocmd - Batteries-Included CLI Runner for Eio
2
3Eiocmd provides a convenient wrapper for building command-line applications with [Eio](https://github.com/ocaml-multicore/eio). It handles common setup tasks and provides a clean interface for building CLIs with minimal boilerplate.
4
5## Features
6
7- **Logging Setup**: Automatic configuration of Logs with Fmt reporter
8- **Cmdliner Integration**: Clean command-line argument parsing
9- **Optional XDG Support**: Integrate with [xdge](../xdge) for XDG directory management
10- **Optional Keyeio Support**: Integrate with [keyeio](../keyeio) for API key management
11- **Minimal Boilerplate**: Get started quickly with sensible defaults
12
13## Installation
14
15```bash
16opam install eiocmd
17```
18
19## Quick Start
20
21### Basic Usage
22
23```ocaml
24open Cmdliner
25
26let main _env =
27 Logs.info (fun m -> m "Hello, world!");
28 0
29
30let () =
31 let info = Cmd.info "myapp" ~version:"1.0.0" ~doc:"My application" in
32 Eiocmd.run ~info main
33```
34
35This automatically provides:
36- `--log-level` flag (debug, info, warning, error, app)
37- `--color` flag (auto, always, never)
38- Proper Eio environment setup
39
40### With XDG Directory Support
41
42```ocaml
43let main _env (xdg, _xdg_cmd) =
44 let config_dir = Xdge.config_dir xdg in
45 Logs.info (fun m -> m "Config dir: %a" Eio.Path.pp config_dir);
46 0
47
48let () =
49 let info = Cmd.info "myapp" ~doc:"My app with XDG support" in
50 Eiocmd.run ~info ~xdge:(Some "myapp") main
51```
52
53### With Keyeio API Key Management
54
55```ocaml
56let main _env (_xdg, _xdg_cmd) profile =
57 let api_key = Keyeio.Profile.get_required profile ~key:"api_key" in
58 Logs.info (fun m -> m "Using API key: %s..." (String.sub api_key 0 8));
59 (* Use api_key to create your API client *)
60 0
61
62let () =
63 let info = Cmd.info "myapp" ~doc:"My app with keyeio" in
64 Eiocmd.run ~info
65 ~xdge:(Some "myapp")
66 ~keyeio:(Some "myservice")
67 main
68```
69
70This automatically provides:
71- `--profile` flag to select credential profile
72- `--key-file` flag to override credential file location
73- Automatic loading of credentials from `~/.config/myapp/keys/myservice.toml`
74
75## API Documentation
76
77See [the mli file](lib/eiocmd.mli) for full API documentation.
78
79### Log Levels
80
81The `--log-level` flag accepts:
82- `debug` - Debug messages and above
83- `info` - Informational messages and above (default)
84- `warning` - Warnings and above
85- `error` - Errors only
86- `app` - Application-specific messages
87
88### Color Output
89
90The `--color` flag accepts:
91- `auto` - Detect TTY capability (default)
92- `always` - Force color output
93- `never` - Disable color output
94
95## Advanced Usage
96
97For more control, you can use the low-level `Setup` module:
98
99```ocaml
100let () =
101 Eio_main.run @@ fun env ->
102
103 (* Initialize components manually *)
104 Eiocmd.Setup.init_rng env;
105 Eiocmd.Setup.init_logs ~level:(Some Logs.Debug) ();
106
107 (* Your application logic *)
108 Logs.debug (fun m -> m "Starting application");
109 (* ... *)
110```
111
112Or compose your own Cmdliner terms using `Eiocmd.Terms`:
113
114```ocaml
115let main log_level style_renderer custom_arg =
116 Eio_main.run @@ fun env ->
117 Eiocmd.Setup.init_logs ~level:log_level ~style_renderer ();
118 (* ... *)
119
120let () =
121 let custom_arg = Arg.(value & opt string "default" & info ["custom"]) in
122 let term = Term.(const main
123 $ Eiocmd.Terms.log_level
124 $ Eiocmd.Terms.style_renderer
125 $ custom_arg) in
126 let info = Cmd.info "myapp" in
127 exit (Cmd.eval' (Cmd.v info term))
128```
129
130## Examples
131
132See the [example directory](example/) for more comprehensive examples.
133
134## License
135
136ISC License - see LICENSE file for details.