Problem

The library API is currently CLI-shaped: Config::load_smart + get_secrets(profile) + per-secret SecretConfig + secret_resolver::resolve_secret. Consumers that just want "give me this secret" have to replicate what GetCommand::run does in their own codebase.

We hit this when wiring fnox into a Rust agent (bglusman/zeroclawed) — the path of least resistance was a subprocess wrapper around the fnox binary, even though that adds PATH dependency, fork-per-call latency, and an argv-leak surface. Library mode would be strictly better, but the boilerplate to use it is non-trivial.

Proposal

Add a top-level convenience API to fnox::lib.rs:

pub struct Fnox {
    config: Config,
    profile: String,
}

impl Fnox {
    /// Walk up looking for fnox.toml, load it, default profile.
    /// Same upward-search semantics as the binary.
    pub fn discover() -> Result<Self> { ... }

    /// Explicit path + profile.
    pub fn open(config_path: impl AsRef<Path>, profile: &str) -> Result<Self> { ... }

    pub async fn get(&self, key: &str) -> Result<Option<String>> { ... }
    pub async fn set(&mut self, key: &str, value: &str) -> Result<()> { ... }
    pub async fn list(&self) -> Result<Vec<String>> { ... }
}

Implementation can wrap the existing GetCommand::run / SetCommand::run / ListCommand::run logic — minus stdin/stdout/println. The CLI commands then become a thin binary-side adapter over the same Fnox type.

Why now

We have a proof-of-concept in crates/onecli-client/src/fnox_library.rs — get + list work; set deliberately not implemented because that orchestration is the bulk of what should land upstream rather than per consumer.

If you would welcome it, happy to send a PR.

Concrete pain points the convenience API removes

1. Config discovery: every consumer reimplements the upward walk
2. Per-secret SecretConfig lookup: config.get_secrets(profile)?.get(name) boilerplate at every call site
3. Set is gnarly: ~100 LOC of provider/encryption logic. Without an upstream API consumers either subprocess the binary (us) or copy-paste the orchestration (also us, in the future).

Thanks for the work on fnox.