@office-ai/aioncli-core 0.26.0 → 0.30.0

package/dist/docs/extensions/reference.md

@@ -0,0 +1,265 @@
+# Extension reference
+
+This guide covers the `gemini extensions` commands and the structure of the
+`gemini-extension.json` configuration file.
+
+## Manage extensions
+
+Use the `gemini extensions` command group to manage your extensions from the
+terminal.
+
+Note that commands like `gemini extensions install` are not supported within the
+CLI's interactive mode. However, you can use the `/extensions list` command to
+view installed extensions. All management operations, including updates to slash
+commands, take effect only after you restart the CLI session.
+
+### Install an extension
+
+Install an extension by providing its GitHub repository URL or a local file
+path.
+
+Gemini CLI creates a copy of the extension during installation. You must run
+`gemini extensions update` to pull changes from the source. To install from
+GitHub, you must have `git` installed on your machine.
+
+```bash
+gemini extensions install <source> [--ref <ref>] [--auto-update] [--pre-release] [--consent]
+```
+
+- `<source>`: The GitHub URL or local path of the extension.
+- `--ref`: The git ref (branch, tag, or commit) to install.
+- `--auto-update`: Enable automatic updates for this extension.
+- `--pre-release`: Enable installation of pre-release versions.
+- `--consent`: Acknowledge security risks and skip the confirmation prompt.
+
+### Uninstall an extension
+
+To uninstall one or more extensions, use the `uninstall` command:
+
+```bash
+gemini extensions uninstall <name...>
+```
+
+### Disable an extension
+
+Extensions are enabled globally by default. You can disable an extension
+entirely or for a specific workspace.
+
+```bash
+gemini extensions disable <name> [--scope <scope>]
+```
+
+- `<name>`: The name of the extension to disable.
+- `--scope`: The scope to disable the extension in (`user` or `workspace`).
+
+### Enable an extension
+
+Re-enable a disabled extension using the `enable` command:
+
+```bash
+gemini extensions enable <name> [--scope <scope>]
+```
+
+- `<name>`: The name of the extension to enable.
+- `--scope`: The scope to enable the extension in (`user` or `workspace`).
+
+### Update an extension
+
+Update an extension to the version specified in its `gemini-extension.json`
+file.
+
+```bash
+gemini extensions update <name>
+```
+
+To update all installed extensions at once:
+
+```bash
+gemini extensions update --all
+```
+
+### Create an extension from a template
+
+Create a new extension directory using a built-in template.
+
+```bash
+gemini extensions new <path> [template]
+```
+
+- `<path>`: The directory to create.
+- `[template]`: The template to use (e.g., `mcp-server`, `context`,
+  `custom-commands`).
+
+### Link a local extension
+
+Create a symbolic link between your development directory and the Gemini CLI
+extensions directory. This lets you test changes immediately without
+reinstalling.
+
+```bash
+gemini extensions link <path>
+```
+
+## Extension format
+
+Gemini CLI loads extensions from `<home>/.gemini/extensions`. Each extension
+must have a `gemini-extension.json` file in its root directory.
+
+### `gemini-extension.json`
+
+The manifest file defines the extension's behavior and configuration.
+
+```json
+{
+  "name": "my-extension",
+  "version": "1.0.0",
+  "description": "My awesome extension",
+  "mcpServers": {
+    "my-server": {
+      "command": "node my-server.js"
+    }
+  },
+  "contextFileName": "GEMINI.md",
+  "excludeTools": ["run_shell_command"]
+}
+```
+
+- `name`: A unique identifier for the extension. Use lowercase letters, numbers,
+  and dashes. This name must match the extension's directory name.
+- `version`: The current version of the extension.
+- `description`: A short summary shown in the extension gallery.
+- <a id="mcp-servers"></a>`mcpServers`: A map of Model Context Protocol (MCP)
+  servers. Extension servers follow the same format as standard
+  [CLI configuration](../get-started/configuration.md).
+- `contextFileName`: The name of the context file (defaults to `GEMINI.md`). Can
+  also be an array of strings to load multiple context files.
+- `excludeTools`: An array of tools to block from the model. You can restrict
+  specific arguments, such as `run_shell_command(rm -rf)`.
+- `themes`: An optional list of themes provided by the extension. See
+  [Themes](../cli/themes.md) for more information.
+
+### Extension settings
+
+Extensions can define settings that users provide during installation, such as
+API keys or URLs. These values are stored in a `.env` file within the extension
+directory.
+
+To define settings, add a `settings` array to your manifest:
+
+```json
+{
+  "name": "my-api-extension",
+  "version": "1.0.0",
+  "settings": [
+    {
+      "name": "API Key",
+      "description": "Your API key for the service.",
+      "envVar": "MY_API_KEY",
+      "sensitive": true
+    }
+  ]
+}
+```
+
+- `name`: The setting's display name.
+- `description`: A clear explanation of the setting.
+- `envVar`: The environment variable name where the value is stored.
+- `sensitive`: If `true`, the value is stored in the system keychain and
+  obfuscated in the UI.
+
+To update an extension's settings:
+
+```bash
+gemini extensions config <name> [setting] [--scope <scope>]
+```
+
+### Custom commands
+
+Provide [custom commands](../cli/custom-commands.md) by placing TOML files in a
+`commands/` subdirectory. Gemini CLI uses the directory structure to determine
+the command name.
+
+For an extension named `gcp`:
+
+- `commands/deploy.toml` becomes `/deploy`
+- `commands/gcs/sync.toml` becomes `/gcs:sync` (namespaced with a colon)
+
+### Hooks
+
+Intercept and customize CLI behavior using [hooks](../hooks/index.md). Define
+hooks in a `hooks/hooks.json` file within your extension directory. Note that
+hooks are not defined in the `gemini-extension.json` manifest.
+
+### Agent skills
+
+Bundle [agent skills](../cli/skills.md) to provide specialized workflows. Place
+skill definitions in a `skills/` directory. For example,
+`skills/security-audit/SKILL.md` exposes a `security-audit` skill.
+
+### Sub-agents
+
+> **Note:** Sub-agents are a preview feature currently under active development.
+
+Provide [sub-agents](../core/subagents.md) that users can delegate tasks to. Add
+agent definition files (`.md`) to an `agents/` directory in your extension root.
+
+### Themes
+
+Extensions can provide custom themes to personalize the CLI UI. Themes are
+defined in the `themes` array in `gemini-extension.json`.
+
+**Example**
+
+```json
+{
+  "name": "my-green-extension",
+  "version": "1.0.0",
+  "themes": [
+    {
+      "name": "shades-of-green",
+      "type": "custom",
+      "background": {
+        "primary": "#1a362a"
+      },
+      "text": {
+        "primary": "#a6e3a1",
+        "secondary": "#6e8e7a",
+        "link": "#89e689"
+      },
+      "status": {
+        "success": "#76c076",
+        "warning": "#d9e689",
+        "error": "#b34e4e"
+      },
+      "border": {
+        "default": "#4a6c5a"
+      },
+      "ui": {
+        "comment": "#6e8e7a"
+      }
+    }
+  ]
+}
+```
+
+Custom themes provided by extensions can be selected using the `/theme` command
+or by setting the `ui.theme` property in your `settings.json` file. Note that
+when referring to a theme from an extension, the extension name is appended to
+the theme name in parentheses, e.g., `shades-of-green (my-green-extension)`.
+
+### Conflict resolution
+
+Extension commands have the lowest precedence. If an extension command name
+conflicts with a user or project command, the extension command is prefixed with
+the extension name (e.g., `/gcp.deploy`) using a dot separator.
+
+## Variables
+
+Gemini CLI supports variable substitution in `gemini-extension.json` and
+`hooks/hooks.json`.
+
+| Variable           | Description                                     |
+| :----------------- | :---------------------------------------------- |
+| `${extensionPath}` | The absolute path to the extension's directory. |
+| `${workspacePath}` | The absolute path to the current workspace.     |
+| `${/}`             | The platform-specific path separator.           |

package/dist/docs/extensions/releasing.md

@@ -0,0 +1,154 @@
+# Release extensions
+
+Release Gemini CLI extensions to your users through a Git repository or GitHub
+Releases.
+
+Git repository releases are the simplest approach and offer the most flexibility
+for managing development branches. GitHub Releases are more efficient for
+initial installations because they ship as single archives rather than requiring
+a full `git clone`. Use GitHub Releases if you need to include platform-specific
+binary files.
+
+## List your extension in the gallery
+
+The [Gemini CLI extension gallery](https://geminicli.com/extensions/browse/)
+automatically indexes public extensions to help users discover your work. You
+don't need to submit an issue or email us to list your extension.
+
+To have your extension automatically discovered and listed:
+
+1.  **Use a public repository:** Ensure your extension is hosted in a public
+    GitHub repository.
+2.  **Add the GitHub topic:** Add the `gemini-cli-extension` topic to your
+    repository's **About** section. Our crawler uses this topic to find new
+    extensions.
+3.  **Place the manifest at the root:** Ensure your `gemini-extension.json` file
+    is in the absolute root of the repository or the release archive.
+
+Our system crawls tagged repositories daily. Once you tag your repository, your
+extension will appear in the gallery if it passes validation.
+
+## Release through a Git repository
+
+Releasing through Git is the most flexible option. Create a public Git
+repository and provide the URL to your users. They can then install your
+extension using `gemini extensions install <your-repo-uri>`.
+
+Users can optionally depend on a specific branch, tag, or commit using the
+`--ref` argument. For example:
+
+```bash
+gemini extensions install <your-repo-uri> --ref=stable
+```
+
+Whenever you push commits to the referenced branch, the CLI prompts users to
+update their installation. The `HEAD` commit is always treated as the latest
+version.
+
+### Manage release channels
+
+You can use branches or tags to manage different release channels, such as
+`stable`, `preview`, or `dev`.
+
+We recommend using your default branch as the stable release channel. This
+ensures that the default installation command always provides the most reliable
+version of your extension. You can then use a `dev` branch for active
+development and merge it into the default branch when you are ready for a
+release.
+
+## Release through GitHub Releases
+
+Distributing extensions through
+[GitHub Releases](https://docs.github.com/en/repositories/releasing-projects-on-github/about-releases)
+provides a faster installation experience by avoiding a repository clone.
+
+Gemini CLI checks for updates by looking for the **Latest** release on GitHub.
+Users can also install specific versions using the `--ref` argument with a
+release tag. Use the `--pre-release` flag to install the latest version even if
+it isn't marked as **Latest**.
+
+### Custom pre-built archives
+
+You can attach custom archives directly to your GitHub Release as assets. This
+is useful if your extension requires a build step or includes platform-specific
+binaries.
+
+Custom archives must be fully self-contained and follow the required
+[archive structure](#archive-structure). If your extension is
+platform-independent, provide a single generic asset.
+
+#### Platform-specific archives
+
+To let Gemini CLI find the correct asset for a user's platform, use the
+following naming convention:
+
+1.  **Platform and architecture-specific:**
+    `{platform}.{arch}.{name}.{extension}`
+2.  **Platform-specific:** `{platform}.{name}.{extension}`
+3.  **Generic:** A single asset will be used as a fallback if no specific match
+    is found.
+
+Use these values for the placeholders:
+
+- `{name}`: Your extension name.
+- `{platform}`: Use `darwin` (macOS), `linux`, or `win32` (Windows).
+- `{arch}`: Use `x64` or `arm64`.
+- `{extension}`: Use `.tar.gz` or `.zip`.
+
+**Examples:**
+
+- `darwin.arm64.my-tool.tar.gz` (specific to Apple Silicon Macs)
+- `darwin.my-tool.tar.gz` (fallback for all Macs, e.g. Intel)
+- `linux.x64.my-tool.tar.gz`
+- `win32.my-tool.zip`
+
+#### Archive structure
+
+Archives must be fully contained extensions. The `gemini-extension.json` file
+must be at the root of the archive. The rest of the layout should match a
+standard extension structure.
+
+#### Example GitHub Actions workflow
+
+Use this example workflow to build and release your extension for multiple
+platforms:
+
+```yaml
+name: Release Extension
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: '20'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build extension
+        run: npm run build
+
+      - name: Create release assets
+        run: |
+          npm run package -- --platform=darwin --arch=arm64
+          npm run package -- --platform=linux --arch=x64
+          npm run package -- --platform=win32 --arch=x64
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v1
+        with:
+          files: |
+            release/darwin.arm64.my-tool.tar.gz
+            release/linux.arm64.my-tool.tar.gz
+            release/win32.arm64.my-tool.zip
+```