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.

JsonSchemaFile

One generated JSON Schema document and the file name it should be written to.

JsoncFormat

JSONC 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.

JsonSchemaError

Error returned while generating or writing JSON Schema files.

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.

generate_html_help

Generate HTML help for a Facet type.

generate_html_help_for_shape

Generate HTML help from a Shape.

generate_json_schemas

Generate one JSON Schema document per config root in T.

open_html_help_file

Open an HTML help file in the user’s default browser.

write_html_help_to_temp_file

Write an HTML help document to a unique file under the system temp directory.

write_json_schemas

Write one JSON Schema file per config root in T to output_dir.