Run Shell Commands with Gemini CLI: A Quick Guide

Overview

This guide will walk you through how to leverage the Gemini CLI’s powerful feature of running shell commands directly within your chat sessions and custom commands. You’ll learn how to enter shell mode, execute commands, interact with command prompts, and even instruct Gemini to run shell commands as part of your custom workflows, such as generating Git commit messages.

Prerequisites

• Gemini CLI installed and configured.
• Basic understanding of your terminal and common shell commands (e.g., ls, git diff, git add).
• Familiarity with creating custom commands in the Gemini CLI (recommended, as per the original tutorial).

Part 1: Running Shell Commands Directly in Chat

The Gemini CLI allows you to seamlessly switch to a shell mode within your chat session, enabling you to run terminal commands and have their output automatically incorporated into the chat’s context. This is incredibly useful for quickly checking file status, running scripts, or gathering information without leaving your current chat.

1. Enter Shell Mode

   To switch to shell mode from your active Gemini CLI chat session, type an exclamation mark (!) and press Enter.

   Indicator: You’ll notice a visual cue: the border color of the chat input will change to a slightly lighter blue, and text like “Shell mode enabled” will appear, confirming you are now in shell mode. Anything you type next will be interpreted as a shell command.

2. Execute a Shell Command

   Once in shell mode, simply type the desired shell command and press Enter. For instance, to list files and folders in your current directory, type ls.

   Outcome: The output of the command will be displayed within the chat history and used as context for Gemini. You will remain in shell mode after the command executes.

3. Interact with Commands Requiring Input

   Some shell commands may pause and wait for user input (e.g., npm run test might prompt you to press ‘Q’ to quit or ‘A’ to re-run tests). Simply typing ‘Q’ or ‘A’ directly in shell mode might be interpreted as a new, invalid command. To interact with the command’s prompt:

   1. Ensure the latest terminal output is highlighted and in focus.
   2. Press Ctrl + F. This action puts the focus on the last terminal output, allowing you to interact with it as you normally would in a terminal.
   3. Now, you can type your input (like Q to quit) and press Enter to interact with the running command.

4. Exit Shell Mode

   To return to regular chat mode from shell mode, you have two options:

   • Press the exclamation mark (!) again.
   • Press the Escape key.

   Either action will toggle you back to the standard chat interface.

Part 2: Using Shell Commands in Custom Commands

You can instruct Gemini to execute shell commands as part of your custom commands. This allows for more sophisticated workflows where Gemini can gather information from your system before processing a prompt.

1. Create a Custom Command File

   Navigate to your Gemini CLI’s commands folder and create a new file for your custom command. For example, create commit_message.toml.

   Tip: Naming the file appropriately (e.g., commit_message.toml) often dictates how you’ll invoke the command (e.g., /commit_message).

2. Define the Prompt and Shell Command

   Inside the new TOML file, define the command’s description and prompt. To include a shell command, use the following syntax within the prompt:

   !{your_shell_command}

   For example, to generate a commit message based on staged Git changes:

   description = "Create a commit message based on staged changes."
   
   prompt = "nGenerate a commit message listing and summarizing the main changes based on the following git diff:nn```diff
   !{git diff --staged}
   ```nnUse emojis in the message where appropriate."
   

   • The !{git diff --staged} part tells Gemini to execute the git diff --staged command.
   • The output of this command will be captured and inserted directly into the prompt where ```diff
!{git diff --staged}
``` is placed.
   • Gemini will then use this captured output as context to generate the commit message.

   Expert Note: The Gemini CLI executes the shell command before sending the prompt to the language model. The command’s output becomes part of the prompt itself.

3. Stage Your Changes (Example Workflow)

   Before using the custom command, ensure you have staged changes in your Git repository. You can do this using shell commands:

   1. Enter shell mode: !
   2. Stage all changes: git add .
   3. Exit shell mode: Escape

4. Execute Your Custom Command

   In your Gemini CLI chat session, type the command to invoke your custom command. For the example above, it would be /commit_message.

   Permission Prompt: When Gemini prepares to run the shell command as part of your custom command, it will ask for your permission. Allow it to proceed.

5. Receive and Use the Output

   Gemini will execute the shell command, use its output to generate a commit message, and display it in the chat. You can then use other Gemini CLI commands, like /copy, to copy the generated message and use it for your commit.

Conclusion

By mastering shell mode and integrating shell commands into your custom commands, you can significantly enhance your productivity and streamline your development workflow directly within the Gemini CLI.

Source: Gemini CLI Tutorial #8 – Running Shell Commands (YouTube)