Crate figue 

figue - Layered Configuration for Rust

figue provides type-safe, layered configuration parsing with support for:

• CLI arguments - Standard command-line argument parsing
• Environment variables - Configure apps via environment
• Config files - JSON, and more formats via plugins
• Defaults from code - Compile-time defaults

Built on facet reflection, figue uses derive macros to generate parsers at compile time with zero runtime reflection overhead.

Quick Start

For simple CLI-only parsing, use from_slice or from_std_args:

use facet::Facet;
use figue::{self as args, FigueBuiltins};

#[derive(Facet, Debug)]
struct Args {
    /// Enable verbose output
    #[facet(args::named, args::short = 'v', default)]
    verbose: bool,

    /// Input file to process
    #[facet(args::positional)]
    input: String,

    /// Standard CLI options (--help, --version, --completions)
    #[facet(flatten)]
    builtins: FigueBuiltins,
}

// Parse from a slice (useful for testing)
let args: Args = figue::from_slice(&["--verbose", "input.txt"]).unwrap();
assert!(args.verbose);
assert_eq!(args.input, "input.txt");

Layered Configuration

For applications that need config files and environment variables, use the builder API with Driver:

use facet::Facet;
use figue::{self as args, builder, Driver};

#[derive(Facet, Debug)]
struct Args {
    /// Application configuration
    #[facet(args::config, args::env_prefix = "MYAPP")]
    config: AppConfig,
}

#[derive(Facet, Debug)]
struct AppConfig {
    /// Server port
    #[facet(default = 8080)]
    port: u16,

    /// Server host
    #[facet(default = "localhost")]
    host: String,
}

// Build layered configuration
let config = builder::<Args>()
    .unwrap()
    .cli(|cli| cli.args(["--config.port", "3000"]))
    .build();

let output = Driver::new(config).run().into_result().unwrap();
assert_eq!(output.value.config.port, 3000);
assert_eq!(output.value.config.host, "localhost"); // from default

Subcommands

figue supports subcommands via enum types:

use facet::Facet;
use figue::{self as args, FigueBuiltins};

#[derive(Facet, Debug)]
struct Cli {
    #[facet(args::subcommand)]
    command: Command,

    #[facet(flatten)]
    builtins: FigueBuiltins,
}

#[derive(Facet, Debug)]
#[repr(u8)]
enum Command {
    /// Build the project
    Build {
        /// Build in release mode
        #[facet(args::named, args::short = 'r')]
        release: bool,
    },
    /// Run the project
    Run {
        /// Arguments to pass through
        #[facet(args::positional)]
        args: Vec<String>,
    },
}

let cli: Cli = figue::from_slice(&["build", "--release"]).unwrap();
match cli.command {
    Command::Build { release } => assert!(release),
    Command::Run { .. } => unreachable!(),
}

Attribute Reference

figue uses #[facet(...)] attributes to configure parsing behavior:

Attribute	Description
args::positional	Mark field as positional argument
args::named	Mark field as named flag (–flag)
args::short = 'x'	Add short flag (-x)
args::counted	Count occurrences (-vvv = 3)
args::subcommand	Mark field as subcommand selector
args::config	Mark field as layered config struct
args::env_prefix = "X"	Set env var prefix for config
args::help	Mark as help flag (exits with code 0)
args::version	Mark as version flag (exits with code 0)
args::completions	Mark as shell completions flag
flatten	Flatten nested struct fields
default / default = x	Provide default value
rename = "x"	Rename field in CLI/config
sensitive	Redact field in debug output

Entry Points

• from_std_args - Parse from std::env::args() (CLI-only)
• from_slice - Parse from a string slice (CLI-only, good for testing)
• builder - Start building layered configuration (CLI + env + files)

For most CLI applications, start with FigueBuiltins flattened into your args struct to get --help, --version, and --completions for free.

Re-exports

pub use crate::completions::Shell;

pub use crate::completions::generate_completions_for_shape;

Modules

completions

Shell completion script generation for command-line interfaces.

Structs

ArgsErrorWithInput

An args parsing error, with input info, so that it can be formatted nicely

ConfigFormatError

Error returned when parsing a config file fails.

Driver

Primary driver type that orchestrates parsing and validation.

DriverOutcome

The result of running the figue driver — either a parsed value or an early exit.

DriverOutput

Successful driver output: a typed value plus an execution report.

DriverReport

Full report of the driver execution.

ExtractError

Error returned when extraction fails.

ExtractMissingField

Information about a missing required field during extraction.

FigueBuiltins

Standard CLI builtins that can be flattened into your Args struct.

FormatRegistry

A registry of config file formats.

HelpConfig

Configuration for help text generation.

JsonFormat

JSON config file format.

MockEnv

Environment source backed by a map (for testing).

Enums

ArgsErrorKind

An error kind for argument parsing.

Attr

Args attribute types for field configuration.

ConfigValue

A configuration value with full provenance tracking at every level.

DriverError

Reason the driver did not produce a parsed value.

Traits

ConfigFormat

Trait for config file format parsers.

Functions

builder

Start configuring an args/config parser for a given type.

from_slice

Parse command-line arguments from a slice.

from_std_args

Parse command-line arguments from std::env::args().

generate_help

Generate help text for a Facet type.

generate_help_for_shape

Generate help text from a Shape.