@office-ai/aioncli-core 0.26.0 → 0.30.0

package/dist/docs/extensions/writing-extensions.md

@@ -0,0 +1,292 @@
+# Build Gemini CLI extensions
+
+Gemini CLI extensions let you expand the capabilities of Gemini CLI by adding
+custom tools, commands, and context. This guide walks you through creating your
+first extension, from setting up a template to adding custom functionality and
+linking it for local development.
+
+## Prerequisites
+
+Before you start, ensure you have the Gemini CLI installed and a basic
+understanding of Node.js.
+
+## Extension features
+
+Extensions offer several ways to customize Gemini CLI. Use this table to decide
+which features your extension needs.
+
+| Feature                                                        | What it is                                                                                                         | When to use it                                                                                                                                                                                                                                                                                 | Invoked by            |
+| :------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------- |
+| **[MCP server](reference.md#mcp-servers)**                     | A standard way to expose new tools and data sources to the model.                                                  | Use this when you want the model to be able to _do_ new things, like fetching data from an internal API, querying a database, or controlling a local application. We also support MCP resources (which can replace custom commands) and system instructions (which can replace custom context) | Model                 |
+| **[Custom commands](../cli/custom-commands.md)**               | A shortcut (like `/my-cmd`) that executes a pre-defined prompt or shell command.                                   | Use this for repetitive tasks or to save long, complex prompts that you use frequently. Great for automation.                                                                                                                                                                                  | User                  |
+| **[Context file (`GEMINI.md`)](reference.md#contextfilename)** | A markdown file containing instructions that are loaded into the model's context at the start of every session.    | Use this to define the "personality" of your extension, set coding standards, or provide essential knowledge that the model should always have.                                                                                                                                                | CLI provides to model |
+| **[Agent skills](../cli/skills.md)**                           | A specialized set of instructions and workflows that the model activates only when needed.                         | Use this for complex, occasional tasks (like "create a PR" or "audit security") to avoid cluttering the main context window when the skill isn't being used.                                                                                                                                   | Model                 |
+| **[Hooks](../hooks/index.md)**                                 | A way to intercept and customize the CLI's behavior at specific lifecycle events (e.g., before/after a tool call). | Use this when you want to automate actions based on what the model is doing, like validating tool arguments, logging activity, or modifying the model's input/output.                                                                                                                          | CLI                   |
+| **[Custom themes](reference.md#themes)**                       | A set of color definitions to personalize the CLI UI.                                                              | Use this to provide a unique visual identity for your extension or to offer specialized high-contrast or thematic color schemes.                                                                                                                                                               | User (via /theme)     |
+
+## Step 1: Create a new extension
+
+The easiest way to start is by using a built-in template. We'll use the
+`mcp-server` example as our foundation.
+
+Run the following command to create a new directory called `my-first-extension`
+with the template files:
+
+```bash
+gemini extensions new my-first-extension mcp-server
+```
+
+This creates a directory with the following structure:
+
+```
+my-first-extension/
+├── example.js
+├── gemini-extension.json
+└── package.json
+```
+
+## Step 2: Understand the extension files
+
+Your new extension contains several key files that define its behavior.
+
+### `gemini-extension.json`
+
+The manifest file tells Gemini CLI how to load and use your extension.
+
+```json
+{
+  "name": "mcp-server-example",
+  "version": "1.0.0",
+  "mcpServers": {
+    "nodeServer": {
+      "command": "node",
+      "args": ["${extensionPath}${/}example.js"],
+      "cwd": "${extensionPath}"
+    }
+  }
+}
+```
+
+- `name`: The unique name for your extension.
+- `version`: The version of your extension.
+- `mcpServers`: Defines Model Context Protocol (MCP) servers to add new tools.
+  - `command`, `args`, `cwd`: Specify how to start your server. The
+    `${extensionPath}` variable is replaced with the absolute path to your
+    extension's directory.
+
+### `example.js`
+
+This file contains the source code for your MCP server. It uses the
+`@modelcontextprotocol/sdk` to define tools.
+
+```javascript
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+
+const server = new McpServer({
+  name: 'prompt-server',
+  version: '1.0.0',
+});
+
+// Registers a new tool named 'fetch_posts'
+server.registerTool(
+  'fetch_posts',
+  {
+    description: 'Fetches a list of posts from a public API.',
+    inputSchema: z.object({}).shape,
+  },
+  async () => {
+    const apiResponse = await fetch(
+      'https://jsonplaceholder.typicode.com/posts',
+    );
+    const posts = await apiResponse.json();
+    const response = { posts: posts.slice(0, 5) };
+    return {
+      content: [
+        {
+          type: 'text',
+          text: JSON.stringify(response),
+        },
+      ],
+    };
+  },
+);
+
+const transport = new StdioServerTransport();
+await server.connect(transport);
+```
+
+### `package.json`
+
+The standard configuration file for a Node.js project. It defines dependencies
+and scripts for your extension.
+
+## Step 3: Add extension settings
+
+Some extensions need configuration, such as API keys or user preferences. Let's
+add a setting for an API key.
+
+1.  Open `gemini-extension.json`.
+2.  Add a `settings` array to the configuration:
+
+    ```json
+    {
+      "name": "mcp-server-example",
+      "version": "1.0.0",
+      "settings": [
+        {
+          "name": "API Key",
+          "description": "The API key for the service.",
+          "envVar": "MY_SERVICE_API_KEY",
+          "sensitive": true
+        }
+      ],
+      "mcpServers": {
+        // ...
+      }
+    }
+    ```
+
+When a user installs this extension, Gemini CLI will prompt them to enter the
+"API Key". The value will be stored securely in the system keychain (because
+`sensitive` is true) and injected into the MCP server's process as the
+`MY_SERVICE_API_KEY` environment variable.
+
+## Step 4: Link your extension
+
+Link your extension to your Gemini CLI installation for local development.
+
+1.  **Install dependencies:**
+
+    ```bash
+    cd my-first-extension
+    npm install
+    ```
+
+2.  **Link the extension:**
+
+    The `link` command creates a symbolic link from the Gemini CLI extensions
+    directory to your development directory. Changes you make are reflected
+    immediately.
+
+    ```bash
+    gemini extensions link .
+    ```
+
+Restart your Gemini CLI session to use the new `fetch_posts` tool. Test it by
+asking: "fetch posts".
+
+## Step 5: Add a custom command
+
+Custom commands create shortcuts for complex prompts.
+
+1.  Create a `commands` directory and a subdirectory for your command group:
+
+    ```bash
+    mkdir -p commands/fs
+    ```
+
+2.  Create a file named `commands/fs/grep-code.toml`:
+
+    ```toml
+    prompt = """
+    Please summarize the findings for the pattern `{{args}}`.
+
+    Search Results:
+    !{grep -r {{args}} .}
+    """
+    ```
+
+    This command, `/fs:grep-code`, takes an argument, runs the `grep` shell
+    command, and pipes the results into a prompt for summarization.
+
+After saving the file, restart Gemini CLI. Run `/fs:grep-code "some pattern"` to
+use your new command.
+
+## Step 6: Add a custom `GEMINI.md`
+
+Provide persistent context to the model by adding a `GEMINI.md` file to your
+extension. This is useful for setting behavior or providing essential tool
+information.
+
+1.  Create a file named `GEMINI.md` in the root of your extension directory:
+
+    ```markdown
+    # My First Extension Instructions
+
+    You are an expert developer assistant. When the user asks you to fetch
+    posts, use the `fetch_posts` tool. Be concise in your responses.
+    ```
+
+2.  Update your `gemini-extension.json` to load this file:
+
+    ```json
+    {
+      "name": "my-first-extension",
+      "version": "1.0.0",
+      "contextFileName": "GEMINI.md",
+      "mcpServers": {
+        "nodeServer": {
+          "command": "node",
+          "args": ["${extensionPath}${/}example.js"],
+          "cwd": "${extensionPath}"
+        }
+      }
+    }
+    ```
+
+Restart Gemini CLI. The model now has the context from your `GEMINI.md` file in
+every session where the extension is active.
+
+## (Optional) Step 7: Add an Agent Skill
+
+[Agent Skills](../cli/skills.md) bundle specialized expertise and workflows.
+Skills are activated only when needed, which saves context tokens.
+
+1.  Create a `skills` directory and a subdirectory for your skill:
+
+    ```bash
+    mkdir -p skills/security-audit
+    ```
+
+2.  Create a `skills/security-audit/SKILL.md` file:
+
+    ```markdown
+    ---
+    name: security-audit
+    description:
+      Expertise in auditing code for security vulnerabilities. Use when the user
+      asks to "check for security issues" or "audit" their changes.
+    ---
+
+    # Security Auditor
+
+    You are an expert security researcher. When auditing code:
+
+    1. Look for common vulnerabilities (OWASP Top 10).
+    2. Check for hardcoded secrets or API keys.
+    3. Suggest remediation steps for any findings.
+    ```
+
+Gemini CLI automatically discovers skills bundled with your extension. The model
+activates them when it identifies a relevant task.
+
+## Step 8: Release your extension
+
+When your extension is ready, share it with others via a Git repository or
+GitHub Releases. Refer to the [Extension Releasing Guide](./releasing.md) for
+detailed instructions and learn how to list your extension in the gallery.
+
+## Next steps
+
+- [Extension reference](reference.md): Deeply understand the extension format,
+  commands, and configuration.
+- [Best practices](best-practices.md): Learn strategies for building great
+  extensions.

package/dist/docs/get-started/authentication.md

@@ -17,6 +17,7 @@ Select the authentication method that matches your situation in the table below:
 | Organization users with a company, school, or Google Workspace account | [Login with Google](#login-google)                               | [Yes](#set-gcp)                                             |
 | AI Studio user with a Gemini API key                                   | [Use Gemini API Key](#gemini-api)                                | No                                                          |
 | Google Cloud Vertex AI user                                            | [Vertex AI](#vertex-ai)                                          | [Yes](#set-gcp)                                             |
+| AWS Bedrock user with Anthropic Claude models                          | [AWS Bedrock](#aws-bedrock)                                      | No (AWS account required)                                   |
 | [Headless mode](#headless)                                             | [Use Gemini API Key](#gemini-api) or<br> [Vertex AI](#vertex-ai) | No (for Gemini API Key)<br> [Yes](#set-gcp) (for Vertex AI) |
 
 ### What is my Google account type?
@@ -215,6 +216,167 @@ pipelines, or if your organization restricts user-based ADC or API key creation.
 
 5.  Select **Vertex AI**.
 
+## Use AWS Bedrock <a id="aws-bedrock"></a>
+
+To use Gemini CLI with AWS Bedrock and Anthropic Claude models, choose from the
+following authentication options:
+
+- A. AWS Profile (recommended for local development)
+- B. AWS Environment Variables
+- C. IAM Role (for EC2/ECS/Lambda environments)
+
+### Prerequisites
+
+Before using AWS Bedrock authentication:
+
+1. **AWS Account**: You need an AWS account with access to Amazon Bedrock.
+
+2. **Model Access**: Request access to Anthropic Claude models in the AWS
+   Bedrock console:
+   - Navigate to [AWS Bedrock Console](https://console.aws.amazon.com/bedrock)
+   - Go to "Model access" in the left sidebar
+   - Request access to Claude models (Claude 3.5, Claude 4, etc.)
+
+3. **IAM Permissions**: Ensure your AWS credentials have the following
+   permissions:
+   ```json
+   {
+     "Version": "2012-10-17",
+     "Statement": [
+       {
+         "Effect": "Allow",
+         "Action": [
+           "bedrock:InvokeModel",
+           "bedrock:InvokeModelWithResponseStream"
+         ],
+         "Resource": "arn:aws:bedrock:*::foundation-model/anthropic.claude-*"
+       }
+     ]
+   }
+   ```
+
+### A. AWS Bedrock - AWS Profile (Recommended)
+
+This is the recommended method for local development and supports multiple AWS
+accounts.
+
+1. Configure your AWS credentials using AWS CLI:
+
+   ```bash
+   # Configure a new AWS profile
+   aws configure --profile enterprise-ai
+   # Enter your AWS Access Key ID, Secret Access Key, and default region
+   ```
+
+   Or manually edit `~/.aws/credentials`:
+
+   ```ini
+   [enterprise-ai]
+   aws_access_key_id = YOUR_ACCESS_KEY
+   aws_secret_access_key = YOUR_SECRET_KEY
+   ```
+
+   And `~/.aws/config`:
+
+   ```ini
+   [profile enterprise-ai]
+   region = ap-southeast-1
+   output = json
+   ```
+
+2. Set the AWS profile and region environment variables:
+
+   ```bash
+   export AWS_PROFILE="enterprise-ai"
+   export AWS_REGION="ap-southeast-1"
+   ```
+
+   To make this setting persistent, see
+   [Persisting Environment Variables](#persisting-vars).
+
+3. Start the CLI:
+
+   ```bash
+   gemini
+   ```
+
+   Gemini CLI will automatically detect AWS Bedrock credentials and use them.
+
+### B. AWS Bedrock - Environment Variables
+
+Use this method for CI/CD pipelines or temporary credentials.
+
+1. Set AWS credentials as environment variables:
+
+   ```bash
+   export AWS_ACCESS_KEY_ID="YOUR_ACCESS_KEY"
+   export AWS_SECRET_ACCESS_KEY="YOUR_SECRET_KEY"
+   export AWS_REGION="us-east-1"
+   ```
+
+   For temporary credentials (STS), also include:
+
+   ```bash
+   export AWS_SESSION_TOKEN="YOUR_SESSION_TOKEN"
+   ```
+
+2. Start the CLI:
+
+   ```bash
+   gemini
+   ```
+
+   > **Warning:** Treat AWS credentials as sensitive information. Never commit
+   > them to version control or share them publicly.
+
+### C. AWS Bedrock - IAM Role
+
+When running in AWS environments (EC2, ECS, Lambda, etc.), IAM roles provide
+automatic authentication without managing credentials.
+
+1. Attach an IAM role with Bedrock permissions to your compute resource.
+
+2. Set the AWS region:
+
+   ```bash
+   export AWS_REGION="us-east-1"
+   ```
+
+3. Start the CLI:
+
+   ```bash
+   gemini
+   ```
+
+   Gemini CLI will automatically use the IAM role credentials.
+
+### Selecting Claude Models
+
+By default, Gemini CLI uses `anthropic.claude-sonnet-4-5-20250929-v1:0`. To use
+a different model, set the model via configuration or command line.
+
+Available Claude models in Bedrock:
+
+- `anthropic.claude-opus-4-5-20251101-v1:0` (Claude Opus 4.5)
+- `anthropic.claude-sonnet-4-5-20250929-v1:0` (Claude Sonnet 4.5, default)
+- `anthropic.claude-haiku-4-5-20251001-v1:0` (Claude Haiku 4.5)
+- `anthropic.claude-3-5-sonnet-20241022-v2:0` (Claude 3.5 Sonnet)
+
+For regional availability and the complete list of models, see the
+[AWS Bedrock documentation](https://docs.aws.amazon.com/bedrock/latest/userguide/models-regions.html).
+
+### Regional Model Availability
+
+Claude models are available in specific AWS regions. Ensure your `AWS_REGION`
+supports your chosen model:
+
+- **us-east-1, us-west-2**: All Claude models
+- **eu-west-1, eu-central-1**: Most Claude models
+- **ap-southeast-1, ap-northeast-1**: Selected Claude models
+
+If you encounter a model availability error, the CLI will display available
+regions for your model and suggest solutions.
+
 ## Set your Google Cloud project <a id="set-gcp"></a>
 
 > **Important:** Most individual Google accounts (free and paid) don't require a

package/dist/docs/get-started/configuration-v1.md

@@ -166,19 +166,21 @@ a few things you can try in order of recommendation:
   - **Default:** All tools available for use by the Gemini model.
   - **Example:** `"coreTools": ["ReadFileTool", "GlobTool", "ShellTool(ls)"]`.
 
-- **`allowedTools`** (array of strings):
+- **`allowedTools`** (array of strings) [DEPRECATED]:
   - **Default:** `undefined`
   - **Description:** A list of tool names that will bypass the confirmation
     dialog. This is useful for tools that you trust and use frequently. The
-    match semantics are the same as `coreTools`.
+    match semantics are the same as `coreTools`. **Deprecated**: Use the
+    [Policy Engine](../core/policy-engine.md) instead.
   - **Example:** `"allowedTools": ["ShellTool(git status)"]`.
 
-- **`excludeTools`** (array of strings):
+- **`excludeTools`** (array of strings) [DEPRECATED]:
   - **Description:** Allows you to specify a list of core tool names that should
     be excluded from the model. A tool listed in both `excludeTools` and
     `coreTools` is excluded. You can also specify command-specific restrictions
     for tools that support it, like the `ShellTool`. For example,
     `"excludeTools": ["ShellTool(rm -rf)"]` will block the `rm -rf` command.
+    **Deprecated**: Use the [Policy Engine](../core/policy-engine.md) instead.
   - **Default**: No tools excluded.
   - **Example:** `"excludeTools": ["run_shell_command", "findFiles"]`.
   - **Security Note:** Command-specific restrictions in `excludeTools` for
@@ -215,14 +217,6 @@ a few things you can try in order of recommendation:
     MCP servers of their own. This should not be used as an airtight security
     mechanism.
 
-- **`autoAccept`** (boolean):
-  - **Description:** Controls whether the CLI automatically accepts and executes
-    tool calls that are considered safe (e.g., read-only operations) without
-    explicit user confirmation. If set to `true`, the CLI will bypass the
-    confirmation prompt for tools deemed safe.
-  - **Default:** `false`
-  - **Example:** `"autoAccept": true`
-
 - **`theme`** (string):
   - **Description:** Sets the visual [theme](../cli/themes.md) for Gemini CLI.
   - **Default:** `"Default"`