argenv
A declared, typed, machine-readable contract for a program's invocation surface — argv and envp.
pub const LOG_LEVEL: = Input ;
One declaration is simultaneously the contract entry, the typed accessor, and a compile-checked symbol. Because there is only one artifact, the published contract cannot drift from the code that reads the value.
--log-level and APP_LOG_LEVEL are not two settings. They are one setting with two
doors — so they share a type, a domain, a default, and a description.
And because the surface is written down, the failures that are normally silent become reportable:
$ APP_LOG_LEVL=warn argenv lint myapp.argenv.json -- --hud fps,bogus --hdr=yes
error: hud contains unknown token `bogus`; accepted: fps, gpuload, memory
error: --hdr takes no value
error: licence_key is required; supply it with --licence-key or APP_KEY
error: APP_LOG_LEVL is not declared; did you mean APP_LOG_LEVEL?
That runs against a published contract document, so it works for programs written in any language — including ones that never adopted this crate.
How strict, and who decides
A misspelled flag or variable is an error by default, and so is a flag given to a subcommand it
does not belong to (delete --dry-run, where --dry-run is create's): the intent is clear and
wrong, and carrying on would run the program without the setting the user asked for. A program that has a
reason to be more forgiving (a wrapper that forwards flags it does not declare, a tool that runs
in environments it does not control) says so once, in its own code:
use ;
// the previous behaviour: typos are surfaced, never fatal
let resolved = parse_and_lint_with;
// or one kind at a time: unknown_flags, unknown_variables, out_of_scope_flags, deprecated
let policy = default.unknown_flags;
On the command line, argenv lint --lenient PATH does the same. A bad value (out of its domain,
unparseable, missing) is an error under every policy: there is no usable reading of it.
Everything else, derived
Because the surface is written down once, what a program ships about it can be derived instead of maintained by hand and forgotten. From a contract (the Rust declaration, or a published document from a program in any language):
$ argenv completions bash myapp.argenv.json > /usr/share/bash-completion/completions/myapp
$ argenv completions zsh myapp.argenv.json > /usr/share/zsh/site-functions/_myapp
$ argenv completions fish myapp.argenv.json > /usr/share/fish/vendor_completions.d/myapp.fish
$ argenv completions nushell myapp.argenv.json > /usr/share/nushell/vendor/autoload/myapp.nu
$ argenv man myapp.argenv.json --date 2026-10-23 | gzip -9n > /usr/share/man/man1/myapp.1.gz
A flag scoped to a subcommand is offered only after that subcommand; enumerated values are
completed; path-valued inputs complete file names; --flag and --no-flag both appear.
Programs that link the library call argenv_resolve::generate themselves and can add what a
document cannot carry (a one-line summary per subcommand, exit statuses, see-also pages). The
whole adapter is a description of the program and a pass-through of its records, so a
completions SHELL and a man subcommand are a few lines, and nothing is written by hand:
use ;
let program = Program ;
print!;
print!;
Some values only the program knows when Tab is pressed: the names of files in the current
folder, of records in a store. asked says which positional they belong to and how to ask the
program for them; the completions run it then and offer each line it prints (its errors are
discarded, and a failure offers nothing):
use Asked;
// `myapp run <Tab>` offers what `myapp list-names` prints, in every shell.
let program = Program ;
The output is shell code, so the contract is treated as untrusted: names and values that are
not plain tokens are left out (or, for the program and subcommand names, refused), and free text
is quoted for the shell it lands in. A summary such as '; rm -rf ~ # is displayed, never
executed. The generators are tested in real bash, zsh (through a pseudo-terminal, pressing Tab),
fish and nushell, and the man page through groff.
The problem
A program is handed two things when it starts: an argument vector and an environment. Both are interfaces. Both are depended upon by scripts, container images, CI pipelines, launchers and people. And almost no program declares either one in a form anything can check.
The names, the types, the legal values and the defaults live in a README table someone updates by hand — or in nothing at all, as a string literal compared against another string literal. Nobody validates them:
- Misspell a flag and you get an error, or worse, silence. Misspell a variable and it is always silence: no warning, no exit code, just the wrong behaviour discovered later.
- Pass
--verbosity=maybewhere only0/1are understood and you get whatever the parsing code happens to do with garbage. - Ask "which inputs does this program actually accept?" and there is no answer short of reading its source.
- Ask "why is this value what it is?" — flag, variable, or default? — and nothing can tell you.
Config files, by contrast, mostly do have schema culture: editor settings, package manifests, deployment descriptors all routinely ship JSON Schema. The surfaces that are universally undeclared are the two the operating system hands you. That is the gap this project names.
The approaches, and why this one
1. Write better documentation. The status quo. Prose has no types, cannot be validated, cannot be consumed by tooling, and — decisively — drifts the moment anyone forgets to update it. Documentation reports on a contract; it is never the contract.
2. Extract declarations from source. Grep for getenv and flag literals. Recovers
names and nothing else: no types, no legal values, no defaults, no meaning. Breaks when a
project reshapes its parsing. A floor, not a contract.
3. Instrument at runtime. Record what was asked for. Authoritative for what it observed, structurally blind to everything a particular run did not touch.
4. Write a separate schema file. Real and useful — this is what typed-dotenv tools and
CLI description formats do. But a sidecar is a second artifact, and two artifacts drift:
nothing forces the schema and the getenv call to agree.
5. Declare it in code, as the accessor itself. ← this project. The declaration is
what the program actually reads, so it cannot drift. It carries types, domains, defaults,
stability, deprecation and provenance, it is const so violations are compile errors, and
it projects to a language-neutral JSON document other stacks can consume.
The design is a middle ground on purpose:
- Richer than a text schema, cheaper than a framework. No macros to learn, no registry
to boot, no runtime. An input is a
conststruct literal. - Adoptable one input at a time. A key, a type and one binding are all that is required. A harvested name is a valid entry, so a project can start with a list and let contributors fill in meaning through one-line pull requests.
- Neutral about who owns the truth. A project that adopts nothing can still have its surface described externally, in the same format, merged by key.
What you get
| Artifact | What it is |
|---|---|
argenv crate |
The typed model: declare inputs, resolve an invocation, read values typed. |
argenv-contract.v1.schema.json |
The cross-language contract, derived from the model and enriched. |
argenv CLI |
schema emits it; check validates documents; lint checks a real invocation; usage renders help. |
| The contract API | Schema and examples as plain GET endpoints, for any language or CI job. |
Guarantees
- A misspelled key or a wrongly typed read is a compile error.
- Absent and invalid are both
None— an invalid value can never masquerade as a default. - Arity is derived from the type, never declared: a boolean flag takes no value, anything else takes one. The derived value is still written out explicitly in the published contract, so no other language has to re-derive it.
- Every resolved value carries where it came from — argument, environment, or default.
- Two inputs cannot claim the same key, variable or flag; a collision is caught, not shadowed.
- An input that declares no binding at all — one nothing could ever set — is rejected.
sincecan never exceed the version being built;reviewedcan never be in the future.- A deprecated input must carry migration details, and its replacement is a compile-checked reference: rename the successor and the reference stops compiling.
- Checking an invocation reports misspelled flags and variables with suggestions,
out-of-domain values, unknown list tokens, missing required inputs and deprecated ones in
use — while leaving the rest of the environment alone, so
PATHis never mentioned.
Install
A program that only publishes its contract needs argenv; one that also reads its own
arguments and environment through it, or checks an invocation, uses argenv-resolve.
Use
use *;
;
let args: = args.skip.collect;
let invocation = Invocation ;
// Resolve once; read typed values as often as you like.
let resolved = invocation.resolve;
let hdr: = HDR.get_from_or_default;
assert_eq!; // why it is what it is
// Report anything the invocation got wrong.
for finding in lint
See crates/argenv-resolve/examples/consumer.rs for a
complete model covering both bindings, custom domain types, negation, repetition and
deprecation.
For something small and familiar, minigrep.rs is
the Rust Book's chapter 12 grep with its two arguments and its IGNORE_CASE variable declared
once: the same setting through a flag or the variable, a typo caught with a suggestion, and the
usage text generated from the declaration.
The test suite doubles as the specification: every rule is one test, named as a sentence.
tests/scenario.rs walks the whole life of a contract —
declared, published, read back by an unrelated consumer, and used to catch a broken launch —
and is the fastest way to see the shape of the project. cargo test runs all of it,
including whether the schema committed here is still the one the model produces.
Adopting it in a program that has never declared anything
- Harvest the names. A key, a type and one binding is a valid record. You now have a list where there was nothing.
- Route reads through the declarations. Each converted site turns a stringly lookup into a compile-checked, typed read with known provenance.
- Enrich by pull request.
summary,example,allowed,reviewedare one-line additions, reviewable by anyone who knows what an input does. - Emit and publish. Wire
schemaandcheckinto CI so the contract is verified on every commit and ships as a build artifact.
No step requires the previous one to be complete.
Project layout
crates/argenv/ the model (published to crates.io)
crates/argenv-resolve/ reading and linting an invocation against the model (published)
crates/argenv-cli/ schema emission, document validation, invocation checking
schema/ the generated JSON Schema contract
api/ static GET endpoints (schema + examples)
ARCHITECTURE.md contract propagation and governance
Status
The model, the schema, the tooling, and the completions and man page derived from a contract are complete and tested.
The contract format is versioned (contract_version) and evolves additively: new
fields are optional, records accept properties they do not recognise, and readers ignore
them. A consumer pinned to this version keeps working against documents produced by a later
one — enforced by tests, not promised in prose.
Planned, and deliberately not built yet: a cfg binding for configuration-file paths, and
generated model modules for other languages. Both consume Record and need no change to the
model.
License
MIT OR Apache-2.0, at your option.