ContextQMD
Back to Gemini Cli

CLI commands

docs/reference/commands.md

0.41.123.1 KB
Original Source

CLI commands

Gemini CLI supports several built-in commands to help you manage your session, customize the interface, and control its behavior. These commands are prefixed with a forward slash (/), an at symbol (@), or an exclamation mark (!).

Slash commands (/)

Slash commands provide meta-level control over the CLI itself.

Built-in Commands

/about

  • Description: Show version info. Share this information when filing issues.

/agents

  • Description: Manage local and remote subagents.
  • Sub-commands:
    • list:
      • Description: Lists all discovered agents, including built-in, local, and remote agents.
      • Usage: /agents list
    • reload (alias: refresh):
      • Description: Rescans agent directories (~/.gemini/agents and .gemini/agents) and reloads the registry.
      • Usage: /agents reload
    • enable:
      • Description: Enables a specific subagent.
      • Usage: /agents enable <agent-name>
    • disable:
      • Description: Disables a specific subagent.
      • Usage: /agents disable <agent-name>
    • config:
      • Description: Opens a configuration dialog for the specified agent to adjust its model, temperature, or execution limits.
      • Usage: /agents config <agent-name>

/auth

  • Description: Open a dialog that lets you change the authentication method.

/bug

  • Description: File an issue about Gemini CLI. By default, the issue is filed within the GitHub repository for Gemini CLI. The string you enter after /bug will become the headline for the bug being filed. The default /bug behavior can be modified using the advanced.bugCommand setting in your .gemini/settings.json files.

/chat

  • Description: Alias for /resume. Both commands now expose the same session browser action and checkpoint subcommands.
  • Menu layout when typing /chat (or /resume):
    • -- auto --
      • list (selecting this opens the auto-saved session browser)
    • -- checkpoints --
      • list, save, resume, delete, share (manual tagged checkpoints)
    • Unique prefixes (for example /cha or /resu) resolve to the same grouped menu.
  • Sub-commands:
    • debug
      • Description: Export the most recent API request as a JSON payload.
    • delete <tag>
      • Description: Deletes a saved conversation checkpoint.
      • Equivalent: /resume delete <tag>
    • list
      • Description: Lists available tags for manually saved checkpoints.
      • Note: This command only lists chats saved within the current project. Because chat history is project-scoped, chats saved in other project directories will not be displayed.
      • Equivalent: /resume list
    • resume <tag>
      • Description: Resumes a conversation from a previous save.
      • Note: You can only resume chats that were saved within the current project. To resume a chat from a different project, you must run the Gemini CLI from that project's directory.
      • Equivalent: /resume resume <tag>
    • save <tag>
      • Description: Saves the current conversation history. You must add a <tag> for identifying the conversation state.
      • Details on checkpoint location: The default locations for saved chat checkpoints are:
        • Linux/macOS: ~/.gemini/tmp/<project_hash>/
        • Windows: C:\Users\<YourUsername>\.gemini\tmp\<project_hash>\
        • Behavior: Chats are saved into a project-specific directory, determined by where you run the CLI. Consequently, saved chats are only accessible when working within that same project.
        • Note: These checkpoints are for manually saving and resuming conversation states. For automatic checkpoints created before file modifications, see the Checkpointing documentation.
        • Equivalent: /resume save <tag>
    • share [filename]
      • Description: Writes the current conversation to a provided Markdown or JSON file. If no filename is provided, then the CLI will generate one.
      • Usage: /chat share file.md or /chat share file.json.
      • Equivalent: /resume share [filename]

/clear

  • Description: Clear the terminal screen, including the visible session history and scrollback within the CLI. The underlying session data (for history recall) might be preserved depending on the exact implementation, but the visual display is cleared.
  • Keyboard shortcut: Press Ctrl+L at any time to perform a clear action.

/commands

  • Description: Manage custom slash commands loaded from .toml files.
  • Sub-commands:
    • reload:
      • Description: Reload custom command definitions from all sources (user-level ~/.gemini/commands/, project-level <project>/.gemini/commands/, MCP prompts, and extensions). Use this to pick up new or modified .toml files without restarting the CLI.
      • Usage: /commands reload

/compress

  • Description: Replace the entire chat context with a summary. This saves on tokens used for future tasks while retaining a high level summary of what has happened.

/copy

  • Description: Copies the last output produced by Gemini CLI to your clipboard, for easy sharing or reuse.
  • Behavior:
    • Local sessions use system clipboard tools (pbcopy/xclip/clip).
    • Remote sessions (SSH/WSL) use OSC 52 and require terminal support.
  • Note: This command requires platform-specific clipboard tools to be installed.
    • On Linux, it requires xclip or xsel. You can typically install them using your system's package manager.
    • On macOS, it requires pbcopy, and on Windows, it requires clip. These tools are typically pre-installed on their respective systems.

/directory (or /dir)

  • Description: Manage workspace directories for multi-directory support.
  • Sub-commands:
    • add:
      • Description: Add a directory to the workspace. The path can be absolute or relative to the current working directory. Moreover, the reference from home directory is supported as well.
      • Usage: /directory add <path1>,<path2>
      • Note: Disabled in restrictive sandbox profiles. If you're using that, use --include-directories when starting the session instead.
    • show:
      • Description: Display all directories added by /directory add and --include-directories.
      • Usage: /directory show

/docs

  • Description: Open Gemini CLI documentation in your browser.

/editor

  • Description: Open a dialog for selecting supported editors.

/extensions

  • Description: Manage extensions. See Gemini CLI Extensions.
  • Sub-commands:
    • config:
      • Description: Configure extension settings.
    • disable:
      • Description: Disable an extension.
    • enable:
      • Description: Enable an extension.
    • explore:
      • Description: Open extensions page in your browser.
    • install:
      • Description: Install an extension from a git repo or local path.
    • link:
      • Description: Link an extension from a local path.
    • list:
      • Description: List active extensions.
    • restart:
      • Description: Restart all extensions.
    • uninstall:
      • Description: Uninstall an extension.
    • update:
      • Description: Update extensions. Usage: update <extension-names>|--all

/help (or /?)

  • Description: Display help information about Gemini CLI, including available commands and their usage.

/hooks

  • Description: Manage hooks, which allow you to intercept and customize Gemini CLI behavior at specific lifecycle events.
  • Sub-commands:
    • disable-all:
      • Description: Disable all enabled hooks.
    • disable <hook-name>:
      • Description: Disable a hook by name.
    • enable-all:
      • Description: Enable all disabled hooks.
    • enable <hook-name>:
      • Description: Enable a hook by name.
    • list (or show, panel):
      • Description: Display all registered hooks with their status.

/ide

  • Description: Manage IDE integration.
  • Sub-commands:
    • disable:
      • Description: Disable IDE integration.
    • enable:
      • Description: Enable IDE integration.
    • install:
      • Description: Install required IDE companion.
    • status:
      • Description: Check status of IDE integration.

/init

  • Description: To help users easily create a GEMINI.md file, this command analyzes the current directory and generates a tailored context file, making it simpler for them to provide project-specific instructions to the Gemini agent.

/mcp

  • Description: Manage configured Model Context Protocol (MCP) servers.
  • Sub-commands:
    • auth:
      • Description: Authenticate with an OAuth-enabled MCP server.
      • Usage: /mcp auth <server-name>
      • Details: If <server-name> is provided, it initiates the OAuth flow for that server. If no server name is provided, it lists all configured servers that support OAuth authentication.
    • desc
      • Description: List configured MCP servers and tools with descriptions.
    • disable
      • Description: Disable an MCP server.
    • enable
      • Description: Enable a disabled MCP server.
    • list or ls:
      • Description: List configured MCP servers and tools. This is the default action if no subcommand is specified.
    • reload:
      • Description: Reloads all MCP servers and re-discovers their available tools.
    • schema:
      • Description: List configured MCP servers and tools with descriptions and schemas.

/memory

  • Description: Manage the AI's instructional context (hierarchical memory loaded from GEMINI.md files).
  • Sub-commands:
    • add:
      • Description: Adds the following text to the AI's memory. Usage: /memory add <text to remember>
    • list:
      • Description: Lists the paths of the GEMINI.md files in use for hierarchical memory.
    • refresh:
      • Description: Reload the hierarchical instructional memory from all GEMINI.md files found in the configured locations (global, project/ancestors, and sub-directories). This command updates the model with the latest GEMINI.md content.
    • show:
      • Description: Display the full, concatenated content of the current hierarchical memory that has been loaded from all GEMINI.md files. This lets you inspect the instructional context being provided to the Gemini model.
    • Note: For more details on how GEMINI.md files contribute to hierarchical memory, see the CLI Configuration documentation.

/model

  • Description: Manage model configuration.
  • Sub-commands:
    • manage:
      • Description: Opens a dialog to configure the model.
    • set:
      • Description: Set the model to use.
      • Usage: /model set <model-name> [--persist]

/permissions

  • Description: Manage folder trust settings and other permissions.
  • Sub-commands:
    • trust:
      • Description: Manage folder trust settings.
      • Usage: /permissions trust [<directory-path>]

/plan

  • Description: Switch to Plan Mode (read-only) and view the current plan if one has been generated.
    • Note: This feature is enabled by default. It can be disabled via the general.plan.enabled setting in your configuration.
  • Sub-commands:
    • copy:
      • Description: Copy the currently approved plan to your clipboard.

/policies

  • Description: Manage policies.
  • Sub-commands:
    • list:
      • Description: List all active policies grouped by mode.

/privacy

  • Description: Display the Privacy Notice and allow users to select whether they consent to the collection of their data for service improvement purposes.

/quit (or /exit)

  • Description: Exit Gemini CLI.

/restore

  • Description: Restores the project files to the state they were in just before a tool was executed. This is particularly useful for undoing file edits made by a tool. If run without a tool call ID, it will list available checkpoints to restore from.
  • Usage: /restore [tool_call_id]
  • Note: Only available if checkpointing is configured via settings. See Checkpointing documentation for more details.

/rewind

  • Description: Navigates backward through the conversation history, letting you review past interactions and potentially revert both chat state and file changes.
  • Usage: Press Esc twice as a shortcut.
  • Features:
    • Select Interaction: Preview user prompts and file changes.
    • Action Selection: Choose to rewind history only, revert code changes only, or both.

/resume

  • Description: Browse and resume previous conversation sessions, and manage manual chat checkpoints.
  • Features:
    • Auto sessions: Run /resume to open the interactive session browser for automatically saved conversations.
    • Chat checkpoints: Use checkpoint subcommands directly (/resume save, /resume resume, etc.).
    • Management: Delete unwanted sessions directly from the browser
    • Resume: Select any session to resume and continue the conversation
    • Search: Use / to search through conversation content across all sessions
    • Session Browser: Interactive interface showing all saved sessions with timestamps, message counts, and first user message for context
    • Sorting: Sort sessions by date or message count
  • Note: All conversations are automatically saved as you chat - no manual saving required. See Session Management for complete details.
  • Alias: /chat provides the same behavior and subcommands.
  • Sub-commands:
    • list
      • Description: Lists available tags for manual chat checkpoints.
    • save <tag>
      • Description: Saves the current conversation as a tagged checkpoint.
    • resume <tag> (alias: load)
      • Description: Loads a previously saved tagged checkpoint.
    • delete <tag>
      • Description: Deletes a tagged checkpoint.
    • share [filename]
      • Description: Exports the current conversation to Markdown or JSON.
    • debug
      • Description: Export the most recent API request as JSON payload (nightly builds).
    • Compatibility alias: /resume checkpoints ... is still accepted for the same checkpoint commands.

/settings

  • Description: Open the settings editor to view and modify Gemini CLI settings.
  • Details: This command provides a user-friendly interface for changing settings that control the behavior and appearance of Gemini CLI. It is equivalent to manually editing the .gemini/settings.json file, but with validation and guidance to prevent errors. See the settings documentation for a full list of available settings.
  • Usage: Simply run /settings and the editor will open. You can then browse or search for specific settings, view their current values, and modify them as desired. Changes to some settings are applied immediately, while others require a restart.

/shells (or /bashes)

  • Description: Toggle the background shells view. This lets you view and manage long-running processes that you've sent to the background.

/setup-github

  • Description: Set up GitHub Actions to triage issues and review PRs with Gemini.

/skills

  • Description: Manage Agent Skills, which provide on-demand expertise and specialized workflows.
  • Sub-commands:
    • disable <name>:
      • Description: Disable a specific skill by name.
      • Usage: /skills disable <name>
    • enable <name>:
      • Description: Enable a specific skill by name.
      • Usage: /skills enable <name>
    • list:
      • Description: List all discovered skills and their current status (enabled/disabled).
    • reload:
      • Description: Refresh the list of discovered skills from all tiers (workspace, user, and extensions).

/stats

  • Description: Display detailed statistics for the current Gemini CLI session.
  • Sub-commands:
    • session:
      • Description: Show session-specific usage statistics, including duration, tool calls, and performance metrics. This is the default view.
    • model:
      • Description: Show model-specific usage statistics, including token counts and quota information.
    • tools:
      • Description: Show tool-specific usage statistics.

/terminal-setup

  • Description: Configure terminal keybindings for multiline input (VS Code, Cursor, Windsurf).

/theme

  • Description: Open a dialog that lets you change the visual theme of Gemini CLI.

/tools

  • Description: Display a list of tools that are currently available within Gemini CLI.
  • Usage: /tools [desc]
  • Sub-commands:
    • desc or descriptions:
      • Description: Show detailed descriptions of each tool, including each tool's name with its full description as provided to the model.
    • nodesc or nodescriptions:
      • Description: Hide tool descriptions, showing only the tool names.

/upgrade

  • Description: Open the Gemini Code Assist upgrade page in your browser. This lets you upgrade your tier for higher usage limits.
  • Note: This command is only available when logged in with Google.

/vim

  • Description: Toggle vim mode on or off. When vim mode is enabled, the input area supports vim-style navigation and editing commands in both NORMAL and INSERT modes.
  • Features:
    • Count support: Prefix commands with numbers (for example, 3h, 5w, 10G)
    • Editing commands: Delete with x, change with c, insert with i, a, o, O; complex operations like dd, cc, dw, cw
    • INSERT mode: Standard text input with escape to return to NORMAL mode
    • NORMAL mode: Navigate with h, j, k, l; jump by words with w, b, e; go to line start/end with 0, $, ^; go to specific lines with G (or gg for first line)
    • Persistent setting: Vim mode preference is saved to ~/.gemini/settings.json and restored between sessions
    • Repeat last command: Use . to repeat the last editing operation
    • Status indicator: When enabled, shows [NORMAL] or [INSERT] in the footer

Custom commands

Custom commands allow you to create personalized shortcuts for your most-used prompts. For detailed instructions on how to create, manage, and use them, see the dedicated Custom Commands documentation.

Input prompt shortcuts

These shortcuts apply directly to the input prompt for text manipulation.

  • Undo:

    • Keyboard shortcut: Press Alt+z or Cmd+z to undo the last action in the input prompt.

  • Redo:

    • Keyboard shortcut: Press Shift+Alt+Z or Shift+Cmd+Z to redo the last undone action in the input prompt.

At commands (@)

At commands are used to include the content of files or directories as part of your prompt to Gemini. These commands include git-aware filtering.

  • @<path_to_file_or_directory>

    • Description: Inject the content of the specified file or files into your current prompt. This is useful for asking questions about specific code, text, or collections of files.
    • Examples:
      • @path/to/your/file.txt Explain this text.
      • @src/my_project/ Summarize the code in this directory.
      • What is this file about? @README.md
    • Details:
      • If a path to a single file is provided, the content of that file is read.
      • If a path to a directory is provided, the command attempts to read the content of files within that directory and any subdirectories.
      • Spaces in paths should be escaped with a backslash (for example, @My\ Documents/file.txt).
      • The command uses the read_many_files tool internally. The content is fetched and then inserted into your query before being sent to the Gemini model.
      • Git-aware filtering: By default, git-ignored files (like node_modules/, dist/, .env, .git/) are excluded. This behavior can be changed via the context.fileFiltering settings.
      • File types: The command is intended for text-based files. While it might attempt to read any file, binary files or very large files might be skipped or truncated by the underlying read_many_files tool to ensure performance and relevance. The tool indicates if files were skipped.
    • Output: The CLI will show a tool call message indicating that read_many_files was used, along with a message detailing the status and the path(s) that were processed.

  • @ (Lone at symbol)

    • Description: If you type a lone @ symbol without a path, the query is passed as-is to the Gemini model. This might be useful if you are specifically talking about the @ symbol in your prompt.

Error handling for @ commands

  • If the path specified after @ is not found or is invalid, an error message will be displayed, and the query might not be sent to the Gemini model, or it will be sent without the file content.
  • If the read_many_files tool encounters an error (for example, permission issues), this will also be reported.

Shell mode and passthrough commands (!)

The ! prefix lets you interact with your system's shell directly from within Gemini CLI.

  • !<shell_command>

    • Description: Execute the given <shell_command> using bash on Linux/macOS or powershell.exe -NoProfile -Command on Windows (unless you override ComSpec). Any output or errors from the command are displayed in the terminal.
    • Examples:
      • !ls -la (executes ls -la and returns to Gemini CLI)
      • !git status (executes git status and returns to Gemini CLI)

  • ! (Toggle shell mode)

    • Description: Typing ! on its own toggles shell mode.
      • Entering shell mode:
        • When active, shell mode uses a different coloring and a "Shell Mode Indicator".
        • While in shell mode, text you type is interpreted directly as a shell command.
      • Exiting shell mode:
        • When exited, the UI reverts to its standard appearance and normal Gemini CLI behavior resumes.

  • Caution for all ! usage: Commands you execute in shell mode have the same permissions and impact as if you ran them directly in your terminal.

  • Environment variable: When a command is executed via ! or in shell mode, the GEMINI_CLI=1 environment variable is set in the subprocess's environment. This allows scripts or tools to detect if they are being run from within Gemini CLI.