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: "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:

  // Load from config files, environment, and program args
  flags.load(&env::vars().collect(), &env::args().collect())?;
  // Collect positional arguments (non-flags)
  let positionals = flags.positionals();

Get values:

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

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");