Gemini CLI icon

Gemini CLI

Use Google Gemini CLI to execute AI-powered coding tasks with multimodal capabilities

Actions7

Overview

The Gemini CLI node integrates with the Google Gemini CLI tool to perform AI-powered coding and project management tasks. It enables users to interact with Gemini models to generate, edit, approve, execute, and query execution plans for software projects or other complex workflows. The node supports multimodal capabilities and can run commands, read/write files, fetch web content, and perform web searches as part of its operations.

Typical use cases include:

  • Generating detailed step-by-step execution plans for coding tasks.
  • Modifying existing plans based on new instructions.
  • Approving plans before execution.
  • Executing approved plans stepwise, including running shell commands or modifying files.
  • Querying or continuing conversations with the Gemini model for interactive assistance.
  • Listing stored execution plans for review.

For example, a user might provide a prompt like "Create a Python function to parse CSV files" and receive a structured plan breaking down the task into actionable steps with estimated durations. Later, they could approve and execute this plan automatically within their project directory.

Properties

Name Meaning
Prompt The instruction or query sent to Gemini CLI. Required for operations: query, continue, generate_plan. Supports expressions to dynamically set content from previous nodes.
Model The Gemini model to use:
- Gemini 2.5 Pro (most capable, 1M token context)
- Gemini 2.5 Flash (fast and efficient)
Max Turns Maximum number of conversation turns allowed in back-and-forth exchanges.
Timeout Maximum time in seconds to wait for Gemini CLI completion before aborting.
Project Path Directory path where Gemini CLI runs, allowing access to project files and command execution. If empty, defaults to current working directory.
Output Format How to format the output data:
- Messages: raw array of all exchanged messages
- Plan: execution plan structure (for plan-related operations)
- Plan Status: progress and status of plan execution
- Structured: object with messages, summary, result, metrics
- Text: only final result text
Additional Options Collection of optional settings:
- API Key: Gemini API key if not set via environment variable
- Use Vertex AI: toggle to use Vertex AI instead of Gemini API
- System Prompt: extra context/instructions for Gemini CLI
- Debug Mode: enable debug logging
Tools Configuration Configure built-in tools and integrations:
- Enable Built-in Tools: select from File System, Shell Commands, Web Fetch, Web Search
- Security Mode: safe (confirmations required), auto-approve (YOLO mode), sandbox (restricted)
- Enable Checkpointing: save conversation state
MCP Servers Configure external MCP servers for extended functionality:
- Server connection details (command or HTTP)
- Environment variables
- Tool inclusion/exclusion lists
- Trust level and timeout settings
- Working directory for server command

Output

The node outputs JSON objects whose structure depends on the operation and selected output format:

  • Messages: An array of message objects representing the full conversation or interaction with Gemini CLI, including user inputs, assistant responses, and errors.
  • Plan: A structured execution plan object containing:
    • id: unique plan identifier
    • title: brief title of the task
    • description: detailed description
    • steps: array of steps, each with:
      • id: step identifier
      • description: what the step does
      • command: optional shell command to run
      • files: optional list of files involved
      • estimated_duration: expected duration in seconds
      • status: current step status (e.g., pending, in_progress, completed)
    • created_at, modified_at: timestamps
    • status: overall plan status (draft, approved, executing, completed, failed)
    • original_prompt: initial prompt text
    • configuration: metadata about model, project path, tools enabled, etc.
  • Plan Status: Includes the plan object plus execution results and a summary of completed/failed steps and final status.
  • Structured: Combines messages, summary statistics (counts of user/assistant/error messages), final result text, performance metrics, configuration details, and success flag.
  • Text: Only the final textual result from Gemini CLI.

If binary data were supported, it would be summarized here, but this node focuses on JSON/textual data.

Dependencies

  • Requires the Gemini CLI installed and accessible in the system PATH (gemini command).
  • Optionally requires an API key credential for Gemini API or Vertex AI, which can be provided via node parameters or environment variables.
  • Uses Node.js child process APIs to spawn the Gemini CLI subprocess.
  • Access to the file system for reading/writing plans and project files.
  • Optional external MCP servers configured by the user for extended protocol support.
  • n8n environment should allow execution of child processes and have proper permissions for specified project directories.

Troubleshooting

  • Gemini CLI Not Found or Not Installed: The node checks for the presence of the gemini command. If missing, it throws an error advising installation via npm install -g @google/gemini-cli.
  • Invalid Project Path: If the specified project directory does not exist, is not a directory, or lacks read/write permissions, the node will error out with a descriptive message.
  • Missing Required Parameters: Operations that require a prompt or plan ID will throw errors if these are empty or missing.
  • Timeouts: If Gemini CLI does not respond within the configured timeout, the node aborts with a timeout error.
  • Plan Not Found: For operations requiring a plan ID, if the plan file cannot be found, an error is thrown.
  • Plan Not Approved: Attempting to execute a plan that is not marked as approved results in an error.
  • JSON Parsing Errors: If Gemini CLI returns malformed or unexpected output when generating or editing plans, the node reports parsing failures.
  • Debug Mode: Enabling debug mode provides verbose logs to help diagnose issues.
  • Security Modes: Using "Auto-Approve (YOLO Mode)" can be risky; destructive operations may run without confirmation.
  • Permissions: Ensure the n8n process has permission to execute shell commands and access the project directory.

Links and References

This summary covers the static analysis of the Gemini CLI node's execute() method and related logic for the "Default" resource and "Generate Plan" operation, incorporating the provided input properties.

Discussion