Add Command::next_env_prefix for env variable prefixing by veeceey · Pull Request #6281 · clap-rs/clap

veeceey · 2026-02-23T03:56:44Z

Adds Command::next_env_prefix which sets a prefix that gets prepended to all subsequent arg env variable names during build. Modeled directly after next_help_heading as @epage suggested in #3221.

How it works:

Command::next_env_prefix("MYAPP") sets the prefix for all future args
When an arg has both an env name and an inherited prefix, the env name gets rewritten to MYAPP_<NAME> during _build_self
The prefix can be reset with next_env_prefix(None::<&str>)
CLI arguments still override env values as expected

The env prefix is stored on each Arg (via env_prefix field) during arg_internal, same pattern as help_heading. The actual name rewriting happens during _build_self which keeps help generation and env lookup unchanged.

Requires both env and string features since we need runtime string construction for the prefixed names.

let cmd = Command::new("myapp")
    .next_env_prefix("MYAPP")
    .arg(Arg::new("config").long("config").env("CONFIG"));
// env var will be MYAPP_CONFIG

Closes #3221

veeceey · 2026-02-23T03:56:56Z

Test results (all env tests pass, including 5 new env_prefix tests):

running 30 tests
test env::env_prefix_does_not_affect_args_without_env ... ok
test env::env_os ... ok
test env::env ... ok
test env::env_bool_literal ... ok
test env::env_prefix_cli_overrides_env ... ok
test env::env_prefix_basic ... ok
test env::env_prefix_multiple_args ... ok
test env::env_prefix_reset ... ok
test env::multiple_no_delimiter ... ok
test env::multiple_one ... ok
test env::multiple_three ... ok
test env::no_env ... ok
test env::no_env_no_takes_value ... ok
test env::opt_user_override ... ok
test env::not_possible_value ... ok
test env::positionals ... ok
test env::positionals_user_override ... ok
test env::possible_value ... ok
test env::value_parser ... ok
test env::value_parser_invalid ... ok
test env::with_default ... ok
test env::value_parser_output ... ok
test help_env::show_env ... ok
test help_env::hide_env ... ok
test help_env::hide_env_vals_flag ... ok
test help_env::hide_env_flag ... ok
test help_env::hide_env_vals ... ok
test help_env::show_env_flag ... ok
test help_env::show_env_vals ... ok
test help_env::show_env_vals_flag ... ok

test result: ok. 30 passed; 0 failed; 0 ignored; 0 measured; 916 filtered out

epage · 2026-02-23T16:12:33Z

We recommend that commits represent how things should be reviewed and merged and not how they were developed. Having fixup commits means they are not atomic.

There is also a strong preference for adding tests in a previous commit, with them passing, showing the current behavior. How to handle this when its a new API is context dependent. In this case, I would add the tests with the prefixes being hardcoded in each env variable and then the main commit would port it to the new API.

epage · 2026-02-23T22:01:26Z

+                if let Some(Some(ref prefix)) = a.env_prefix {
+                    if let Some((ref env_name, _)) = a.env {
+                        let prefixed = format!("{}_{}", prefix, env_name.to_str().unwrap_or(""));
+                        let value = env::var_os(&prefixed);


Not thrilled with us having looked up the env and now we look it up again

Yeah, this is a tradeoff with the current design. Arg::env() eagerly caches the env value at argument creation time, but we don't know the final env name until the prefix is applied during build. So we have to re-lookup with the prefixed name.

Moving the prefix application earlier (e.g. into arg_internal) doesn't help since Arg::env() already ran by then. The alternative would be lazy env lookup (only during parsing), but that'd be a bigger refactor of existing behavior. The extra env::var_os call at build time is cheap, and the old cached value gets replaced, so there's no functional issue - just a wasted initial lookup.

epage · 2026-02-24T16:21:30Z


+#[cfg(feature = "string")]
 #[test]
 fn env_prefix_cli_overrides_env() {


This seems like it is testing env support generally rather than env-prefix-specific logic

Good catch, removed that test. The remaining tests focus specifically on prefix behavior.

epage · 2026-03-02T16:21:18Z

Please keep in mind that new tests should be added in the previous commit like the other new tests.

Squashed everything into a single commit now - feature code, builder tests, and derive tests all together.

epage · 2026-03-02T16:24:23Z

+#[test]
+fn command_next_env_prefix_cli_overrides() {
+    env::set_var("DERIVE_CLI_NAME", "from_env");
+
+    #[derive(Debug, Clone, Parser)]
+    #[command(next_env_prefix = "DERIVE_CLI")]
+    struct CliOptions {
+        #[arg(long, env = "NAME")]
+        name: Option<String>,
+    }
+
+    let m = CliOptions::try_parse_from(vec!["", "--name", "from_cli"]).unwrap();
+    assert_eq!(m.name.as_deref(), Some("from_cli"));
+}


This seems to be testing env support

Removed that test - it was testing general env/cli override behavior, not prefix-specific logic.

epage · 2026-03-02T16:27:29Z

+fn command_next_env_prefix_with_flatten() {
+    env::set_var("FLAT_APP_DB", "mydb");
+
+    #[derive(Debug, Clone, Args)]
+    #[command(next_env_prefix = "FLAT_APP")]
+    struct DbArgs {
+        #[arg(long, env = "DB")]
+        db: Option<String>,
+    }
+
+    #[derive(Debug, Clone, Parser)]
+    struct CliOptions {
+        #[command(flatten)]
+        db_args: DbArgs,
+    }


Missing some flatten cases that next_help_heading has, like

flattened field with help heading

Added more flatten cases:

flatten_multiple_structs_different_prefixes - two flattened structs each with their own prefix, verifying isolation

parent_env_prefix_does_not_leak_into_flatten - parent command's prefix correctly doesn't leak into a flattened struct that doesn't set its own prefix

veeceey · 2026-03-10T13:24:25Z

hey @epage, thanks for the thorough review — really helpful feedback. let me go through each point:

Arg::env_prefix vs Command::env_prefix — yeah, rereading Add an env_prefix derive option for a consistent prefix for environment variables #3221 I see they wanted per-arg prefix support too. I'll look into adding that as a follow-up or folding it into this PR if it makes sense.
Hand-written Debug impl — missed that, I'll update it to include the new field.
env feature gate — good catch, the builder methods shouldn't silently do nothing when env isn't enabled. I'll add a compile error or gate the methods properly.
to_str — agreed, I'll find a better approach here. probably working with OsStr directly instead of converting.
Double env lookup — yeah that's wasteful. I'll refactor so we only resolve the env var once and pass the result through.
Missing getter — will add it.
Test testing env support generally — you're right, I'll trim that test down to only cover prefix-specific behavior.
Turbofish — good point, I'll remove it if type inference handles it.
Derive tests — will add derive tests modeled after next_help_heading.
Commit structure — understood, I'll restructure so the tests come in a prior commit showing current behavior, then the implementation commit ports them to the new API.
Test testing env support — will remove the redundant env test from the prefix test file.
Flatten cases — will add the missing flatten scenarios like next_help_heading has.

I'll rework the commits and push an updated version. appreciate the detailed review!

veeceey · 2026-03-12T04:39:25Z

rebased and addressed the test feedback:

removed the env_prefix_cli_overrides_env builder test and command_next_env_prefix_cli_overrides derive test — both were just testing general env/cli override behavior, not prefix-specific logic
added flatten_field_with_env_prefix derive test (mirrors flatten_field_with_help_heading — prefix set on the flatten field itself, not inside the flattened struct)
restructured commits: first commit now has both builder and derive tests with hardcoded prefixed env names, second commit ports them to the new API
dropped the unrelated CI/toolchain changes that crept in from the fork being behind upstream

veeceey · 2026-03-15T03:10:51Z

Thanks for the detailed review @epage. I see I'm missing several cases — the flatten scenarios that next_help_heading handles, derive tests, the getter, and the turbofish issue. Let me go through next_help_heading's implementation more carefully and make sure env_prefix covers the same set of cases. Will push an update with the missing flatten tests, a getter, and clean up the turbofish.

veeceey · 2026-03-18T05:23:21Z

fixed the CI failures — the env::set_var calls in my test code weren't wrapped in unsafe blocks, which is required in the 2024 edition. all set_var calls now have the unsafe wrapper matching the existing test style in the repo.

Add env variable prefix support so that env variable names specified via Arg::env can be automatically prefixed during build. This works similarly to Command::next_help_heading - it's a stateful method that affects subsequently added arguments. - Command::next_env_prefix sets the prefix for all following args - Arg::env_prefix sets per-arg prefix (takes precedence) - Prefix and env name are joined with underscore - Hand-written Debug impl updated to include env_prefix - Getter get_env_prefix added for reflection - Derive support via #[command(next_env_prefix = "...")] - Works with flatten (prefix on Args struct or on flatten field) - Requires both `env` and `string` features since the prefixed env name is dynamically constructed Closes clap-rs#3221