CLI: A Reliable Interface · 25 min · free lesson

Resolve Configuration Once

Apply explicit configuration precedence.

Core idea

Choose flag over environment over default, then validate the chosen value.

Diagram for Resolve Configuration Once: a Rust code example flows to the lesson rule and the key observation.
The worked implementation exercises apply explicit configuration precedence. Its tests demonstrate the stated finite contract.

Understand it

Configuration can come from a flag, an environment variable or a default. Establish precedence before parsing so a broken lower-priority value does not override an explicit valid flag. Conversely, do not silently fall back when the chosen highest-priority value is malformed: the operator needs to know their request was rejected.

The list limit must be an integer from 1 to 100. Absence selects 20, but an explicitly empty string is an invalid value, not absence. In production, report which configuration source failed without printing secrets. Invocation environment in Crabrix is passed only to the student program; it never changes the compiler or dependency build-script environment. This prevents an educational flag from accidentally reconfiguring the toolchain.

The route project is Task Ledger: first keep a reproducible source history, then expose its data through a CLI and HTTP boundary, persist it in SQL, diagnose failures and prepare a release. This lesson owns one contract in that project. Run the worked example before changing the starter and explain which input makes the tempting shortcut fail.

Terminal practice: Run env TASK_LIMIT=7 cargo run -- list. Compare with env TASK_LIMIT=bad cargo run -- list.

The compiler lab is independent of the reading question. Edit solution.rs; the app supplies a separate caller with normal, empty and adversarial inputs. A successful unchanged demonstration does not prove your implementation. After the lab, apply the same contract to the route companion project. Its README separates the on-device adapter from the desktop Cargo/TCP profile.

Read the code

pub fn limit(
    flag: Option<&str>,
    environment: Option<&str>,
) -> Result<u16, String> {
    let raw = flag.or(environment).unwrap_or("20");
    match raw.parse::<u16>() {
        Ok(n) if (1..=100).contains(&n) => Ok(n),
        _ => Err("invalid limit".to_owned()),
    }
}

fn main() {
    assert_eq!(limit(Some("7"), Some("bad")), Ok(7), "case 1");
    assert_eq!(limit(None, None), Ok(20), "case 2");
    assert_eq!(limit(None, Some("100")), Ok(100), "case 3");
    assert_eq!(
        limit(Some(""), Some("5")),
        Err("invalid limit".to_owned()),
        "case 4"
    );
    assert_eq!(
        limit(Some("0"), None),
        Err("invalid limit".to_owned()),
        "case 5"
    );
    assert_eq!(
        limit(None, Some("101")),
        Err("invalid limit".to_owned()),
        "case 6"
    );
    println!("worked example passed");
}

The worked implementation exercises apply explicit configuration precedence. Its tests demonstrate the stated finite contract.

Practice starter

pub fn limit(flag: Option<&str>, environment: Option<&str>) -> Result<u16,String> {
    todo!("implement the contract")
}

Open local example in Playground ↗

Try it

Choose flag, otherwise environment, otherwise 20. Parse the chosen string as u16 and accept only 1..=100; return invalid limit on failure. Keep the public signature. Open the compiler lab and edit solution.rs; do not edit the private verification caller.

What success looks like: The separate caller accepts the changed solution and rejects unchanged TODO, a wrong implementation and a printed success message.

Check your understanding

An explicit valid flag overrides a malformed environment value. What should happen?

Reveal the answer
  1. Reject the unrelated lower-priority value
  2. Always use the default
  3. Use the flag

Precedence decides the authoritative value before validation; invalid authoritative input must still fail.

Go deeper

Common misconception: Reject the unrelated lower-priority value

Choose flag over environment over default, then validate the chosen value.

  1. Identify the boundary: Apply explicit configuration precedence. Write down its accepted inputs and observable output.
  2. Exercise the failure: Precedence decides the authoritative value before validation; invalid authoritative input must still fail.
  3. Check the independent caller: Choose flag, otherwise environment, otherwise 20. Parse the chosen string as u16 and accept only 1..=100; return invalid limit on failure.

Transfer challenge: Apply this contract to Task Ledger, introduce the failure described in the lesson, and show the failing check before fixing it.

Connections

  • Parse a CLI Contract: Preserve arguments and reject ambiguous input
  • Process Bounded Standard Input: Treat input as data with resource limits