Add shortcuts hint and panel for discoverability

packages/cli/src/services/BuiltinCommandLoader.test.ts

@@ -85,6 +85,9 @@ vi.mock('../ui/commands/extensionsCommand.js', () => ({
   extensionsCommand: () => ({}),
 }));
 vi.mock('../ui/commands/helpCommand.js', () => ({ helpCommand: {} }));
+vi.mock('../ui/commands/shortcutsCommand.js', () => ({
+  shortcutsCommand: {},
+}));
 vi.mock('../ui/commands/memoryCommand.js', () => ({ memoryCommand: {} }));
 vi.mock('../ui/commands/modelCommand.js', () => ({
   modelCommand: { name: 'model' },

packages/cli/src/services/BuiltinCommandLoader.ts

@@ -31,6 +31,7 @@ import { directoryCommand } from '../ui/commands/directoryCommand.js';
 import { editorCommand } from '../ui/commands/editorCommand.js';
 import { extensionsCommand } from '../ui/commands/extensionsCommand.js';
 import { helpCommand } from '../ui/commands/helpCommand.js';
+import { shortcutsCommand } from '../ui/commands/shortcutsCommand.js';
 import { rewindCommand } from '../ui/commands/rewindCommand.js';
 import { hooksCommand } from '../ui/commands/hooksCommand.js';
 import { ideCommand } from '../ui/commands/ideCommand.js';
@@ -115,6 +116,7 @@ export class BuiltinCommandLoader implements ICommandLoader {
           ]
         : [extensionsCommand(this.config?.getEnableExtensionReloading())]),
       helpCommand,
+      shortcutsCommand,
       ...(this.config?.getEnableHooksUI() ? [hooksCommand] : []),
       rewindCommand,
       await ideCommand(),

packages/cli/src/test-utils/mockCommandContext.ts

@@ -60,6 +60,7 @@ export const createMockCommandContext = (
       setPendingItem: vi.fn(),
       loadHistory: vi.fn(),
       toggleCorgiMode: vi.fn(),
+      toggleShortcutsHelp: vi.fn(),
       toggleVimEnabled: vi.fn(),
       openAgentConfigDialog: vi.fn(),
       closeAgentConfigDialog: vi.fn(),

packages/cli/src/test-utils/render.tsx

@@ -203,6 +203,7 @@ const mockUIActions: UIActions = {
   handleApiKeySubmit: vi.fn(),
   handleApiKeyCancel: vi.fn(),
   setBannerVisible: vi.fn(),
+  setShortcutsHelpVisible: vi.fn(),
   setEmbeddedShellFocused: vi.fn(),
   dismissBackgroundShell: vi.fn(),
   setActiveBackgroundShellPid: vi.fn(),

packages/cli/src/ui/AppContainer.tsx

@@ -799,6 +799,7 @@ Logging in with Google... Restarting Gemini CLI to continue.
   const setIsBackgroundShellListOpenRef = useRef<(open: boolean) => void>(
     () => {},
   );
+  const [shortcutsHelpVisible, setShortcutsHelpVisible] = useState(false);
 
   const slashCommandActions = useMemo(
     () => ({
@@ -834,6 +835,7 @@ Logging in with Google... Restarting Gemini CLI to continue.
           }
         }
       },
+      toggleShortcutsHelp: () => setShortcutsHelpVisible((visible) => !visible),
       setText: stableSetText,
     }),
     [
@@ -852,6 +854,7 @@ Logging in with Google... Restarting Gemini CLI to continue.
       openPermissionsDialog,
       addConfirmUpdateExtensionRequest,
       toggleDebugProfiler,
+      setShortcutsHelpVisible,
       stableSetText,
     ],
   );
@@ -1893,6 +1896,7 @@ Logging in with Google... Restarting Gemini CLI to continue.
       ctrlCPressedOnce: ctrlCPressCount >= 1,
       ctrlDPressedOnce: ctrlDPressCount >= 1,
       showEscapePrompt,
+      shortcutsHelpVisible,
       isFocused,
       elapsedTime,
       currentLoadingPhrase,
@@ -1998,6 +2002,7 @@ Logging in with Google... Restarting Gemini CLI to continue.
       ctrlCPressCount,
       ctrlDPressCount,
       showEscapePrompt,
+      shortcutsHelpVisible,
       isFocused,
       elapsedTime,
       currentLoadingPhrase,
@@ -2097,6 +2102,7 @@ Logging in with Google... Restarting Gemini CLI to continue.
       handleApiKeySubmit,
       handleApiKeyCancel,
       setBannerVisible,
+      setShortcutsHelpVisible,
       handleWarning,
       setEmbeddedShellFocused,
       dismissBackgroundShell,
@@ -2173,6 +2179,7 @@ Logging in with Google... Restarting Gemini CLI to continue.
       handleApiKeySubmit,
       handleApiKeyCancel,
       setBannerVisible,
+      setShortcutsHelpVisible,
       handleWarning,
       setEmbeddedShellFocused,
       dismissBackgroundShell,

packages/cli/src/ui/commands/helpCommand.ts

@@ -10,7 +10,6 @@ import { MessageType, type HistoryItemHelp } from '../types.js';
 
 export const helpCommand: SlashCommand = {
   name: 'help',
-  altNames: ['?'],
   kind: CommandKind.BUILT_IN,
   description: 'For help on gemini-cli',
   autoExecute: true,

packages/cli/src/ui/commands/shortcutsCommand.ts

@@ -0,0 +1,19 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type { SlashCommand } from './types.js';
+import { CommandKind } from './types.js';
+
+export const shortcutsCommand: SlashCommand = {
+  name: 'shortcuts',
+  altNames: ['keys', '?'],
+  kind: CommandKind.BUILT_IN,
+  description: 'Toggle the shortcuts panel above the input',
+  autoExecute: true,
+  action: (context) => {
+    context.ui.toggleShortcutsHelp();
+  },
+};

packages/cli/src/ui/commands/types.ts

@@ -85,6 +85,7 @@ export interface CommandContext {
     addConfirmUpdateExtensionRequest: (value: ConfirmationRequest) => void;
     removeComponent: () => void;
     toggleBackgroundShell: () => void;
+    toggleShortcutsHelp: () => void;
   };
   // Session-specific data
   session: {

packages/cli/src/ui/components/Composer.test.tsx

@@ -49,6 +49,14 @@ vi.mock('./ShellModeIndicator.js', () => ({
   ShellModeIndicator: () => <Text>ShellModeIndicator</Text>,
 }));
 
+vi.mock('./ShortcutsHint.js', () => ({
+  ShortcutsHint: () => <Text>ShortcutsHint</Text>,
+}));
+
+vi.mock('./ShortcutsHelp.js', () => ({
+  ShortcutsHelp: () => <Text>ShortcutsHelp</Text>,
+}));
+
 vi.mock('./DetailedMessagesDisplay.js', () => ({
   DetailedMessagesDisplay: () => <Text>DetailedMessagesDisplay</Text>,
 }));
@@ -116,6 +124,7 @@ const createMockUIState = (overrides: Partial<UIState> = {}): UIState =>
     ctrlCPressedOnce: false,
     ctrlDPressedOnce: false,
     showEscapePrompt: false,
+    shortcutsHelpVisible: false,
     ideContextState: null,
     geminiMdFileCount: 0,
     renderMarkdown: true,
@@ -457,7 +466,7 @@ describe('Composer', () => {
 
       const { lastFrame } = renderComposer(uiState);
 
-      expect(lastFrame()).toContain('ApprovalModeIndicator');
+      expect(lastFrame()).toMatch(/ApprovalModeIndica\s*tor/);
     });
 
     it('shows ShellModeIndicator when shell mode is active', () => {
@@ -467,7 +476,7 @@ describe('Composer', () => {
 
       const { lastFrame } = renderComposer(uiState);
 
-      expect(lastFrame()).toContain('ShellModeIndicator');
+      expect(lastFrame()).toMatch(/ShellModeIndica\s*tor/);
     });
 
     it('shows RawMarkdownIndicator when renderMarkdown is false', () => {

packages/cli/src/ui/components/Composer.tsx

@@ -12,6 +12,8 @@ import { ApprovalModeIndicator } from './ApprovalModeIndicator.js';
 import { ShellModeIndicator } from './ShellModeIndicator.js';
 import { DetailedMessagesDisplay } from './DetailedMessagesDisplay.js';
 import { RawMarkdownIndicator } from './RawMarkdownIndicator.js';
+import { ShortcutsHint } from './ShortcutsHint.js';
+import { ShortcutsHelp } from './ShortcutsHelp.js';
 import { InputPrompt } from './InputPrompt.js';
 import { Footer } from './Footer.js';
 import { ShowMoreLines } from './ShowMoreLines.js';
@@ -92,8 +94,18 @@ export const Composer = ({ isFocused = true }: { isFocused?: boolean }) => {
         flexDirection={isNarrow ? 'column' : 'row'}
         alignItems={isNarrow ? 'flex-start' : 'center'}
       >
-        <Box marginRight={1}>
-          <StatusDisplay hideContextSummary={hideContextSummary} />
+        <Box
+          marginRight={1}
+          flexDirection="row"
+          alignItems="center"
+          flexGrow={1}
+          justifyContent="space-between"
+          width="100%"
+        >
+          <ShortcutsHint />
+          <Box flexGrow={1} justifyContent="flex-end" flexDirection="row">
+            <StatusDisplay hideContextSummary={hideContextSummary} />
+          </Box>
         </Box>
         <Box paddingTop={isNarrow ? 1 : 0}>
           {showApprovalModeIndicator !== ApprovalMode.DEFAULT &&
@@ -121,6 +133,12 @@ export const Composer = ({ isFocused = true }: { isFocused?: boolean }) => {
         </OverflowProvider>
       )}
 
+      {uiState.shortcutsHelpVisible && (
+        <Box marginTop={1}>
+          <ShortcutsHelp />
+        </Box>
+      )}
+
       {uiState.isInputActive && (
         <InputPrompt
           buffer={uiState.buffer}

packages/cli/src/ui/components/InputPrompt.tsx

@@ -151,14 +151,15 @@ export const InputPrompt: React.FC<InputPromptProps> = ({
   const { merged: settings } = useSettings();
   const kittyProtocol = useKittyKeyboardProtocol();
   const isShellFocused = useShellFocusState();
-  const { setEmbeddedShellFocused } = useUIActions();
+  const { setEmbeddedShellFocused, setShortcutsHelpVisible } = useUIActions();
   const {
     terminalWidth,
     activePtyId,
     history,
     terminalBackgroundColor,
     backgroundShells,
     backgroundShellHeight,
+    shortcutsHelpVisible,
   } = useUIState();
   const [justNavigatedHistory, setJustNavigatedHistory] = useState(false);
   const escPressCount = useRef(0);
@@ -511,6 +512,30 @@ export const InputPrompt: React.FC<InputPromptProps> = ({
         return true;
       }
 
+      if (shortcutsHelpVisible) {
+        if (key.sequence === '?' && key.insertable) {
+          setShortcutsHelpVisible(false);
+          buffer.handleInput(key);
+          return true;
+        }
+        if (
+          keyMatchers[Command.ESCAPE](key) ||
+          key.name === 'backspace' ||
+          key.sequence === '\b'
+        ) {
+          setShortcutsHelpVisible(false);
+          return true;
+        }
+        if (key.insertable) {
+          setShortcutsHelpVisible(false);
+        }
+      }
+
+      if (key.sequence === '?' && key.insertable && !shortcutsHelpVisible) {
+        setShortcutsHelpVisible(true);
+        return true;
+      }
+
       if (vimHandleInput && vimHandleInput(key)) {
         return true;
       }
@@ -969,6 +994,8 @@ export const InputPrompt: React.FC<InputPromptProps> = ({
       commandSearchActive,
       commandSearchCompletion,
       kittyProtocol.enabled,
+      shortcutsHelpVisible,
+      setShortcutsHelpVisible,
       tryLoadQueuedMessages,
       setBannerVisible,
       onSubmit,