emx-config

A git-config style configuration management library and CLI tool.

Features

• Multiple configuration layers with priority: args > env > local > global > default
• TOML-based configuration files
• Environment variable support
• Sectioned configuration keys (e.g., section.key, section.subsection.key)
• JSON and JSONL output formats for CLI

Installation

cargo install --path .

Usage

CLI

# Get a configuration value
emx-config get user.name

# Set a configuration value (local)
emx-config set user.name "John Doe"

# Set a configuration value (global)
emx-config set --global user.name "John Doe"

# List all configuration values
emx-config list

# List with source layer
emx-config list --show-source

# Unset a configuration value
emx-config unset user.name

# Output in JSON format (nested JSON object)
emx-config --json get user.name
emx-config --json list

# Output in JSONL format (one JSON object per line, machine-readable)
emx-config --jsonl get user.name
emx-config --jsonl list

Library

use emx_config_core::{Config, ConfigLayer};
use std::collections::HashMap;

// Create a config with defaults
let mut defaults = HashMap::new();
defaults.insert("timeout".to_string(), toml::Value::Integer(30));

let config = Config::builder()
    .with_defaults(defaults)
    .build()
    .unwrap();

// Get a value
let timeout = config.get_int("timeout").unwrap();

Configuration Priority

Configuration values are loaded from multiple sources in order of priority (highest first):

1. Arguments - Command-line arguments
2. Environment - Environment variables and .env file
3. Local - ./config.toml (or EMX_CONFIG_NAME value)
4. Global - $EMX_HOME/config.toml (or EMX_CONFIG_NAME value)
5. Default - Default values provided when building the config

Environment Variables

• EMX_HOME - Directory for global configuration
• EMX_CONFIG_NAME - Name of the configuration file (default: config.toml)
• EMX_LOAD_ENV - Whether to load environment variables (default: 1)
  • When set to 0, environment variables and .env file are not loaded
  • EMX_CONFIG_NAME and EMX_HOME are still respected

Configuration Keys

Configuration keys can be specified in two formats:

1. Underscore notation (recommended for simple keys):

   • timeout - Top-level key
   • user_name - Simple key
   • test_value - Simple key

2. Dot notation (for nested sections):

   • user.name - Key in user section
   • git.branch.main - Key in nested sections

Both notations work and can be used interchangeably.

Environment Variable Mapping

Configuration keys use underscores to represent nesting in environment variables:

• timeout → EMX_TIMEOUT
• user_name → EMX_USER_NAME
• test.value → EMX_TEST_VALUE (both test.value and test_value map to EMX_TEST_VALUE)
• git.branch.main → EMX_GIT_BRANCH_MAIN

Note: Environment variables use underscores (_) while configuration files may use dots (.) or TOML tables for nesting. Both styles are supported and will correctly map to the same environment variable.

License

MIT