Gemini CLI icon

Gemini CLI

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

Actions7

Overview

The node integrates with the Google Gemini CLI to perform AI-powered coding and planning tasks. It supports multiple operations such as querying the AI assistant, generating detailed execution plans for tasks, editing existing plans, approving plans for execution, executing approved plans step-by-step, and listing all stored plans.

This node is beneficial in scenarios where users want to automate software development workflows, generate structured task plans, or interact with an AI assistant for code generation and project management. For example, a developer can use it to create a multi-step plan for implementing a new feature, modify that plan based on feedback, approve it, and then execute each step while tracking progress.

Properties

Name Meaning
Model Choose the Gemini model to use:
- Gemini 2.5 Pro: Most capable model with 1M token context window
- Gemini 2.5 Flash: Fast and efficient model for quick responses
Max Turns Maximum number of conversation turns (back-and-forth exchanges) allowed during query or conversation operations
Timeout Maximum time in seconds to wait for Gemini CLI completion before aborting
Project Path Directory path where Gemini CLI should run (e.g., /path/to/project). If empty, uses the current working directory. This allows Gemini CLI to access files and run commands in the specified project location
Output Format How to format the output data:
- Messages: Raw array of all messages exchanged
- 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 the final result text
Additional Options Collection of optional settings:
- API Key: Gemini API key if not set via environment variable
- Use Vertex AI: Whether to use Vertex AI instead of Gemini API
- System Prompt: Additional instructions/context
- Debug Mode: Enable debug logging
Tools Configuration Configure built-in tools and external integrations:
- Enable Built-in Tools: Select from File System, Shell Commands, Web Fetch, Web Search
- Security Mode: Safe (confirmations required), Auto-Approve (YOLO), Sandbox
- Enable Checkpointing: Save conversation state
MCP Servers Configure external MCP (Model Context Protocol) servers for extended functionality:
Supports connection via command execution or HTTP URL, environment variables, tool inclusion/exclusion lists, trust level, timeout, and working directory

Output

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

  • Messages: An array of message objects exchanged with Gemini CLI, including user inputs, assistant responses, and errors.
  • Plan: A detailed execution plan object containing:
    • id: Unique plan identifier
    • title: Brief title of the task
    • description: Detailed description
    • steps: Array of steps, each with id, description, optional command, optional files array, estimated duration, and status
    • Metadata like creation/modification timestamps and status (draft, approved, executing, completed, failed)
  • Plan Status: Current progress and status of a plan execution, including counts of completed and failed steps.
  • Structured: An object combining messages, summary statistics (counts of user/assistant/error messages), the final result text, performance metrics, configuration details, and success status.
  • Text: The final result text only, suitable for simple use cases.

If the node executes a plan, the output includes detailed results per step and overall plan status.

No binary data output is produced by this node.

Dependencies

  • Requires the Google Gemini CLI installed and accessible in the system PATH (gemini command).
  • Optionally requires a valid Gemini API key provided either via input property or environment variable.
  • Supports integration with Vertex AI if enabled.
  • May require proper permissions and existence of the specified project directory.
  • Optional external MCP servers can be configured for extended capabilities.
  • Node uses child process spawning to run the Gemini CLI commands.

Troubleshooting

  • Gemini CLI Not Installed or Inaccessible: The node checks for the presence of the gemini command. If missing, it throws an error instructing to install the CLI globally via npm.
  • Invalid Project Path: If the specified project path 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 like "query", "continue", and "generate_plan" require a non-empty prompt; plan-related operations require a valid plan ID.
  • Plan Not Found: Editing, approving, or executing a plan with a non-existent ID will cause an error.
  • Plan Not Approved: Attempting to execute a plan that is not marked as approved will fail.
  • Timeouts: If Gemini CLI takes longer than the specified timeout, the process is killed and an error is returned.
  • JSON Parsing Errors: When generating or editing plans, the node expects a valid JSON response from Gemini CLI. Malformed or missing JSON will cause parsing errors.
  • Debug Mode: Enabling debug mode provides detailed logs which help diagnose issues related to CLI invocation, environment, and responses.

Links and References

This summary covers the "List Plans" operation within the "Default" resource context, describing the node's behavior, properties, outputs, dependencies, and common troubleshooting points.

Discussion