Rust xflags localization is about translating command-line help, error explanations and usage instructions without breaking the executable argument grammar. People searching for xflags! macro localization, parse_or_exit! help, OsString and PathBuf support, UPDATE_XFLAGS regeneration or multilingual CLI testing need to know what can change safely. The description of an option is written for humans; the switch typed into a shell is a public interface. A good translation preserves that distinction and tells readers exactly what to type.
Imagine a harmless project-inspection utility named atlas-inspect. It accepts a required directory path, and –verbose requests extra explanatory output. A Japanese-language guide may translate the purpose and warnings, but it must not silently replace –verbose with a Japanese expression that the parser never declared. Rust xflags favors compact static definitions and fast compilation. That makes it suitable for developer tools, but does not turn its generated help into a complete locale catalog. Each visible string has an owner, and every change needs a corresponding behavioral check.
This guide explains xflags! and parse_or_exit!, source-backed generated structs, the UPDATE_XFLAGS environment variable, help descriptions, positional paths, repeated values, parser errors, terminal encodings and Unicode fixtures. It starts with a working conceptual example, then examines independent failure scenarios, test evidence and a four-week learning plan. The purpose is to help someone use a multilingual command-line program confidently rather than simply count how many English words have been replaced.
At a glance: preserve the interface while translating its explanation
- Keep recognized flags and command tokens stable.
- Review generated help and application messages separately.
- Preserve OS-level path data with appropriate Rust types.
- Regenerate source-backed definitions deliberately.
- Test working commands and deliberate failures on release binaries.
The examples are designed around a read-only inspection task. They do not require modifying a user’s files, and every unsupported feature is treated as a boundary to investigate rather than a promise. Read the syntax overview first, use the investigations to recognize failure patterns, and finish with release tests and independent reader review.
Understand the Rust xflags design
The xflags crate provides macros that declare a command’s switches and positional arguments and produce Rust types and parsing behavior. A declaration can contain cmd, optional, required and repeated clauses. Long switch names are part of that grammar; short aliases may also be declared. Doc comments are a source of human-facing help. The crate’s documentation emphasizes fast compilation and a concise interface, so do not assume it includes the same translation hooks or dynamic registration mechanisms as a more extensive CLI framework. Start by locking the version and reading its syntax reference.
Make a small executable promise
Consider a program that prints which path it would inspect but never reads confidential content or changes files. It has a required path: PathBuf and an optional -v, –verbose switch. A reader should learn that path is actual input, not the literal word PATH, and –verbose is syntax, not a word to translate. Show an example with a real disposable directory and describe exactly what appears. If a sample uses a different command name or writes files, that variation belongs in a separate documented example rather than an implicit assumption.
Distinguish the macro entry points
The xflags! macro can declare named commands and produce generated structs. parse_or_exit! offers a concise top-level parse that handles help and parser failure through its own exit behavior. These are related but distinct ways to integrate the crate. Do not show a generated struct method as if it belongs to an anonymous result, and do not assume the same source-level update process is required in each form. Compile each instructional snippet in isolation before publishing it. The reader should be able to see where their program obtains arguments and where it prints application output.
Keep executable strings separate from descriptive strings
Construct a phrase inventory with six categories: command and subcommand names, switch spellings, placeholders, help prose, parser diagnostics and application diagnostics. Stable command names and switches usually should not be translated because users put them in shell scripts. Placeholders and prose are intended for comprehension, although changing a placeholder can still confuse readers if the replacement resembles a real option. Library-owned errors may not expose direct per-locale replacement points. Be precise about which messages your app controls rather than promising automatic translation for every byte of generated output.
Handle generated source deliberately
xflags can use a src attribute with source-backed generated structs, and the documented UPDATE_XFLAGS variable triggers regeneration of those definitions. This creates a source-management boundary. A translator who changes only a comment may not understand how the final help is assembled; a developer who hand-edits a generated type may lose changes at the next regeneration. Review the diff, verify the artifact was regenerated from the correct declaration, compile and run the command corpus. Do not mix historical generated output with newer macro syntax without clearly identifying the version.
Protect typed values and Unicode paths
PathBuf and OsString protect operating-system argument data that might not be convertible to an ordinary UTF-8 String. Translating human explanations does not require translating filenames, project IDs or file contents. Build tests with spaces, composed and decomposed accents, CJK names, RTL display and, where a platform allows it, non-UTF-8 filename bytes. Record the exact parsed value and the operation performed on it. A correct-looking terminal label does not prove that a path survived an encoding conversion; data identity and visible wording must be verified separately.
Respect xflags-specific limitations
The crate documentation distinguishes its conventions from some GNU parser conventions. In particular, certain bundled short-flag and glued-value forms are not accepted, and the grammar is static rather than dynamically extended at runtime. If a translated example copies an unsupported format from another tool, an otherwise accurate description becomes misleading. Test every exact invocation shown in the final article. When local conventions differ from the parser, explain the accepted grammar rather than disguising the limitation or promising a switch that would require a code change.
Build a release-evidence corpus
For each language and platform, retain an invocation with a valid path, an optional switch, missing required input, unknown flag, invalid typed value, help request and shell-quoted Unicode fixture. Capture stdout, stderr and exit status. Distinguish parser failure from later application validation. Re-run the corpus against the installed release, not only a development checkout. Localization failures often appear when a packaged resource is missing, a stale binary is invoked or a terminal uses different encoding assumptions. The evidence lets a future maintainer compare behavior without guessing.
Review for a real reader
Ask a target-language reader to identify what the command does, which tokens must be copied verbatim and how to recover from a predictable mistake. Give them a clean binary and a set of harmless test fixtures rather than a screenshot. Listen for uncertainty over words such as required, default, replace, remove and inspect. These are high-stakes distinctions because users may interpret them as permissions to alter files. A successful review ends with a command that runs and an explanation that predicted its result.
Thirty-five practical xflags localization investigations
1. Literal flag translated away
A French help page replaces –verbose with a French-looking switch absent from the xflags declaration.
Restore the declared token and translate only the description; introduce an alias through code only after compatibility review.
Run both spellings on a packaged fixture and record which succeeds.
A useful evidence note records the exact argv, selected language, target platform, expected result and observed result. This distinguishes a translation mistake from shell parsing, type conversion or application validation. Do not approve a rewritten example just because it looks more natural; someone should run it from the finished page.
2. Short alias vanishes
A localized guide documents –verbose but omits the registered -v alias, leaving a real interface capability undiscoverable.
Show both spellings and describe their common effect without inventing locale-specific initials.
Execute -v and –verbose separately and compare parsed values.
The practical question is whether a first-time reader can complete the intended task without knowing the original English wording. Keep syntax literal where it is machine-facing, but make human explanations conversational, precise about obligation and clear about consequences. A short sentence that points to a real recovery action is more useful than a long abstract definition.
3. Required path described as optional
A sentence says the directory may be supplied although the parser declares required path: PathBuf.
State the requirement in direct language and include a minimal invocation with a real disposable path.
Run with and without the path; record help, diagnostic and exit status.
This is also a maintenance issue. The next release may change parser behavior or generated help independently from the translated copy. Keep a fixture for the old command and a reviewer note about the ownership of the affected string. That small record makes future regression work faster and helps avoid accidental changes to a stable interface.
4. Placeholder copied literally
The synopsis displays PATH and beginners type the letters PATH, not an actual filename.
Explain the difference between a value hint and literal argument, then show a concrete safe substitution.
Copy the displayed command and inspect the PathBuf received by the program.
Treat locale selection and command grammar as two separate dimensions of the test. Run the same command in an English baseline and one longer translation; check that the same operation occurs, even if messages wrap differently. If behavior varies, first identify whether an intentional localized alias was implemented or whether the documentation has drifted.
5. Default misrepresented
The translation implies verbose mode is enabled by default although the optional Boolean switch is absent.
Describe behavior in both modes and avoid turning stylistic phrasing into a false default.
Compare normal and –verbose output in a controlled test.
A world-facing guide must account for users on different shells and terminals. It should not assume that screen rendering, argument decoding and filesystem representation share one universal encoding. Prefer platform-marked examples and explicitly identify which bytes are to be typed and which phrases exist only to explain a result.
6. Mixed macro APIs
Documentation shows xflags! generated struct code but calls an unrelated parse_or_exit! pattern on it.
Separate the two integration styles, and use methods generated by the exact chosen declaration.
Compile both small examples against the same pinned crate version.
A useful evidence note records the exact argv, selected language, target platform, expected result and observed result. This distinguishes a translation mistake from shell parsing, type conversion or application validation. Do not approve a rewritten example just because it looks more natural; someone should run it from the finished page.
7. Stale generated source
A new xflags declaration is merged without refreshing a src-backed generated definition.
Run the documented UPDATE_XFLAGS flow and review the generated diff rather than hand-editing generated sections.
Regenerate twice, check for unexpected second-pass changes, and compile.
The practical question is whether a first-time reader can complete the intended task without knowing the original English wording. Keep syntax literal where it is machine-facing, but make human explanations conversational, precise about obligation and clear about consequences. A short sentence that points to a real recovery action is more useful than a long abstract definition.
8. Source text differs from installed help
A translated doc comment appears in Git but the release binary still prints the old phrase.
Check artifact selection, compilation, macro expansion and any stale build cache before assuming the locale catalog failed.
Run –help in the build directory and again from the installed path.
This is also a maintenance issue. The next release may change parser behavior or generated help independently from the translated copy. Keep a fixture for the old command and a reviewer note about the ownership of the affected string. That small record makes future regression work faster and helps avoid accidental changes to a stable interface.
9. Unknown locale produces empty strings
An application-level catalog has no translation for a key and renders a blank recovery instruction.
Supply a readable fallback and document which strings belong to the app rather than the library.
Test an unsupported locale and deliberately missing key.
Treat locale selection and command grammar as two separate dimensions of the test. Run the same command in an English baseline and one longer translation; check that the same operation occurs, even if messages wrap differently. If behavior varies, first identify whether an intentional localized alias was implemented or whether the documentation has drifted.
10. Numeric input translated incorrectly
A new numeric option accepts Rust FromStr values, but the guide presents a locale-formatted number that cannot parse.
Keep accepted input syntax literal and translate its explanation, not its value grammar.
Test integer, decimal-comma, text and overflow fixtures.
A world-facing guide must account for users on different shells and terminals. It should not assume that screen rendering, argument decoding and filesystem representation share one universal encoding. Prefer platform-marked examples and explicitly identify which bytes are to be typed and which phrases exist only to explain a result.
11. Non-UTF-8 path damaged
A path is converted through lossy UTF-8 before reaching the operation that needs its original identity.
Retain OsString or PathBuf until an actual filesystem boundary and render lossily only for labeled diagnostics.
Where supported, create a non-UTF-8 filename and compare exact identity.
A useful evidence note records the exact argv, selected language, target platform, expected result and observed result. This distinguishes a translation mistake from shell parsing, type conversion or application validation. Do not approve a rewritten example just because it looks more natural; someone should run it from the finished page.
12. Whitespace path split by shell
A sample path contains spaces but lacks quoting, so two positional arguments reach xflags.
Add shell-specific quoting and explain which layer handles tokenization before parsing.
Test the quoted and unquoted examples in each supported shell.
The practical question is whether a first-time reader can complete the intended task without knowing the original English wording. Keep syntax literal where it is machine-facing, but make human explanations conversational, precise about obligation and clear about consequences. A short sentence that points to a real recovery action is more useful than a long abstract definition.
13. RTL punctuation shifts flag appearance
An Arabic paragraph visually rearranges hyphens beside a literal long switch.
Isolate code tokens and put translated explanatory phrases in separate runs of text.
Copy and paste the rendered invocation, not merely the source Markdown.
This is also a maintenance issue. The next release may change parser behavior or generated help independently from the translated copy. Keep a fixture for the old command and a reviewer note about the ownership of the affected string. That small record makes future regression work faster and helps avoid accidental changes to a stable interface.
14. Combining accents break alignment
Help columns depend on byte width and an accented translation wraps under an unrelated option.
Choose readable reflow instead of naive width assumptions or fixed-byte truncation.
Inspect precomposed and decomposed accents at narrow and wide widths.
Treat locale selection and command grammar as two separate dimensions of the test. Run the same command in an English baseline and one longer translation; check that the same operation occurs, even if messages wrap differently. If behavior varies, first identify whether an intentional localized alias was implemented or whether the documentation has drifted.
15. Emoji copied into command
An educational callout places a decorative emoji at the start of a code block.
Keep decoration outside copyable commands and provide a clean standalone example.
Paste the complete rendered code block into a shell without removing characters.
A world-facing guide must account for users on different shells and terminals. It should not assume that screen rendering, argument decoding and filesystem representation share one universal encoding. Prefer platform-marked examples and explicitly identify which bytes are to be typed and which phrases exist only to explain a result.
16. Unsupported bundled flags
An imported guide teaches -abc for multiple short switches, even though xflags uses different conventions.
Replace with tested switch spellings and mention the documented parser limitation.
Run each example in the actual crate version.
A useful evidence note records the exact argv, selected language, target platform, expected result and observed result. This distinguishes a translation mistake from shell parsing, type conversion or application validation. Do not approve a rewritten example just because it looks more natural; someone should run it from the finished page.
17. Unsupported glued value
A tutorial suggests -fVALUE as shorthand for a value-taking flag without verifying xflags support.
Teach the accepted separated-value grammar and avoid generalizing from GNU-style tools.
Compare -f VALUE and -fVALUE on an isolated fixture.
The practical question is whether a first-time reader can complete the intended task without knowing the original English wording. Keep syntax literal where it is machine-facing, but make human explanations conversational, precise about obligation and clear about consequences. A short sentence that points to a real recovery action is more useful than a long abstract definition.
18. Dynamic flag registration assumed
A plugin guide promises runtime addition of flags although the xflags grammar is static.
Treat plugin configuration as data or choose another parser when dynamic grammar is essential.
Install a dummy plugin and verify the displayed help matches compiled syntax.
This is also a maintenance issue. The next release may change parser behavior or generated help independently from the translated copy. Keep a fixture for the old command and a reviewer note about the ownership of the affected string. That small record makes future regression work faster and helps avoid accidental changes to a stable interface.
19. Repeated value described as singular
A repeated –include is documented as accepting only one input, hiding a supported capability.
State cardinality explicitly and illustrate two separate invocations of the switch.
Inspect the parsed vector or repetition count.
Treat locale selection and command grammar as two separate dimensions of the test. Run the same command in an English baseline and one longer translation; check that the same operation occurs, even if messages wrap differently. If behavior varies, first identify whether an intentional localized alias was implemented or whether the documentation has drifted.
20. Optional value declared mandatory
Translation changes a gentle optional setting into an instruction that suggests the command cannot run without it.
Explain the omission behavior and default when one exists.
Run with and without the option and compare outputs.
A world-facing guide must account for users on different shells and terminals. It should not assume that screen rendering, argument decoding and filesystem representation share one universal encoding. Prefer platform-marked examples and explicitly identify which bytes are to be typed and which phrases exist only to explain a result.
21. Conflicting alias added
A new local-language short switch collides with another registered flag.
Audit the complete grammar before accepting aliases and consider keeping established ASCII names.
Compile with the candidate alias and exercise the entire switch set.
A useful evidence note records the exact argv, selected language, target platform, expected result and observed result. This distinguishes a translation mistake from shell parsing, type conversion or application validation. Do not approve a rewritten example just because it looks more natural; someone should run it from the finished page.
22. Absent and empty values conflated
The guide treats a missing argument and an explicitly empty quoted string as equivalent.
Explain whether xflags, the shell or later validation distinguishes the states.
Test no value, empty value and whitespace-only value.
The practical question is whether a first-time reader can complete the intended task without knowing the original English wording. Keep syntax literal where it is machine-facing, but make human explanations conversational, precise about obligation and clear about consequences. A short sentence that points to a real recovery action is more useful than a long abstract definition.
23. Diagnostics expose internal detail
An application prints a debug representation and Rust source paths instead of understandable recovery guidance.
Use a stable public error category and localized next action where the application owns the output.
Trigger an invalid value and ask a reader how they would correct it.
This is also a maintenance issue. The next release may change parser behavior or generated help independently from the translated copy. Keep a fixture for the old command and a reviewer note about the ownership of the affected string. That small record makes future regression work faster and helps avoid accidental changes to a stable interface.
24. Brittle whitespace snapshots
A test fails because terminal width changes line breaks while commands and meanings remain identical.
Assert semantic tokens and important messages separately from presentation details.
Render help at sixty and one hundred columns.
Treat locale selection and command grammar as two separate dimensions of the test. Run the same command in an English baseline and one longer translation; check that the same operation occurs, even if messages wrap differently. If behavior varies, first identify whether an intentional localized alias was implemented or whether the documentation has drifted.
25. Packaged locale resource omitted
The repository includes translated application files but the release archive only carries English resources.
Audit the packaging manifest and test from a clean extracted installation.
Run help and one controlled error with no checkout paths.
A world-facing guide must account for users on different shells and terminals. It should not assume that screen rendering, argument decoding and filesystem representation share one universal encoding. Prefer platform-marked examples and explicitly identify which bytes are to be typed and which phrases exist only to explain a result.
26. Help and failure status mixed
A normal –help request and an unknown switch are described as identical exit paths.
Document success and error separately, including stdout, stderr and status.
Capture all three for help, missing input and unknown flags.
A useful evidence note records the exact argv, selected language, target platform, expected result and observed result. This distinguishes a translation mistake from shell parsing, type conversion or application validation. Do not approve a rewritten example just because it looks more natural; someone should run it from the finished page.
27. Machine token translated as an enum label
A format option accepts json but the guide lists only its translated descriptive name.
Keep accepted enum tokens literal and explain their meanings nearby.
Execute every advertised value and confirm case sensitivity.
The practical question is whether a first-time reader can complete the intended task without knowing the original English wording. Keep syntax literal where it is machine-facing, but make human explanations conversational, precise about obligation and clear about consequences. A short sentence that points to a real recovery action is more useful than a long abstract definition.
28. Hierarchy shown incorrectly
A child command’s option is presented as a root-level flag in a translated synopsis.
Draw the actual command tree and preserve command placement in examples.
Run parent and child help as well as an intentionally wrong-level invocation.
This is also a maintenance issue. The next release may change parser behavior or generated help independently from the translated copy. Keep a fixture for the old command and a reviewer note about the ownership of the affected string. That small record makes future regression work faster and helps avoid accidental changes to a stable interface.
29. Platform paths generalized
A Windows-style drive path is shown as universal, and a Unix user cannot run the sample.
Tag platform-specific examples and use PathBuf to protect actual path values.
Use matching disposable paths on each supported operating system.
Treat locale selection and command grammar as two separate dimensions of the test. Run the same command in an English baseline and one longer translation; check that the same operation occurs, even if messages wrap differently. If behavior varies, first identify whether an intentional localized alias was implemented or whether the documentation has drifted.
30. Framework upgrade changes messages
An xflags upgrade changes generated headings or errors, breaking snapshots mistaken for translation changes.
Compare pinned old and new dependency behavior before revising guidance.
Replay the command corpus against both builds.
A world-facing guide must account for users on different shells and terminals. It should not assume that screen rendering, argument decoding and filesystem representation share one universal encoding. Prefer platform-marked examples and explicitly identify which bytes are to be typed and which phrases exist only to explain a result.
31. An inspect tool is called a repair tool
A localized caption says the example modifies files when it only prints selected settings.
Choose verbs matching observable side effects and give warnings for genuinely destructive operations.
Run with read-only fixtures and observe whether any path is modified.
A useful evidence note records the exact argv, selected language, target platform, expected result and observed result. This distinguishes a translation mistake from shell parsing, type conversion or application validation. Do not approve a rewritten example just because it looks more natural; someone should run it from the finished page.
32. User data is machine-translated
A filename or project ID is translated as ordinary prose before being supplied to the parser.
Preserve identifiers and paths exactly while translating surrounding instructions.
Create two distinguishable non-ASCII filenames and verify selection identity.
The practical question is whether a first-time reader can complete the intended task without knowing the original English wording. Keep syntax literal where it is machine-facing, but make human explanations conversational, precise about obligation and clear about consequences. A short sentence that points to a real recovery action is more useful than a long abstract definition.
33. Completion claims unsupported integration
The guide promises automatic completion in all shells without any actual completion installation.
Separate xflags parsing from external completion artifacts and identify the tool that generates suggestions.
Test suggestions and inserted tokens in each supported shell.
This is also a maintenance issue. The next release may change parser behavior or generated help independently from the translated copy. Keep a fixture for the old command and a reviewer note about the ownership of the affected string. That small record makes future regression work faster and helps avoid accidental changes to a stable interface.
34. Interactive prompts misattributed
A guide calls an interactive selector a built-in xflags feature when an unrelated library provides it.
Name each responsible component and review its own cancellation and language behavior.
Run both interactive and piped noninteractive commands.
Treat locale selection and command grammar as two separate dimensions of the test. Run the same command in an English baseline and one longer translation; check that the same operation occurs, even if messages wrap differently. If behavior varies, first identify whether an intentional localized alias was implemented or whether the documentation has drifted.
35. Backward compatibility lost in docs
A documentation revision changes every ASCII switch token because the team searches and replaces English words.
Protect runnable snippets with regression tests and add aliases only as deliberate interface changes.
Replay the previous release’s commands on the new binary.
A world-facing guide must account for users on different shells and terminals. It should not assume that screen rendering, argument decoding and filesystem representation share one universal encoding. Prefer platform-marked examples and explicitly identify which bytes are to be typed and which phrases exist only to explain a result.
Frequently asked questions
Does xflags automatically translate help into every language?
The crate can generate help from grammar and descriptions, but it should not be treated as a complete runtime localization system. Application catalogs and translated error context require explicit engineering and tests.
What is the difference between xflags! and parse_or_exit!?
xflags! supports named generated command types, while parse_or_exit! offers a concise top-level parse pattern. They are related macros but their integration and generated artifacts should not be confused.
Can I rename –verbose in a translation?
Not by editing a sentence. The switch is executable syntax, and aliases must be added to the grammar and checked against existing options and scripts.
Why should paths use PathBuf or OsString?
Those types can preserve operating-system arguments that are not valid UTF-8. Translating help should not alter the identity of user-supplied paths or identifiers.
When should UPDATE_XFLAGS be used?
Follow the documented source-backed generation workflow when the project uses src-generated definitions. Review the regenerated source and verify it compiles before release.
Can I use GNU bundled short switches?
Do not assume so. xflags documents limitations relative to some GNU parser conventions. Every example should be tested against the installed version.
How should Unicode be tested?
Use fixtures with spaces, accented names, CJK characters, RTL explanatory text and platform-appropriate non-UTF-8 arguments where possible. Compare parsed values, streams and status.
What is the simplest release criterion?
A target-language user can identify literal tokens, run the safe example, understand the output and recover from a predictable invalid invocation without guessing.
A four-week route from first example to release
Week 1: baseline and grammar inventory
Select one small command. Record its accepted options, help output, working example, and missing-input and unknown-option failures. Label each visible string as literal grammar, displayed placeholder, built-in parser text or application-owned prose. Choose two target languages, including one with longer phrases. Compile the example in a fresh environment, then prepare fixtures with a simple path, a path with spaces and a non-ASCII filename. Write down what each command should do before translating a sentence. The baseline becomes a safety net: when the help later changes, the team can compare behavior rather than relying on recollection.
Week 2: translated explanations and runnable examples
Translate descriptions, purpose statements and recovery instructions in context. Keep switch names unchanged unless an explicit compatibility decision authorizes an alias. Review the words for required, optional, repeated, default and invalid with particular care. Execute every command shown in the localized guide as a reader would copy it from the rendered page. Compare the actual output with the written promise, including whether the harmless inspection sample modifies anything. Use a phrase ledger for the application-owned strings and a separate record for library-generated messages that cannot be replaced directly.
Week 3: Unicode, errors and distributed builds
Test composed accents, CJK strings, right-to-left explanations and filesystem paths that contain spaces. Where supported, include non-UTF-8 path data rather than assuming every argument can become a String. Deliberately supply an invalid typed value, omit a required path and request help. Capture stdout, stderr and exit status. Rebuild any source-backed generated structures through the documented update workflow, review the diff, and run all fixtures from the packaged binary in a clean environment. Test narrow terminal widths without penalizing legitimate line wrapping.
Week 4: reader acceptance and release ownership
Give a target-language reader three tasks: find the correct command, run a successful safe example and repair one predictable mistake. Observe whether they understand placeholders, switch spelling and real effects. Rework ambiguous passages and re-run the corresponding commands. Assign an owner for app-level locale resources and a separate reviewer for any change to command grammar. Compare results to the baseline and store the tested crate version, shell, operating system, invocation and outcome with the published guide. This makes the localization maintainable rather than a one-off translation event.
Release acceptance and next reading
A useful Rust xflags guide is not measured by how many strings have changed language. It should let a reader predict a command’s effects, identify its required input, invoke stable flags, survive a failure and continue safely. Keep typed paths intact and help text meaningful. Check the exact dependency version whenever the generated interface changes. The parser is responsible for recognized syntax; the application remains responsible for telling people what its own work means.