Vvinhnx

clap-v3-to-v4

Migrate Rust clap CLI parser from v3 to v4: derive/value enum renames, builder API updates to num_args, ErrorKind renames, and AppSettings cleanup

rustclapclimigrationv3-to-v4argument-parserderivebuilder
Public
9 executions
Apply to Repository

Run locally

npx codemod clap-v3-to-v4

clap-v3-to-v4

Automate 80%+ of the Rust clap CLI parser migration from v3 to v4.

What it does

Derive API transforms

  • #[clap(...)] on structs/enums → #[command(...)]
  • #[clap(...)] on fields → #[arg(...)]
  • arg_enum → value_enum
  • ArgEnum derives → ValueEnum
  • Removes redundant value_parser and action attributes (implicit in v4)

Builder API transforms

  • .takes_value(true) → .num_args(1)
  • .multiple_values(true) → .num_args(1..)
  • .min_values(N) → .num_args(N..)
  • .max_values(N) → .num_args(1..=N)
  • .number_of_values(N) → .num_args(N)
  • .multiple(true) → .num_args(1..)
  • Removes .takes_value(false) (now default)
  • Removes .require_value_delimiter(true) (use .value_delimiter(','))
  • Removes .setting(AppSettings::ColoredHelp) (now default)
  • Removes now-unused AppSettings imports when ColoredHelp was the only use

Error kind renames

  • ErrorKind::EmptyValue → ErrorKind::InvalidValue
  • ErrorKind::UnrecognizedSubcommand → ErrorKind::InvalidSubcommand

Cargo.toml follow-up

  • Update clap = "3.x" → clap = "4"
  • Update clap = { version = "3.x", ... } → clap = { version = "4", ... }

Usage

bash

Manual follow-up

After running, you should:

  1. Review Cargo.toml updates for any uncommon clap dependency formatting not covered by deterministic rewrites
  2. Remove the deprecated feature flag if present
  3. Run cargo check to catch remaining compile errors
  4. Verify num_args ranges match your intended behavior
  5. Check ArgAction usage — v4 changed default actions for flags
  6. Update custom help templates — format changed in v4
  7. Remove unused imports (e.g., AppSettings if no longer needed)
  8. Run cargo test to verify behavior

Development

bash

References

License

MIT

Ready to contribute?

Build your own codemod and share it with the community.

Publish a codemodJoin the community