The Gemini CLI extension for Elasticsearch with tools and skills

We're glad to announce the release of our Elastic extension for Google's Gemini CLI, bringing the full power of Elasticsearch and Elastic Agent Builder directly into your AI development workflow. This extension also offers several recently developed agent skills for interacting with Elasticsearch.

The extension is available as an open source project here.

What is Gemini CLI, and how do you install it?

Gemini CLI is an open source AI agent that brings Google’s Gemini models directly into the command line. It allows developers to interact with AI from the terminal to perform tasks such as generating code, editing files, running shell commands, and retrieving information from the web.

Unlike typical chat interfaces, Gemini CLI integrates with your local development environment, meaning that it can understand project context, modify files, run builds or tests, and automate workflows directly within the terminal. This makes it useful for developers, site reliability engineers (SREs), and engineers who want AI-assisted coding and automation without leaving their command-line workflow.

Gemini CLI can be installed using several package managers. The most common method is via npm:

npm install -g @google/gemini-cli

If you want to know alternative installation options, refer to the official installation page.

After installation, start the CLI by running:

gemini

You see a screen, as shown in Figure 1:

**Figure 1:** A screenshot of Gemini CLI.

Configure Elasticsearch

We need to have an Elasticsearch instance running. If you want to use the Model Context Protocol (MCP) server, you also need Kibana 9.3+ installed. To use the Elasticsearch Query Language (ES|QL) skill (esql) described below, Kibana is not required.

You can activate a free trial on Elastic Cloud or install it locally using the start-local script:

curl -fsSL https://elastic.co/start-local | sh

This will install Elasticsearch and Kibana on your computer and will generate an API key to be used for configuring Gemini CLI.

The API key will be shown as output of the previous command and stored in a .env file in the elastic-start-local folder.

If you’re using on-premises Elasticsearch (for example, using start-local), and you want to use Elastic Agent Builder with MCP, you also need to connect a large language model (LLM). You can read this documentation page to understand the different options.

If you’re using Elastic Cloud (or serverless), you already have a prebuilt LLM connection in place.

Install the Elasticsearch extension

You can install the Elasticsearch extension for Gemini CLI with the following command:

gemini extensions install https://github.com/elastic/gemini-cli-elasticsearch

You can check that the extensions have been installed successfully by opening Gemini and executing the following command:

/extensions list

You should see the Elasticsearch extension available.

If you want to use the MCP integration, you need to have an Elasticsearch 9.3+ version installed. You need your MCP server URL from Kibana:

Get your MCP server URL from Agents > View all tools > Manage MCP > Copy MCP Server URL.
The URL will look like this: https://your-kibana-instance/api/agent_builder/mcp

You need the Elasticsearch endpoint URL. This is typically reported at the top of the Kibana Elasticsearch page. If you’re running Elasticsearch with start-local, you already have the endpoint in the ES_LOCAL_URL key in the start-local .env file.

You also need an API key. If you’re running Elasticsearch with start-local, you already have the ES_LOCAL_API_KEY in the start-local .env file. Otherwise, you can create an API key using the Kibana interface, as reported here:

In Kibana: Stack Management > Security > API Keys > Create API key.
We suggest setting only the read privileges for the API key, enabling the feature_agentBuilder.read privilege as reported here.
Copy the encoded API key value.

Set the required environment variables in your shell:

export ELASTIC_URL="your-elasticsearch-url"
export ELASTIC_MCP_URL="your-elasticsearch-mcp-url"
export ELASTIC_API_KEY="your-encoded-api-key"

Install the example dataset

You can install the eCommerce orders dataset available from Kibana. It includes a single index named kibana_sample_data_ecommerce, containing information for 4,675 orders from an ecommerce website. For each order, we have the following information:

Customer information (name, ID, birth date, email, and more).
Order date.
Order ID.
Products (list of all the products with price, quantity, ID, category, discount, and other details).
SKU.
Total price (taxless, taxed).
Total quantity.
Geo information (city, country, continent, location, region).

To install the sample data, open the Integrations page in Kibana (search for “Integration” in the top search bar) and install the Sample Data. For more details, refer to the documentation here.

The goal of this article is to show how easy it is to configure Gemini CLI to connect to Elasticsearch and interact with the kibana_sample_data_ecommerce index.

How to use the Elasticsearch MCP

You can check the connection using the following command in Gemini:

/mcp list

You should see the elastic-agent-builder enabled, as shown in Figure 2:

**Figure 2:** The `elastic-agent-builder` MCP server with the list of tools.

Elasticsearch provides a default set of tools. See the description here.

Using these tools, you can interact with Elasticsearch, asking questions like:

Give me the list of all the indexes available in Elasticsearch.
How many customers are based in the USA in the kibana_sample_data_ecommerce index of Elasticsearch?

Depending on the question, Gemini will use one or more of the available tools to try to answer it.

The /elastic commands

In the Elasticsearch extension for Gemini CLI, we also added /elastic commands.

If you execute the /help command, you see all the available /elastic options (Figure 3):

**Figure 3:** The available `/elastic` commands.

These commands can be useful if you want to directly execute a specific tool of the elastic-agent-builder MCP server. For instance, using the following command, you can get the mapping of the kibana_sample_data_ecommerce:

/elastic:get-mapping kibana_sample_data_ecommerce

These commands are essentially shortcuts for executing specific tools, rather than relying on the Gemini model to determine which tool should be invoked.

How to use the Elasticsearch skills

This extension also comes with an agent skill for ES|QL, the Elasticsearch Query Language available in Elasticsearch. Agent Skills is an open format that gives AI coding agents, like Gemini CLI, custom instructions for specific tasks. They use a concept called progressive disclosure, meaning that only a brief description of the skill is added to the initial system prompt. When you ask the agent to perform a task, like querying Elasticsearch, it matches the request to the relevant skill and dynamically loads the detailed instructions. This is an efficient way to manage token budgets while providing the AI with exactly the context it needs.

The esql skill is designed to let Gemini CLI write and execute ES|QL queries directly against your cluster. ES|QL is a powerful piped query language that makes data exploration, log analysis, and aggregations highly intuitive. With this skill enabled, you don't need to look up ES|QL syntax; you can simply ask the Gemini CLI natural language questions about your data, and the agent will handle the rest.

The executions are performed using simple curl commands run in a terminal. This is possible because Elasticsearch provides a rich set of REST APIs that can be easily used to integrate the system into any architecture.

What the esql skill offers:

Index and schema discovery: The agent can use the skill's built-in tools to list available indices and fetch field mappings. For instance, before writing a query for the eCommerce dataset, the agent can run a schema check on kibana_sample_data_ecommerce to understand the available fields, like taxful_total_price or category.
Seamless natural language translation: The skill gives the agent more than just a plain reference manual; it provides a specific guide for interpreting user intent. When you type natural language requests, like "Show average response time grouped by service," the agent uses the skill's bundled pattern matching to instantly translate your words into the correct ES|QL aggregations, filters, and commands.
Self-correct: If a query fails (for example, due to a type mismatch or syntax error), the skill returns the generated query alongside the exact Elasticsearch error message, allowing the agent to instantly fix the query and try again without you having to intervene.

Since the esql skill is also available as a tool in the elastic-agent-builder MCP server, we need to disable this server momentarily. You can use the following command to disable it:

/mcp disable elastic-agent-builder

Then you can simply type a prompt like this into your Gemini CLI:

Find the top 5 product categories by total sales revenue in the kibana_sample_data_ecommerce index

The agent will:

Recognize the need for the esql skill.
Check the schema of kibana_sample_data_ecommerce.
Construct an ES|QL query, like: FROM kibana_sample_data_ecommerce | STATS total_revenue = SUM(taxful_total_price) BY category.keyword | SORT total_revenue DESC | LIMIT 5.
Execute the query against the Elasticsearch API.
Present the final answer to you right in the terminal.

Here, we reported an example of response from Gemini to the previous prompt:

───────────────────────────────────────────────────────────
> Find the top 5 product categories by total sales revenue in the kibana_sample_data_ecommerce index   ───────────────────────────────────────────────────────────
✓  Activate Skill "esql": Interact with Elasticsearch using ES|QL and curl. Use when querying, managing indices,  …
Skill esql activated. Resources loaded from /home/user/.gemini/extensions/elasticsearch/skills/esql: 
Showing up to 200 items (files + folders).                                                                     /home/user/.gemini/extensions/elasticsearch/skills/esql/                                                            ├───SKILL.md 
└───references/
├───esql-reference.md 
├───generation-tips.md 
└───query-patterns.md

✦ I will start by exploring the mapping of the kibana_sample_data_ecommerce index to identify the fields for product category and sales revenue. Then, I will construct and execute an ES|QL query to determine the top 5 product categories by total sales revenue.

✓  Shell curl -s "${ELASTIC_URL%/}/kibana_sample_data_ecommerce/_mapping" -H "Authorization: ApiKey $(printenv ELAS…                                                                                                                       {  
   "kibana_sample_data_ecommerce": { 
     "mappings": { 
       "properties": {
         "category": { 
           "type": "text", 
           "fields": {
             "keyword": {
               "type": "keyword"
             }
           }
         }, 
         "currency": {
           "type": "keyword"
         }, 

✦ Okay, I have the mapping. The category is products.category.keyword and sales revenue is taxful_total_price. I'll now execute the ES|QL query to get the top 5 categories by revenue.

✓  Shell curl -s -X POST "${ELASTIC_URL%/}/_query" \  -H "Authorization: ApiKey $(printenv ELASTIC_API_KEY)" \  -H …
{ 
   "took": 62,
   "is_partial": false, 
   "completion_time_in_millis": 1772805644164,
   "documents_found": 4675,
   "values_loaded": 12084, 
   "start_time_in_millis": 1772805644102, 
   "expiration_time_in_millis": 1773237644087,  
   "columns": [ 
     { 
       "name": "total_revenue",    
       "type": "double"  
     }, 
     {   
       "name": "products.category.keyword",

✦ The query for top 5 product categories by revenue was successful. I'll format the returned JSON values into a   user-friendly list.

 ✓  Shell 
                             
 Top 5 product categories by total sales revenue: 
 1. Men's Clothing: 149393.91
 2. Women's Clothing: 135099.91
 3. Women's Shoes: 105479.17
 4. Men's Shoes: 91797.92
 5. Women's Accessories: 60830.31 

✦ I've found the answer; now I'll format it for clarity.

 ✓  Shell 

 Here are the top 5 product categories by total sales revenue:                                                        
                                                                      
 | Rank | Category              | Total Revenue | 
 |------|-----------------------|---------------| 
 | 1    | Men's Clothing        | 149,393.91    |
 | 2    | Women's Clothing      | 135,099.91    |
 | 3    | Women's Shoes         | 105,479.17    |
 | 4    | Men's Shoes           | 91,797.92     | 
 | 5    | Women's Accessories   | 60,830.31     | 

✦ I've formatted and presented the answer. I'm finished.
 ───────────────────────────────────────────────────────────

It’s interesting to note how the Gemini model generates the final response by showing all the steps it follows. Here, you can clearly see the influence of the skill in the model’s reasoning process. The first time the model recognizes that it needs to use a skill or execute a shell command, it requests permission using the human-in-the-loop approach.

By handling the heavy lifting of schema discovery, query generation, and execution, the esql skill lets you focus entirely on the answers rather than the mechanics of getting them. You’ll get the data you need, properly formatted and right in your terminal, all without ever writing a single line of syntax or context-switching to a different application.

Conclusion

In this article, we presented the Elasticsearch extension for Gemini CLI that we recently released. This extension gives you the ability to interact with your Elasticsearch instance using Gemini and the Elasticsearch MCP server provided by Elastic Agent Builder, available starting from version 9.3.0, as well as the /elastic command.

Moreover, the extension also includes an esql skill that converts a user’s request from natural language into an ES|QL query. This skill can be particularly useful when the MCP server cannot be used, since the underlying communication is driven by simple curl commands executed in a terminal. Elasticsearch offers a rich set of REST APIs that can be easily integrated into any project. This is especially useful when developing agentic AI applications.

For more information about our Gemini CLI extension, visit the project repository here.

Ready to try this out on your own? Start a free trial.

Elasticsearch has integrations for tools from LangChain, Cohere and more. Join our advanced semantic search webinar to build your next GenAI app!