fix(cli): prevent subcommand shadowing and skip auth for commands

[mattKorwel]

Summary

This PR fixes an issue where the Gemini CLI's greedy default command ($0 [query..]) shadowed administrative subcommands like mcp, extensions, skills, and hooks. This caused subcommands to be incorrectly treated as conversational queries, triggering unnecessary authentication checks and sandbox relaunches that would fail if a GEMINI_API_KEY was missing.

Details

• Reordered Command Registration: In packages/cli/src/config/config.ts, explicit subcommands are now registered before the default query command to ensure priority matching.
• Added isCommand Middleware: Implemented a yargs middleware to explicitly flag when a management subcommand is matched via argv['isCommand'] = true.
• Bypassed Auth & Sandbox for Commands: Updated packages/cli/src/gemini.tsx to skip refreshAuth and sandbox relaunching when argv.isCommand is true. This enables administrative tasks to run without an API key.
• Restored Lost Logic: Re-implemented the .check(), .fail(), and global debug option that were inadvertently removed during recent refactoring, ensuring robust flag validation (e.g., preventing conflicting prompt flags).
• Unconditional Registration: Subcommands are now registered unconditionally, allowing yargs to handle help and validation correctly even if the underlying feature is disabled in settings.

Related Issues

Fixes #23173

How to Validate

1. Manual Verification: Run gemini extensions list or gemini mcp list without a GEMINI_API_KEY environment variable. The command should execute successfully (showing an empty list or help) instead of failing with an authentication error.
2. Automated Tests: Run the configuration unit tests:

   npm test -w @google/gemini-cli -- src/config/config.test.ts

   Verify that the new isCommand middleware test suite passes and that existing validation tests (like conflicting flags) are restored and passing.

Pre-Merge Checklist

• Updated relevant documentation and README (if needed)
• Added/updated tests (if needed)
• Noted breaking changes (if any)
• Validated on required platforms/methods:
  • MacOS
    • npm run

[github-actions]

Size Change: +1.11 kB (0%)

Total Size: 26.1 MB

Filename	Size	Change
./bundle/chunk-DOTGJDVX.js	0 B	-3.64 MB (removed)	🏆
./bundle/chunk-RNURC5X7.js	0 B	-14.5 MB (removed)	🏆
./bundle/core-5DR65Q7F.js	0 B	-42.4 kB (removed)	🏆
./bundle/devtoolsService-HWESM4KW.js	0 B	-27.7 kB (removed)	🏆
./bundle/gemini.js	520 kB	+1.05 kB (+0.2%)
./bundle/interactiveCli-3Y7KYS5J.js	0 B	-1.62 MB (removed)	🏆
./bundle/oauth2-provider-ZWJJ4I47.js	0 B	-9.16 kB (removed)	🏆
./bundle/chunk-BOIGMUIM.js	3.64 MB	+3.64 MB (new file)	🆕
./bundle/chunk-J2JJNF4X.js	14.5 MB	+14.5 MB (new file)	🆕
./bundle/core-RBI4UIDA.js	42.4 kB	+42.4 kB (new file)	🆕
./bundle/devtoolsService-FY4KPZD6.js	27.7 kB	+27.7 kB (new file)	🆕
./bundle/interactiveCli-BY3LMCSD.js	1.62 MB	+1.62 MB (new file)	🆕
./bundle/oauth2-provider-OYFL4C75.js	9.16 kB	+9.16 kB (new file)	🆕

ℹ️ View Unchanged

Filename	Size
./bundle/chunk-34MYV7JD.js	2.45 kB
./bundle/chunk-5AUYMPVF.js	858 B
./bundle/chunk-5WHECDMU.js	1.95 MB
./bundle/chunk-664ZODQF.js	124 kB
./bundle/chunk-DAHVX5MI.js	206 kB
./bundle/chunk-IUUIT4SU.js	56.5 kB
./bundle/chunk-RJTRUG2J.js	39.8 kB
./bundle/devtools-36NN55EP.js	696 kB
./bundle/dist-T73EYRDX.js	356 B
./bundle/getMachineId-bsd-TXG52NKR.js	1.55 kB
./bundle/getMachineId-darwin-7OE4DDZ6.js	1.55 kB
./bundle/getMachineId-linux-SHIFKOOX.js	1.34 kB
./bundle/getMachineId-unsupported-5U5DOEYY.js	1.06 kB
./bundle/getMachineId-win-6KLLGOI4.js	1.72 kB
./bundle/memoryDiscovery-DL6LDUAP.js	922 B
./bundle/multipart-parser-KPBZEGQU.js	11.7 kB
./bundle/node_modules/@google/gemini-cli-devtools/dist/client/main.js	221 kB
./bundle/node_modules/@google/gemini-cli-devtools/dist/src/_client-assets.js	227 kB
./bundle/node_modules/@google/gemini-cli-devtools/dist/src/index.js	11.5 kB
./bundle/node_modules/@google/gemini-cli-devtools/dist/src/types.js	132 B
./bundle/sandbox-macos-permissive-open.sb	890 B
./bundle/sandbox-macos-permissive-proxied.sb	1.31 kB
./bundle/sandbox-macos-restrictive-open.sb	3.36 kB
./bundle/sandbox-macos-restrictive-proxied.sb	3.56 kB
./bundle/sandbox-macos-strict-open.sb	4.82 kB
./bundle/sandbox-macos-strict-proxied.sb	5.02 kB
./bundle/src-QVCVGIUX.js	47 kB
./bundle/tree-sitter-7U6MW5PS.js	274 kB
./bundle/tree-sitter-bash-34ZGLXVX.js	1.84 MB

_{compressed-size-action}

[mattKorwel]

/gemini review

[gemini-code-assist]

Code Review

This pull request addresses two main issues: yargs command shadowing and a TypeError when accessing potentially undefined settings.admin properties. The command shadowing fix involves reordering yargs command registration, adding a middleware to detect subcommands, and using an isCommand flag to skip unnecessary authentication and sandboxing. The TypeError is resolved by adding optional chaining to settings access. The reviewer suggests an improvement for the isCommand middleware, recommending a dynamic approach to building the subcommand list instead of a hardcoded one to enhance maintainability.

_{Note: Security Review did not run due to the size of the PR.}

[mattKorwel]

the root failure case we are dealing with here is inconsistent but sometimes, it is exercised and you can't get any gemini commands to work. see screenshot. the first several commands failed telling me it needed to auth, when it doesn't. the 2nd to last worked, but the last, should not have started a session with the command but rather recognized it as a admin command that was invalid.