Module Immich_auth.Cmd

Cmdliner helpers for Immich CLI authentication.

This module provides reusable command-line argument definitions and command builders for authentication workflows. It supports multiple profiles for managing multiple server connections.

Usage

  (* In your main.ml *)
  Eio_main.run @@ fun env ->
  let fs = env#fs in
  Cmd.group (Cmd.info "immich")
    [ Cmd.auth_cmd env fs
    ; (* other commands *)
    ]
  |> Cmd.eval_exn

Environment Variables

Logging

Uses Logs_cli for verbosity control:

Common Arguments

val server_arg : string Cmdliner.Term.t

Required positional argument for server URL (also reads IMMICH_SERVER).

val server_opt : string option Cmdliner.Term.t

Optional --server argument (also reads IMMICH_SERVER).

val api_key_arg : string option Cmdliner.Term.t

Optional --api-key argument (also reads IMMICH_API_KEY).

val email_arg : string option Cmdliner.Term.t

Optional --email argument for password authentication.

val password_arg : string option Cmdliner.Term.t

Optional --password argument.

val profile_arg : string option Cmdliner.Term.t

Optional --profile argument for selecting a specific profile.

val key_name_arg : string option Cmdliner.Term.t

Optional --name argument for naming API keys.

Logging and Configuration

val setup_logging : (Fmt.style_renderer option * Logs.level option) Cmdliner.Term.t

Term that collects logging options (-v, --color, etc.). Use with setup_logging_with_config to apply logging after parsing.

val setup_logging_with_config : Fmt.style_renderer option -> Logs.level option -> Requests.Cmd.config -> unit

setup_logging_with_config style_renderer level config sets up logging with the given options. Extracts --verbose-http from the requests config. Call this at the start of command execution.

Term for HTTP request configuration (timeouts, retries, proxy, etc.).

Commands

Commands take an env parameter from the outer Eio_main.run context, and an fs path for building cmdliner terms.

val auth_cmd : < fs : Eio.Fs.dir_ty Eio.Path.t ; clock : _ Eio.Time.clock ; net : _ Eio.Net.t.. > -> Eio.Fs.dir_ty Eio.Path.t -> unit Cmdliner.Cmd.t

Complete auth command group combining login, logout, status, and profile.

Helper Functions

val with_session : ?profile:string -> (Eio.Fs.dir_ty Eio.Path.t -> Session.t -> 'a) -> < fs : Eio.Fs.dir_ty Eio.Path.t.. > -> 'a

with_session ?profile f env loads the session and calls f fs session. Prints an error and exits if not logged in.

  • parameter profile

    Profile to load (default: current profile)

val with_client : ?requests_config:Requests.Cmd.config -> ?profile:string -> (Eio.Fs.dir_ty Eio.Path.t -> Client.t -> 'a) -> < fs : Eio.Fs.dir_ty Eio.Path.t ; clock : _ Eio.Time.clock ; net : _ Eio.Net.t.. > -> 'a

with_client ?requests_config ?profile f env loads the session, creates a client, and calls f fs client. Prints an error and exits if not logged in.

  • parameter requests_config

    HTTP request configuration

  • parameter profile

    Profile to load (default: current profile)

Profile Configuration for External Programs

These types and functions allow other programs to easily use Immich profiles that were set up with the immich CLI. This provides a single cmdliner term that bundles all the necessary configuration.

Example Usage

  (* In your sortal/bin/main.ml *)
  open Cmdliner

  let my_cmd env fs =
    let doc = "My command using Immich" in
    let info = Cmd.info "my-command" ~doc in
    let action config =
      let open Immich_auth.Cmd.Profile_config in
      setup_logging config;
      Immich_auth.Cmd.with_client
        ~requests_config:(requests_config config)
        ?profile:(profile config)
        (fun _fs client ->
          let api = Immich_auth.Client.client client in
          (* Use the Immich API here *)
          ()
        ) env
    in
    Cmd.v info Term.(const action $ Immich_auth.Cmd.profile_config_term fs)
module Profile_config : sig ... end

Configuration for using an Immich profile.

Cmdliner term that collects all configuration needed to use an Immich profile.

Combines:

  • Logging options (-v, --color, etc.)
  • HTTP configuration (timeouts, retries, proxy, --verbose-http)
  • Profile selection (--profile)

Use with with_client to create an authenticated client.