How should a CLI select its default command on empty or global-flags-only invocations?

[zeitlinger]

Use case

We are experimenting with Usage's Go generator in OATs, a test runner. Its normal invocation is just oats: discover configuration and run tests. oats -v must do the same with verbosity enabled; an explicit oats run is equivalent.

We understand that default_subcommand currently routes an unmatched first word rather than selecting a child when no command word is present. We would like advice on the intended way to express this application behavior, rather than silently introduce different semantics in Go.

A reduced version of the spec is:

name "oats"
bin "oats"
default_subcommand "run"
default_subcommand_flags #true
flag "-v --verbose" global=#true
cmd "run" {
    flag "--timeout <duration>" env="OATS_TIMEOUT" default="1m"
    arg "[paths]..."
}
cmd "list" {}

Invocation	Current routing	What OATs needs
oats	Root	run
oats -v	Root	run, with verbosity
oats ./cases	run with a path	Same
oats --timeout 2m	run through default flag routing	Same
oats list	list	Same
oats --help	Root help	Same

This is about more than calling the run handler: selecting run must also apply its environment values, defaults, and validation. Root help/version should still exit without executing tests or validating run-only requirements.

Current workaround

Our adapter calls generated Parse, checks that every subcommand pointer is nil, and then parses again with run prepended. That works for our current CLI but means maintaining a list of every command and performing a second parse. We would prefer to avoid that glue and keep option resolution owned by Usage.

Questions

• Is there an existing/recommended way to express this with today's spec or generated API? For example, should the root itself own the run behavior, and how should it share options and validation with an explicit run command?
• If not, would you prefer extending the existing default_subcommand behavior, adding a separate explicit policy, or keeping this as application-level dispatch with a supported helper?
• For a shared parser policy, what should the boundaries be around parent/global flags and explicit help/version requests?

We are happy to contribute an implementation and conformance tests once the direction is clear. We are not assuming the existing behavior is a bug or proposing a Go-only change to the shared grammar; an idiomatic alternative would be just as useful.

AI-assisted discussion prepared using OpenAI Codex.

[jdx]

This is a reasonable use case. My preference would be an explicit opt-in policy, preserving today's default_subcommand behavior.

Your diagnosis matches the implementation and documented semantics: default_subcommand routes an unmatched word, and default_subcommand_flags additionally routes on a default-only flag. Empty invocations and parent-only flags intentionally stay on the parent. I don't see an existing setting that expresses the full behavior you want.

The important requirement is selecting run before environment/default resolution and validation. Calling its handler after a root parse would miss those rules. Making the root own run behavior is possible, but still leaves sharing option declarations and validation with explicit run to the application.

Your two-parse adapter is a reasonable temporary workaround for this CLI, but I wouldn't make that the general solution. Besides maintaining the subcommand list, prepending run changes the scope of parent-only flags, and the first parse can reject root requirements before fallback is attempted.

I'd favor a separate setting—illustratively, default_subcommand_on_empty #true, requiring default_subcommand. The name is tentative: “empty” should mean no command or positional input after successfully parsing parent flags, not literally zero tokens. Changing the existing default implicitly would affect applications that intentionally give a bare invocation different behavior.

The boundaries I'd suggest are:

Case	Behavior
Empty input or recognized parent/global flags only	Select run, preserving existing flag bindings
Explicit command or alias	Keep the explicit selection
Root help/version request	Respond at root without run-only validation
Missing flag value or another parse error	Preserve the error
--, root positionals, arg_required_else_help	Define precedence explicitly before implementation

This should be shared command-selection semantics, before fallback resolution and validation, with matching reference/Rust/Go conformance tests covering both routing and the resulting values and requirements. A Go-only handler helper would leave the underlying semantic gap unresolved.

This assessment is based on reviewing the source and OATs adapter; I haven't run a reproduction.

This comment was AI-generated using OpenAI Codex.

[zeitlinger]

Thanks—an explicit opt-in fits OATs’ needs. Before implementing, would this precedence make sense?

• --: An explicit separator suppresses the new empty-input fallback, even with nothing after it. Existing separator/positional behavior remains unchanged. I’m fine with oats -- differing from bare oats.
• Root positionals: Consuming a root positional suppresses fallback; merely declaring an unfilled positional does not. Environment/default values don’t count as positional input. After selection, requirements follow the same rules as an explicitly selected child.
• arg_required_else_help: Eligible fallback selects the child before applying root implicit-help policy. The child’s own policy still applies; synthetic selection and already-parsed parent flags don’t count as child argv. Explicit root help/version still stay at root.

Existing command/alias selection and default-word/default-flag routing would remain unchanged, as would parse errors and parent flag bindings.

I’m happy to use default_subcommand_on_empty unless you prefer another name, requiring default_subcommand and defaulting to false. If that sounds right, I can contribute shared semantics with matching reference/Rust/Go conformance tests covering selection, values, requirements, and help behavior.

This reply was AI-generated using OpenAI Codex.

[jdx]

Yes, that precedence makes sense. Please go ahead with default_subcommand_on_empty, requiring default_subcommand and defaulting to false, with the shared semantics and reference/Rust/Go conformance tests you describe.

Two small clarifications to make explicit in the docs and tests:

• Requirements should follow explicit child selection exactly, including subcommand_negates_reqs; fallback should not automatically waive required root arguments.
• Only a syntactic -- separator suppresses fallback, not a literal -- consumed as a flag value.

The name works for me. Please document that “empty” includes recognized parent/global flags with no command or positional input. Selecting the child before environment/default resolution, validation, and root implicit help is the right approach.

This reply was AI-generated using OpenAI Codex.

[zeitlinger]

Implemented via #1458