cliconf

Dead-simple configuration for Rust CLI tools.

How it Works

Define a flag that your program accepts:

let mut flags = Flags::new();
flags.add(Flag {
    name: "hello-name",
    shorthand: Some('n'),
    default_value: FlagValue::String("world".to_string()),
    description: Some("Who to say hello to."),
});

Add one or more locations of config files:

flags.add_config_file("/var/lib/hello-world/config.json");
flags.add_home_config_file(".config/hello-world/config.json");

Load flags:

let env_vars: HashMap<String, String> = env::vars().collect();

let args: Vec<String> = env::args().collect();
let args = args[1..].to_vec(); // Exclude name of executable

flags.load(&env_vars, &args)?;

Get values:

let name = flags.get_string("hello-name");
println!("Hello, {name}!");

Get non-flag arguments:

let positionals = flags.positionals();

Using Flags

Flags are always processed in the following order:

1. Configuration files (processed in the order they are added)
2. Environment variables
3. Command-line arguments

The following configuration methods all produce the same result:

1. Configuration files

{
  "hello-name": "john"
}

2. Environment variables

HELLO_NAME="john" hello-world

3. Command-line arguments

hello-world --hello-name "john"
# or, using the shorthand
hello-world -n "john"

Flags processed later-on in the cycle take precedence, so command-line arguments will override environment variables, which will override config files:

HELLO_NAME=from_environment hello-world -n from_args
# Outputs: "Hello, from_args!"

Types of Flags

There are 9 types of flag values: Bool String Int64 Int128 Float64 StringArray Int64Array Int128Array Float64Array. Set a flag's default_value to select one.

The Rust types for each are as follows:

All flags must have default values. This is to ensure that your flags are always the correct type and that your program always has good opinionated defaults.

To get values for each type of flag:

// Single Values
let my_bool = flags.get_bool("my-bool");
let my_string = flags.get_string("my-string");
let my_int64 = flags.get_i64("my-int64");
let my_int128 = flags.get_i128("my-int128");
let my_float64 = flags.get_f64("my-float64");
// Arrays
let my_string_array = flags.get_string_array("my-string-array");
let my_int64_array = flags.get_i64_array("my-int64-array");
let my_int128_array = flags.get_i128_array("my-int128-array");
let my_float64_array = flags.get_f64_array("my-float64-array");