v4 plan: clean slate, built outward from command actions

[asahasrabuddhe]

This thread is for planning urfave/cli v4. @dearchap will lay out the release process here. The feature list lives in #2192.

Approach

v4 starts from an empty tree, not from the v3 code. We build it outward from the smallest useful core and check each layer against v3 tests as it lands.

Proposed build order:

1. A clean v4 module with no existing cli code.
2. Command actions only, with i18n for the errors they return. This is small and easy to test.
3. One command, its actions and its errors, then grow outward from there.
4. An app "personality": hooks that decide how the CLI behaves on errors and help, so an app can act like ls, like git, or like other Unix tools.
5. The help subsystem, with a rewrite of the templating (Improve readability of help text #2075).
6. Flags and args, with their i18n errors (Text flags #2051, Handling non-parsed flags #2240, nil pointer dereference due to HelpFlag when running in parallel #2176).
7. Multiple commands and subcommands.

Agents and v4

Much of this work suits coding agents. Each step above can be written as a prompt, with v3 test compatibility as the check.

v4 should also make CLIs built on urfave/cli behave predictably when an agent runs them. Open points:

• Stable, documented exit codes.
• Typed errors that callers can match without parsing text.
• Help and usage output that a program can parse.
• No interactive prompts when stdin is not a terminal.

Open questions

• Module path and branch: v4 branch on this repo, or a separate directory?
• Which v3 tests count as the compatibility suite?
• What is the translation format, and who owns the default English strings?

Release process

@dearchap to fill in.

[asahasrabuddhe]

The spike of the first milestone (errors, i18n and exit handling) is up as draft PR #2447. The full design is in v4/DESIGN.md in that PR, so comments on specific lines can go there. This thread can stay on the direction and the open questions.

What the spike does

• Every error the library detects is a *cli.Error with a Kind and structured fields. errors.Is(err, cli.ErrUnknownFlag) works through %w wrapping and errors.Join, and applications can define their own kinds.
• Messages come from a catalogue with placeholders and plural forms. English is built in, German is a separate package, and we can add other languages as required.
• Command.Run never exits. cli.Main handles signals and calls os.Exit.

$ LANG=de_DE.UTF-8 hello a b c
hello: 3 unerwartete Argumente, beginnend mit „a“
„hello --help“ gibt weitere Informationen aus.
$ echo $?
2

Personalities

A personality has two parts. Presets set the policy, meaning the exit codes, the hints and what happens on an unknown command. Modifiers set the format, and never change exit codes, so a script, a person and an agent see the same code for the same failure.

• Presets: POSIX (the default), BSD (sysexits codes), Git (for tools that dispatch to subcommands) and V3 (v3 output byte for byte, for migration).
• Modifiers: Agent (one versioned JSON object on stderr, no colour, never a prompt) and Quiet (one line per error).

cmd := &cli.Command{
    Personality: personality.Auto(os.LookupEnv, personality.Git),
}

Auto returns the preset for people and Agent(preset) when URFAVE_CLI_AGENT=1 is set.

Also in the design

• A modular library. The core has no dependencies, and help templates, completion, JSON, docs, config files and MCP live in optional packages and modules, so a program only pays for what it imports.
• Migrating from v3. Same names where the meaning is the same, go fix for the mechanical rewrites, a V3 preset that keeps output unchanged, and an adapter so a large app can move one command at a time.
• Agent support. Masked sensitive values, prompts that fail fast when nobody can answer, structured warnings, command annotations for MCP, and a supported mcp module.
• Building v4 with agents. An AGENTS.md with the rules, one issue per milestone with tests written first, and the v3 compatibility suite and a v3 against v4 fuzzer as the judge.
• Build and CI. Plain go commands instead of scripts/build.go, pinned tools, a size budget, an API check and fuzzing.

Questions

• Is Go 1.25 the right minimum?
• Should the spike live in v4/ on main, or on a long-lived v4 branch?
• Which presets and modifiers should ship in the first release?
• Is URFAVE_CLI_AGENT the right name, and should Auto also recognise variables that agent tools may already set? Claude Code may set CLAUDECODE, for example, which needs confirming.
• How long should v3 get fixes after v4.0?
• v2 has had fixes since November 2019. Should v2 support end when v4.0 ships, with fixes continuing while v4 is in development?
• What size budget should CI enforce for examples/hello?

@dearchap the release process section is still yours.

[coilysiren]

@asahasrabuddhe given that the design is a draft PR, and you okay with us maintainers collaborating via pushing directly to the PR? If not, what would you prefer? I'm going to do that now and you can git revert if you need to

[coilysiren]

I've got 3 agent native go CLIs I've been using daily for months. For each one I'm going to make a post describing its architecture as it relates to CLI design

https://github.com/coilyco/umbra
https://github.com/coilyco/agentic-os
https://github.com/coilyco/agent-compose

Offhand I can say that the CLI that has the greatest need and structure is umbra, it's UX and feature set are very fine tuned.

[asahasrabuddhe]

@asahasrabuddhe given that the design is a draft PR, and you okay with us maintainers collaborating via pushing directly to the PR? If not, what would you prefer? I'm going to do that now and you can git revert if you need to

Please feel free to push changes to the draft PR! If someone is busy or is unable to push code, they can choose to leave feedback and I will implement that change.