feat(cli): Add 'list' subcommand to '/commands' by Jwhyee · Pull Request #22324 · google-gemini/gemini-cli

Jwhyee · 2026-03-13T14:38:10Z

Summary

Adds a list subcommand to the /commands utility to display all currently loaded .toml command files. This improves the developer experience by allowing users to quickly verify which custom commands and prompts are active without manually inspecting the file system.

Details

Currently, the /commands command only supports the reload subcommand. This PR introduces the list subcommand, which reads and outputs the filenames from the directories evaluated by the CLI (user-level ~/.gemini/commands/, project-level <project>/.gemini/commands/, MCP prompts, and extensions).

Added unit tests in commandsCommand.test.ts to ensure the correct paths are scanned and listed.
Updated user-facing documentation in docs/reference/commands.md.

Related Issues

Fixes #22321

How to Validate

Build and start the CLI locally: npm run build followed by npm start.
Add a dummy .toml file to ~/.gemini/commands/ or <project>/.gemini/commands/.
Inside the CLI prompt, execute /commands list.
Verify that the output accurately reflects the .toml files present in those directories.
Run the test suite to ensure no regressions: npm run test.
Run npm run preflight to confirm formatting and linting pass.

Pre-Merge Checklist

gemini-code-assist · 2026-03-13T14:40:25Z

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request introduces a new list subcommand to the /commands utility, enhancing the developer experience by providing a straightforward way to view all active custom commands. The changes include modifications to the command logic, addition of unit tests, and updates to the user documentation.

Highlights

New 'list' Subcommand: Introduced a 'list' subcommand to the /commands utility, enabling users to view all loaded .toml command files.
Improved Developer Experience: Allows developers to quickly verify active custom commands and prompts without manual file system inspection.
Comprehensive File Listing: The 'list' subcommand reads and outputs filenames from user-level, project-level, MCP prompts, and extensions directories.
Added Unit Tests: Implemented unit tests in commandsCommand.test.ts to ensure correct path scanning and listing.
Updated Documentation: Updated user-facing documentation in docs/reference/commands.md to reflect the new subcommand.

Changelog

docs/reference/commands.md
- Added documentation for the new list subcommand.
packages/cli/src/ui/commands/commandsCommand.test.ts
- Added unit tests for the list subcommand, mocking file system interactions and command contexts to ensure correct functionality.
packages/cli/src/ui/commands/commandsCommand.ts
- Implemented the list subcommand, including logic to gather and display .toml command files from various sources.
- Modified the default action to include a reference to the new list subcommand.

Activity

Added a list subcommand to the /commands utility.
Implemented unit tests for the new subcommand.
Updated user-facing documentation.
Addressed issue Feature Request: Add 'list' subcommand to '/commands' to show loaded command files #22321.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	`/gemini review`	Performs a code review for the current pull request in its current state.
Pull Request Summary	`/gemini summary`	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	`/gemini help`	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

gemini-code-assist

Code Review

This pull request introduces a list subcommand to /commands, allowing users to see all loaded custom command files. The implementation is straightforward and includes corresponding documentation and tests. My main feedback is to improve error handling when scanning for command files to provide better diagnostics for users, ensuring detailed logging for unexpected errors as per best practices.

- Refactor FileCommandLoader to expose getCommandDirectories - Improve error handling with isNodeError and add internal debugLogger - Fix strict typing issues in tests - Add mock cleanup (restoreAllMocks) in afterEach

Jwhyee · 2026-03-14T03:11:27Z

/gemini review

gemini-code-assist

Code Review

This pull request introduces a useful list subcommand to the /commands utility, allowing users to see all loaded .toml command files. The implementation is well-structured and includes corresponding documentation and unit tests. I've identified one area for improvement regarding code duplication in commandsCommand.ts to enhance maintainability.

snapshot tests

gemini-cli · 2026-03-28T03:04:17Z

Hi there! Thank you for your interest in contributing to Gemini CLI.

To ensure we maintain high code quality and focus on our prioritized roadmap, we have updated our contribution policy (see Discussion #17383).

We only guarantee review and consideration of pull requests for issues that are explicitly labeled as 'help wanted'. All other community pull requests are subject to closure after 14 days if they do not align with our current focus areas. For this reason, we strongly recommend that contributors only submit pull requests against issues explicitly labeled as 'help-wanted'.

This pull request is being closed as it has been open for 14 days without a 'help wanted' designation. We encourage you to find and contribute to existing 'help wanted' issues in our backlog! Thank you for your understanding and for being part of our community!

cocosheng-g · 2026-04-08T19:33:42Z

@Jwhyee, apologies for the bot closing this PR! We have reopened it. Please sync your branch to the latest main and we will have someone review it shortly.

Jwhyee · 2026-04-09T11:50:28Z

@cocosheng-g Fixed test failures! A type error introduced by the upstream merge. context.services.agentContext?.config was returning undefined instead of null, which caused a type mismatch in FileCommandLoader. Added ?? null to handle it.

Jwhyee · 2026-04-09T14:44:21Z

@cocosheng-g Thanks for enabling auto-merge! The docs-pr-check has been queued for over 3 hours without running. is there anything I need to do on my end, or does this need a re-trigger?

cocosheng-g · 2026-04-09T19:53:08Z

Requesting review from gemini-cli-docs

jkcinouye

LGTM - docs.

One minor. note.

Jwhyee · 2026-04-10T15:38:05Z

@jkcinouye Thank you for the suggestion. I've applied the changes to make it read more naturally.

Jwhyee · 2026-04-27T11:26:10Z

@jkcinouye The docs-pr-check has been stuck in the queue for about 2 weeks. could you help re-trigger it when you get a chance?

Jwhyee · 2026-04-27T11:28:35Z

@cocosheng-g Once the check passes, could you re-add this to the merge queue?!

spencer426

Thanks for adding the /commands list feature! This is a great addition for visibility into custom commands.

The changes look mostly solid, but there are a few areas that need to be aligned with the project's strict development rules.

Architectural Boundaries

FileCommandLoader.ts is currently located in packages/cli/src/services/ but performs filesystem operations (like glob). Our architecture rules dictate that non-UI logic and filesystem operations MUST reside in packages/core. While this file already existed here, introducing more filesystem logic compounds the architectural debt. We may want to consider moving this service to core in a future PR.

spencer426 · 2026-04-30T20:31:46Z

+        }
+      } catch (e) {
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+        if ((e as { code?: string }).code === 'ENOENT') {


Our strict development rules require handling filesystem errors gracefully using isNodeError from packages/core/src/utils/errors.ts and explicitly forbid eslint-disable-next-line for unsafe type assertions.

Please export isNodeError from packages/core/src/index.ts (if it isn't already exported) and update this block to use it: if (isNodeError(e) && e.code === 'ENOENT').

spencer426 · 2026-04-30T20:31:46Z

+      // Snapshot the text content
+      const addItemCall = vi.mocked(context.ui.addItem).mock.calls[0][0];
+
+      expect((addItemCall as { text: string }).text).toMatchSnapshot();


The rules state to avoid any and unsafe type casting in tests.

Please cast this to the proper type HistoryItemInfo (which can be imported from packages/cli/src/ui/types.ts) or narrow the type properly instead of using a partial shape cast.

spencer426 · 2026-04-30T20:31:46Z

+        },
+      ]);
+
+      const listCmd = commandsCommand.subCommands!.find(


The use of the non-null assertion operator (!) should be avoided unless absolutely necessary.

Consider restructuring this slightly to use standard type narrowing (e.g., asserting the command is found and throwing a descriptive error if not) rather than chaining !.

Co-authored-by: Coco Sheng <cocosheng@google.com> Co-authored-by: Spencer <spencertang@google.com>

feat(cli): Add 'list' subcommand to '/commands'

a60825a

Jwhyee requested review from a team as code owners March 13, 2026 14:38

gemini-code-assist Bot reviewed Mar 13, 2026

View reviewed changes

Comment thread packages/cli/src/ui/commands/commandsCommand.ts Outdated

fix(cli): silently skip ENOENT for list subcommand

98df373

gemini-cli Bot added the area/core Issues related to User Interface, OS Support, Core Functionality label Mar 13, 2026

Jwhyee added 2 commits March 14, 2026 01:59

Merge branch 'main' into feat/add-commands-list

599a141

Merge branch 'main' into feat/add-commands-list

d64d444

github-actions Bot mentioned this pull request Mar 14, 2026

📊 AI CLI 工具社区动态日报 2026-03-14 gsscsd/big_model_radar#32

Open

Jwhyee and others added 2 commits March 14, 2026 10:47

fix(cli): address code review feedback for commands list

4da6e0d

- Refactor FileCommandLoader to expose getCommandDirectories - Improve error handling with isNodeError and add internal debugLogger - Fix strict typing issues in tests - Add mock cleanup (restoreAllMocks) in afterEach

Merge branch 'main' into feat/add-commands-list

023706f

github-actions Bot mentioned this pull request Mar 14, 2026

📊 Bản tin hàng ngày công cụ AI CLI 2026-03-14 compasify/agents-radar#40

Open

gemini-code-assist Bot reviewed Mar 14, 2026

View reviewed changes

Comment thread packages/cli/src/ui/commands/commandsCommand.ts Outdated

Jwhyee and others added 7 commits March 14, 2026 12:27

refactor(cli): extract displayName logic to reduce duplication

fc4fd07

refactor(cli): move commands listing logic to FileCommandLoader and add

676033c

snapshot tests

docs(cli): add documentation for /commands list subcommand

274ed21

Merge branch 'main' into feat/add-commands-list

acb97a7

Merge branch 'main' into feat/add-commands-list

b1cf02c

Merge branch 'main' into feat/add-commands-list

25a8466

Merge branch 'main' into feat/add-commands-list

3c4788a

gemini-cli Bot closed this Mar 28, 2026

marsam2489-lang approved these changes Mar 28, 2026

View reviewed changes

cocosheng-g reopened this Apr 8, 2026

Jwhyee and others added 2 commits April 9, 2026 20:24

fix(cli): resolve type error for config in listSubcommandAction

8e08c0c

Merge branch 'main' into feat/add-commands-list

f862756

cocosheng-g enabled auto-merge April 9, 2026 13:55

Merge branch 'main' into feat/add-commands-list

408dd1e

auto-merge was automatically disabled April 10, 2026 02:56
Head branch was pushed to by a user without write access

Merge branch 'main' into feat/add-commands-list

53354ad

jkcinouye approved these changes Apr 10, 2026

View reviewed changes

Comment thread docs/cli/custom-commands.md Outdated

Jwhyee added 2 commits April 11, 2026 00:34

docs: reorder sentences in commands tip block

c6d5be6

docs: reorder sentences in commands tip block

212eb13

cocosheng-g approved these changes Apr 10, 2026

View reviewed changes

cocosheng-g enabled auto-merge April 10, 2026 18:12

Merge branch 'main' into feat/add-commands-list

31114c8

Jwhyee requested review from cocosheng-g and jkcinouye April 13, 2026 14:43

Merge branch 'main' into feat/add-commands-list

751d97c

cocosheng-g added this pull request to the merge queue Apr 14, 2026

github-merge-queue Bot removed this pull request from the merge queue due to failed status checks Apr 14, 2026

Merge branch 'main' into feat/add-commands-list

471a8d2

spencer426 added this pull request to the merge queue Apr 30, 2026

Merged via the queue into google-gemini:main with commit 8461662 Apr 30, 2026
1 of 2 checks passed

spencer426 requested changes Apr 30, 2026

View reviewed changes

TirthNaik-99 pushed a commit to TirthNaik-99/gemini-cli that referenced this pull request May 4, 2026

feat(cli): Add 'list' subcommand to '/commands' (google-gemini#22324)

fe90455

Co-authored-by: Coco Sheng <cocosheng@google.com> Co-authored-by: Spencer <spencertang@google.com>

kimjune01 pushed a commit to kimjune01/gemini-cli-claude that referenced this pull request May 6, 2026

feat(cli): Add 'list' subcommand to '/commands' (google-gemini#22324)

5f25edd

Co-authored-by: Coco Sheng <cocosheng@google.com> Co-authored-by: Spencer <spencertang@google.com>

Conversation

Jwhyee commented Mar 13, 2026

Summary

Details

Related Issues

How to Validate

Pre-Merge Checklist

Uh oh!

gemini-code-assist Bot commented Mar 13, 2026

Summary of Changes

Highlights

Footnotes

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

Jwhyee commented Mar 14, 2026

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

gemini-cli Bot commented Mar 28, 2026

Uh oh!

cocosheng-g commented Apr 8, 2026

Uh oh!

Jwhyee commented Apr 9, 2026

Uh oh!

Jwhyee commented Apr 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

cocosheng-g commented Apr 9, 2026

Uh oh!

jkcinouye left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Jwhyee commented Apr 10, 2026

Uh oh!

Uh oh!

Jwhyee commented Apr 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Jwhyee commented Apr 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

spencer426 left a comment

Choose a reason for hiding this comment

Architectural Boundaries

Uh oh!

spencer426 Apr 30, 2026

Choose a reason for hiding this comment

Uh oh!

spencer426 Apr 30, 2026

Choose a reason for hiding this comment

Uh oh!

spencer426 Apr 30, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Jwhyee commented Apr 9, 2026 •

edited

Loading

Jwhyee commented Apr 27, 2026 •

edited

Loading

Jwhyee commented Apr 27, 2026 •

edited

Loading