# Eiocmd - Batteries-Included CLI Runner for Eio

Eiocmd 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.

## Features

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

## Installation

```bash
opam install eiocmd
```

## Quick Start

### Basic Usage

```ocaml
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

```ocaml
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

```ocaml
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](lib/eiocmd.mli) 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:

```ocaml
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`:

```ocaml
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](example/) for more comprehensive examples.

## License

ISC License - see LICENSE file for details.