Skip to main content

Crate clapfig

Crate clapfig 

Source
Expand description

Rich, layered configuration for Rust applications.

Clapfig manages configuration from multiple sources — config files, environment variables, and programmatic overrides — with a builder API that takes a few lines to set up. Built on confique for struct-driven defaults and template generation.

§Core library — no CLI framework required

The core of clapfig is a pure Rust API with no dependency on any CLI framework. Config discovery, multi-file merging, environment variable mapping, key lookup, persistence, and template generation all work through ClapfigBuilder and ConfigAction without importing clap or any other parser. You can use clapfig in GUI apps, servers, or with any CLI parser of your choice.

§Optional clap adapter (clap feature, on by default)

For CLI apps using clap, clapfig ships an optional adapter behind the clap Cargo feature (enabled by default). The [cli] module provides ConfigArgs and ConfigSubcommand — ready-made clap derive types that give your app config gen|list|get|set subcommands with zero boilerplate. They convert to the framework-agnostic ConfigAction via ConfigArgs::into_action().

To use clapfig without clap, disable default features:

clapfig = { version = "...", default-features = false }

§Three axes of configuration

Config file handling is controlled by three orthogonal settings on the builder:

  • Discovery (search_paths()): where to look for config files. Supports explicit directories, platform paths, and walking up the directory tree via SearchPath::Ancestors.

  • Resolution (search_mode()): what to do with found files. Merge deep-merges all found configs (layered overrides); FirstMatch uses only the highest-priority file found (“find my config”).

  • Persistence (persist_path()): where config set writes. Explicit and independent of the search paths — no guessing.

See the types module for the full conceptual documentation and use-case examples.

§Layer precedence (lowest to highest)

  1. Compiled defaults (#[config(default = ...)])
  2. Config files (discovery + resolution mode)
  3. Environment variables (PREFIX__KEY)
  4. Programmatic overrides (.cli_override())

Every layer is sparse — only the keys you specify are merged.

§Quick start

ⓘ
let config: AppConfig = Clapfig::builder()
    .app_name("myapp")
    .load()?;

Re-exports§

pub use error::ClapfigError;
pub use types::Boundary;
pub use types::ConfigAction;
pub use types::SearchMode;
pub use types::SearchPath;

Modules§

error
types
Core types that define how clapfig discovers, resolves, and persists configuration.

Structs§

Clapfig
Entry point for building a clapfig configuration.
ClapfigBuilder
Builder for configuring and loading layered configuration.
ConfigArgs
Clap-derived args for the config subcommand group.

Enums§

ConfigResult
Result of a config operation. Returned to the caller for display.
ConfigSubcommand
Available config subcommands.