Eiocmd - Batteries-Included CLI Runner for Eio#

Eiocmd provides a convenient wrapper for building command-line applications with Eio. It handles common setup tasks and provides a clean interface for building CLIs with minimal boilerplate.

Features#

• Logging Setup: Automatic configuration of Logs with Fmt reporter
• Cmdliner Integration: Clean command-line argument parsing
• Optional XDG Support: Integrate with xdge for XDG directory management
• Optional Keyeio Support: Integrate with keyeio for API key management
• Minimal Boilerplate: Get started quickly with sensible defaults

Installation#

opam install eiocmd

Quick Start#

Basic Usage#

open Cmdliner

let main _env =
  Logs.info (fun m -> m "Hello, world!");
  0

let () =
  let info = Cmd.info "myapp" ~version:"1.0.0" ~doc:"My application" in
  Eiocmd.run ~info main

This automatically provides:

• --log-level flag (debug, info, warning, error, app)
• --color flag (auto, always, never)
• Proper Eio environment setup

With XDG Directory Support#

let main _env (xdg, _xdg_cmd) =
  let config_dir = Xdge.config_dir xdg in
  Logs.info (fun m -> m "Config dir: %a" Eio.Path.pp config_dir);
  0

let () =
  let info = Cmd.info "myapp" ~doc:"My app with XDG support" in
  Eiocmd.run ~info ~xdge:(Some "myapp") main

With Keyeio API Key Management#

let main _env (_xdg, _xdg_cmd) profile =
  let api_key = Keyeio.Profile.get_required profile ~key:"api_key" in
  Logs.info (fun m -> m "Using API key: %s..." (String.sub api_key 0 8));
  (* Use api_key to create your API client *)
  0

let () =
  let info = Cmd.info "myapp" ~doc:"My app with keyeio" in
  Eiocmd.run ~info
    ~xdge:(Some "myapp")
    ~keyeio:(Some "myservice")
    main

This automatically provides:

• --profile flag to select credential profile
• --key-file flag to override credential file location
• Automatic loading of credentials from ~/.config/myapp/keys/myservice.toml

API Documentation#

See the mli file for full API documentation.

Log Levels#

The --log-level flag accepts:

• debug - Debug messages and above
• info - Informational messages and above (default)
• warning - Warnings and above
• error - Errors only
• app - Application-specific messages

Color Output#

The --color flag accepts:

• auto - Detect TTY capability (default)
• always - Force color output
• never - Disable color output

Advanced Usage#

For more control, you can use the low-level Setup module:

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

  (* Initialize components manually *)
  Eiocmd.Setup.init_rng env;
  Eiocmd.Setup.init_logs ~level:(Some Logs.Debug) ();

  (* Your application logic *)
  Logs.debug (fun m -> m "Starting application");
  (* ... *)

Or compose your own Cmdliner terms using Eiocmd.Terms:

let main log_level style_renderer custom_arg =
  Eio_main.run @@ fun env ->
  Eiocmd.Setup.init_logs ~level:log_level ~style_renderer ();
  (* ... *)

let () =
  let custom_arg = Arg.(value & opt string "default" & info ["custom"]) in
  let term = Term.(const main
    $ Eiocmd.Terms.log_level
    $ Eiocmd.Terms.style_renderer
    $ custom_arg) in
  let info = Cmd.info "myapp" in
  exit (Cmd.eval' (Cmd.v info term))

Examples#

See the example directory for more comprehensive examples.

License#

ISC License - see LICENSE file for details.