@google/gemini-cli-core 0.22.0 → 0.23.0-preview.0

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

@@ -0,0 +1,143 @@
+Note: This page will be replaced by [installation.md](installation.md).
+
+# Gemini CLI installation, execution, and deployment
+
+Install and run Gemini CLI. This document provides an overview of Gemini CLI's
+installation methods and deployment architecture.
+
+## How to install and/or run Gemini CLI
+
+There are several ways to run Gemini CLI. The recommended option depends on how
+you intend to use Gemini CLI.
+
+- As a standard installation. This is the most straightforward method of using
+  Gemini CLI.
+- In a sandbox. This method offers increased security and isolation.
+- From the source. This is recommended for contributors to the project.
+
+### 1. Standard installation (recommended for standard users)
+
+This is the recommended way for end-users to install Gemini CLI. It involves
+downloading the Gemini CLI package from the NPM registry.
+
+- **Global install:**
+
+  ```bash
+  npm install -g @google/gemini-cli
+  ```
+
+  Then, run the CLI from anywhere:
+
+  ```bash
+  gemini
+  ```
+
+- **NPX execution:**
+
+  ```bash
+  # Execute the latest version from NPM without a global install
+  npx @google/gemini-cli
+  ```
+
+### 2. Run in a sandbox (Docker/Podman)
+
+For security and isolation, Gemini CLI can be run inside a container. This is
+the default way that the CLI executes tools that might have side effects.
+
+- **Directly from the registry:** You can run the published sandbox image
+  directly. This is useful for environments where you only have Docker and want
+  to run the CLI.
+  ```bash
+  # Run the published sandbox image
+  docker run --rm -it us-docker.pkg.dev/gemini-code-dev/gemini-cli/sandbox:0.1.1
+  ```
+- **Using the `--sandbox` flag:** If you have Gemini CLI installed locally
+  (using the standard installation described above), you can instruct it to run
+  inside the sandbox container.
+  ```bash
+  gemini --sandbox -y -p "your prompt here"
+  ```
+
+### 3. Run from source (recommended for Gemini CLI contributors)
+
+Contributors to the project will want to run the CLI directly from the source
+code.
+
+- **Development mode:** This method provides hot-reloading and is useful for
+  active development.
+  ```bash
+  # From the root of the repository
+  npm run start
+  ```
+- **Production-like mode (Linked package):** This method simulates a global
+  installation by linking your local package. It's useful for testing a local
+  build in a production workflow.
+
+  ```bash
+  # Link the local cli package to your global node_modules
+  npm link packages/cli
+
+  # Now you can run your local version using the `gemini` command
+  gemini
+  ```
+
+---
+
+### 4. Running the latest Gemini CLI commit from GitHub
+
+You can run the most recently committed version of Gemini CLI directly from the
+GitHub repository. This is useful for testing features still in development.
+
+```bash
+# Execute the CLI directly from the main branch on GitHub
+npx https://github.com/google-gemini/gemini-cli
+```
+
+## Deployment architecture
+
+The execution methods described above are made possible by the following
+architectural components and processes:
+
+**NPM packages**
+
+Gemini CLI project is a monorepo that publishes two core packages to the NPM
+registry:
+
+- `@google/gemini-cli-core`: The backend, handling logic and tool execution.
+- `@google/gemini-cli`: The user-facing frontend.
+
+These packages are used when performing the standard installation and when
+running Gemini CLI from the source.
+
+**Build and packaging processes**
+
+There are two distinct build processes used, depending on the distribution
+channel:
+
+- **NPM publication:** For publishing to the NPM registry, the TypeScript source
+  code in `@google/gemini-cli-core` and `@google/gemini-cli` is transpiled into
+  standard JavaScript using the TypeScript Compiler (`tsc`). The resulting
+  `dist/` directory is what gets published in the NPM package. This is a
+  standard approach for TypeScript libraries.
+
+- **GitHub `npx` execution:** When running the latest version of Gemini CLI
+  directly from GitHub, a different process is triggered by the `prepare` script
+  in `package.json`. This script uses `esbuild` to bundle the entire application
+  and its dependencies into a single, self-contained JavaScript file. This
+  bundle is created on-the-fly on the user's machine and is not checked into the
+  repository.
+
+**Docker sandbox image**
+
+The Docker-based execution method is supported by the `gemini-cli-sandbox`
+container image. This image is published to a container registry and contains a
+pre-installed, global version of Gemini CLI.
+
+## Release process
+
+The release process is automated through GitHub Actions. The release workflow
+performs the following actions:
+
+1.  Build the NPM packages using `tsc`.
+2.  Publish the NPM packages to the artifact registry.
+3.  Create GitHub releases with bundled assets.

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

@@ -0,0 +1,219 @@
+# Gemini CLI examples
+
+Not sure where to get started with Gemini CLI? This document covers examples on
+how to use Gemini CLI for a variety of tasks.
+
+**Note:** Results are examples intended to showcase potential use cases. Your
+results may vary.
+
+## Rename your photographs based on content
+
+Scenario: You have a folder containing the following files:
+
+```bash
+photos/photo1.png
+photos/photo2.png
+photos/photo3.png
+```
+
+Give Gemini the following prompt:
+
+```cli
+Rename the photos in my "photos" directory based on their contents.
+```
+
+Result: Gemini will ask for permission to rename your files.
+
+Select **Allow once** and your files will be renamed:
+
+```bash
+photos/yellow_flowers.png
+photos/antique_dresser.png
+photos/green_android_robot.png
+```
+
+## Explain a repository by reading its code
+
+Scenario: You want to understand how a popular open-source utility works by
+inspecting its code, not just its README.
+
+Give Gemini CLI the following prompt:
+
+```cli
+Clone the 'chalk' repository from https://github.com/chalk/chalk, read its key source files, and explain how it works.
+```
+
+Result: Gemini will perform a sequence of actions to answer your request.
+
+1.  First, it will ask for permission to run `git clone` to download the
+    repository.
+2.  Next, it will find the important source files and ask for permission to read
+    them.
+3.  Finally, after analyzing the code, it will provide a summary.
+
+Gemini CLI will return an explanation based on the actual source code:
+
+```markdown
+The `chalk` library is a popular npm package for styling terminal output with
+colors. After analyzing the source code, here's how it works:
+
+- **Core functionality:** The main file sets up a chainable API. Each color or
+  modifier (like `bold` or `italic`) is a getter that appends the corresponding
+  ANSI escape code to an internal stack.
+
+- **Chainable API:** When you call `chalk.red.bold('Hello')`, you are accessing
+  getters. The `red` getter adds the red color code, and the `bold` getter adds
+  the bold code.
+
+- **Output generation:** When the chain is treated as a string (e.g., in
+  `console.log`), a final `toString()` method is called. This method joins all
+  the stored ANSI codes, wraps them around the input string ('Hello'), and adds
+  a reset code at the end. This produces the final, styled string that the
+  terminal can render.
+```
+
+## Combine two spreadsheets into one spreadsheet
+
+Scenario: You have two .csv files: `Revenue - 2023.csv` and
+`Revenue - 2024.csv`. Each file contains monthly revenue figures, like so:
+
+```csv
+January,0
+February,0
+March,0
+April,900
+May,1000
+June,1000
+July,1200
+August,1800
+September,2000
+October,2400
+November,3400
+December,2100
+```
+
+You want to combine these two .csv files into a single .csv file.
+
+Give Gemini CLI the following prompt:
+
+```cli
+Combine the two .csv files into a single .csv file, with each year a different column.
+```
+
+Result: Gemini CLI will read each file and then ask for permission to write a
+new file. Provide your permission and Gemini CLI will provide the following
+.csv:
+
+```csv
+Month,2023,2024
+January,0,1000
+February,0,1200
+March,0,2400
+April,900,500
+May,1000,800
+June,1000,900
+July,1200,1000
+August,1800,400
+September,2000,2000
+October,2400,3400
+November,3400,1800
+December,2100,9000
+```
+
+## Run unit tests
+
+Scenario: You've written a simple login page. You wish to write unit tests to
+ensure that your login page has code coverage.
+
+Give Gemini CLI the following prompt:
+
+```cli
+Write unit tests for Login.js.
+```
+
+Result: Gemini CLI will ask for permission to write a new file and create a test
+for your login page
+
+```javascript
+import React from 'react';
+import { render, fireEvent, waitFor } from '@testing-library/react';
+import Login from './Login';
+
+// Mock the API call for login
+jest.mock('./api', () => ({
+  login: jest.fn(),
+}));
+
+describe('Login component', () => {
+  it('renders the login form correctly', () => {
+    const { getByLabelText, getByText } = render(<Login />);
+
+    expect(getByLabelText('Username')).toBeInTheDocument();
+    expect(getByLabelText('Password')).toBeInTheDocument();
+    expect(getByText('Login')).toBeInTheDocument();
+  });
+
+  it('shows an error message with invalid credentials', async () => {
+    const { getByLabelText, getByText, findByText } = render(<Login />);
+    const usernameInput = getByLabelText('Username');
+    const passwordInput = getByLabelText('Password');
+    const loginButton = getByText('Login');
+
+    // Mock the API to return an error
+    require('./api').login.mockRejectedValue(new Error('Invalid credentials'));
+
+    fireEvent.change(usernameInput, { target: { value: 'testuser' } });
+    fireEvent.change(passwordInput, { target: { value: 'wrongpassword' } });
+    fireEvent.click(loginButton);
+
+    const errorMessage = await findByText('Invalid credentials');
+    expect(errorMessage).toBeInTheDocument();
+  });
+
+  it('logs in successfully with valid credentials', async () => {
+    const onLoginSuccess = jest.fn();
+    const { getByLabelText, getByText } = render(
+      <Login onLoginSuccess={onLoginSuccess} />,
+    );
+    const usernameInput = getByLabelText('Username');
+    const passwordInput = getByLabelText('Password');
+    const loginButton = getByText('Login');
+
+    // Mock the API to return a success message
+    require('./api').login.mockResolvedValue({ success: true });
+
+    fireEvent.change(usernameInput, { target: { value: 'testuser' } });
+    fireEvent.change(passwordInput, { target: { value: 'correctpassword' } });
+    fireEvent.click(loginButton);
+
+    await waitFor(() => {
+      expect(onLoginSuccess).toHaveBeenCalled();
+    });
+  });
+
+  it('disables the submit button while submitting', async () => {
+    const { getByLabelText, getByText } = render(<Login />);
+    const usernameInput = getByLabelText('Username');
+    const passwordInput = getByLabelText('Password');
+    const loginButton = getByText('Login');
+
+    // Mock the API to have a delay
+    require('./api').login.mockImplementation(
+      () =>
+        new Promise((resolve) =>
+          setTimeout(() => resolve({ success: true }), 1000),
+        ),
+    );
+
+    fireEvent.change(usernameInput, { target: { value: 'testuser' } });
+    fireEvent.change(passwordInput, { target: { value: 'correctpassword' } });
+    fireEvent.click(loginButton);
+
+    expect(loginButton).toBeDisabled();
+
+    await waitFor(() => {
+      expect(loginButton).not.toBeDisabled();
+    });
+  });
+});
+```

package/dist/docs/get-started/gemini-3.md

@@ -0,0 +1,116 @@
+# Gemini 3 Pro and Gemini 3 Flash on Gemini CLI
+
+Gemini 3 Pro and Gemini 3 Flash are now available on Gemini CLI! Currently, most
+paid customers of Gemini CLI will have access to both Gemini 3 Pro and Gemini 3
+Flash, including the following subscribers:
+
+- Google AI Pro and Google AI Ultra (excluding business customers).
+- Gemini Code Assist Standard and Enterprise (requires
+  [administrative enablement](#administrator-instructions)).
+- Paid Gemini API and Vertex API key holders.
+
+For free tier users:
+
+- If you signed up for the waitlist, please check your email for details. We’ve
+  onboarded everyone who signed up to the previously available waitlist.
+- If you were not on our waitlist, we’re rolling out additional access gradually
+  to ensure the experience remains fast and reliable. Stay tuned for more
+  details.
+
+## How to get started with Gemini 3 on Gemini CLI
+
+Get started by upgrading Gemini CLI to the latest version (0.21.1):
+
+```bash
+npm install -g @google/gemini-cli@latest
+```
+
+After you’ve confirmed your version is 0.21.1 or later:
+
+1. Use the `/settings` command in Gemini CLI.
+2. Toggle **Preview Features** to `true`.
+3. Run `/model` and select **Auto (Gemini 3)**.
+
+For more information, see [Gemini CLI model selection](../cli/model.md).
+
+### Usage limits and fallback
+
+Gemini CLI will tell you when you reach your Gemini 3 Pro daily usage limit.
+When you encounter that limit, you’ll be given the option to switch to Gemini
+2.5 Pro, upgrade for higher limits, or stop. You’ll also be told when your usage
+limit resets and Gemini 3 Pro can be used again.
+
+Similarly, when you reach your daily usage limit for Gemini 2.5 Pro, you’ll see
+a message prompting fallback to Gemini 2.5 Flash.
+
+### Capacity errors
+
+There may be times when the Gemini 3 Pro model is overloaded. When that happens,
+Gemini CLI will ask you to decide whether you want to keep trying Gemini 3 Pro
+or fallback to Gemini 2.5 Pro.
+
+> **Note:** The **Keep trying** option uses exponential backoff, in which Gemini
+> CLI waits longer between each retry, when the system is busy. If the retry
+> doesn't happen immediately, please wait a few minutes for the request to
+> process.
+
+### Model selection and routing types
+
+When using Gemini CLI, you may want to control how your requests are routed
+between models. By default, Gemini CLI uses **Auto** routing.
+
+When using Gemini 3 Pro, you may want to use Auto routing or Pro routing to
+manage your usage limits:
+
+- **Auto routing:** Auto routing first determines whether a prompt involves a
+  complex or simple operation. For simple prompts, it will automatically use
+  Gemini 2.5 Flash. For complex prompts, if Gemini 3 Pro is enabled, it will use
+  Gemini 3 Pro; otherwise, it will use Gemini 2.5 Pro.
+- **Pro routing:** If you want to ensure your task is processed by the most
+  capable model, use `/model` and select **Pro**. Gemini CLI will prioritize the
+  most capable model available, including Gemini 3 Pro if it has been enabled.
+
+To learn more about selecting a model and routing, refer to
+[Gemini CLI Model Selection](../cli/model.md).
+
+## How to enable Gemini 3 with Gemini CLI on Gemini Code Assist
+
+If you're using Gemini Code Assist Standard or Gemini Code Assist Enterprise,
+enabling Gemini 3 Pro on Gemini CLI requires configuring your release channels.
+Using Gemini 3 Pro will require two steps: administrative enablement and user
+enablement.
+
+To learn more about these settings, refer to
+[Configure Gemini Code Assist release channels](https://developers.google.com/gemini-code-assist/docs/configure-release-channels).
+
+### Administrator instructions
+
+An administrator with **Google Cloud Settings Admin** permissions must follow
+these directions:
+
+- Navigate to the Google Cloud Project you're using with Gemini CLI for Code
+  Assist.
+- Go to **Admin for Gemini** > **Settings**.
+- Under **Release channels for Gemini Code Assist in local IDEs** select
+  **Preview**.
+- Click **Save changes**.
+
+### User instructions
+
+Wait for two to three minutes after your administrator has enabled **Preview**,
+then:
+
+- Open Gemini CLI.
+- Use the `/settings` command.
+- Set **Preview Features** to `true`.
+
+Restart Gemini CLI and you should have access to Gemini 3.
+
+## Need help?
+
+If you need help, we recommend searching for an existing
+[GitHub issue](https://github.com/google-gemini/gemini-cli/issues). If you
+cannot find a GitHub issue that matches your concern, you can
+[create a new issue](https://github.com/google-gemini/gemini-cli/issues/new/choose).
+For comments and feedback, consider opening a
+[GitHub discussion](https://github.com/google-gemini/gemini-cli/discussions).

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

@@ -0,0 +1,71 @@
+# Get started with Gemini CLI
+
+Welcome to Gemini CLI! This guide will help you install, configure, and start
+using the Gemini CLI to enhance your workflow right from your terminal.
+
+## Quickstart: Install, authenticate, configure, and use Gemini CLI
+
+Gemini CLI brings the power of advanced language models directly to your command
+line interface. As an AI-powered assistant, Gemini CLI can help you with a
+variety of tasks, from understanding and generating code to reviewing and
+editing documents.
+
+## Install
+
+The standard method to install and run Gemini CLI uses `npm`:
+
+```bash
+npm install -g @google/gemini-cli
+```
+
+Once Gemini CLI is installed, run Gemini CLI from your command line:
+
+```bash
+gemini
+```
+
+For more installation options, see [Gemini CLI Installation](./installation.md).
+
+## Authenticate
+
+To begin using Gemini CLI, you must authenticate with a Google service. In most
+cases, you can log in with your existing Google account:
+
+1. Run Gemini CLI after installation:
+
+   ```bash
+   gemini
+   ```
+
+2. When asked "How would you like to authenticate for this project?" select **1.
+   Login with Google**.
+
+3. Select your Google account.
+
+4. Click on **Sign in**.
+
+Certain account types may require you to configure a Google Cloud project. For
+more information, including other authentication methods, see
+[Gemini CLI Authentication Setup](./authentication.md).
+
+## Configure
+
+Gemini CLI offers several ways to configure its behavior, including environment
+variables, command-line arguments, and settings files.
+
+To explore your configuration options, see
+[Gemini CLI Configuration](./configuration.md).
+
+## Use
+
+Once installed and authenticated, you can start using Gemini CLI by issuing
+commands and prompts in your terminal. Ask it to generate code, explain files,
+and more.
+
+To explore the power of Gemini CLI, see [Gemini CLI examples](./examples.md).
+
+## What's next?
+
+- Find out more about [Gemini CLI's tools](../tools/index.md).
+- Review [Gemini CLI's commands](../cli/commands.md).
+- Learn how to [get started with Gemini 3](./gemini-3.md).

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

@@ -0,0 +1,141 @@
+# Gemini CLI installation, execution, and deployment
+
+Install and run Gemini CLI. This document provides an overview of Gemini CLI's
+installation methods and deployment architecture.
+
+## How to install and/or run Gemini CLI
+
+There are several ways to run Gemini CLI. The recommended option depends on how
+you intend to use Gemini CLI.
+
+- As a standard installation. This is the most straightforward method of using
+  Gemini CLI.
+- In a sandbox. This method offers increased security and isolation.
+- From the source. This is recommended for contributors to the project.
+
+### 1. Standard installation (recommended for standard users)
+
+This is the recommended way for end-users to install Gemini CLI. It involves
+downloading the Gemini CLI package from the NPM registry.
+
+- **Global install:**
+
+  ```bash
+  npm install -g @google/gemini-cli
+  ```
+
+  Then, run the CLI from anywhere:
+
+  ```bash
+  gemini
+  ```
+
+- **NPX execution:**
+
+  ```bash
+  # Execute the latest version from NPM without a global install
+  npx @google/gemini-cli
+  ```
+
+### 2. Run in a sandbox (Docker/Podman)
+
+For security and isolation, Gemini CLI can be run inside a container. This is
+the default way that the CLI executes tools that might have side effects.
+
+- **Directly from the registry:** You can run the published sandbox image
+  directly. This is useful for environments where you only have Docker and want
+  to run the CLI.
+  ```bash
+  # Run the published sandbox image
+  docker run --rm -it us-docker.pkg.dev/gemini-code-dev/gemini-cli/sandbox:0.1.1
+  ```
+- **Using the `--sandbox` flag:** If you have Gemini CLI installed locally
+  (using the standard installation described above), you can instruct it to run
+  inside the sandbox container.
+  ```bash
+  gemini --sandbox -y -p "your prompt here"
+  ```
+
+### 3. Run from source (recommended for Gemini CLI contributors)
+
+Contributors to the project will want to run the CLI directly from the source
+code.
+
+- **Development mode:** This method provides hot-reloading and is useful for
+  active development.
+  ```bash
+  # From the root of the repository
+  npm run start
+  ```
+- **Production-like mode (linked package):** This method simulates a global
+  installation by linking your local package. It's useful for testing a local
+  build in a production workflow.
+
+  ```bash
+  # Link the local cli package to your global node_modules
+  npm link packages/cli
+
+  # Now you can run your local version using the `gemini` command
+  gemini
+  ```
+
+---
+
+### 4. Running the latest Gemini CLI commit from GitHub
+
+You can run the most recently committed version of Gemini CLI directly from the
+GitHub repository. This is useful for testing features still in development.
+
+```bash
+# Execute the CLI directly from the main branch on GitHub
+npx https://github.com/google-gemini/gemini-cli
+```
+
+## Deployment architecture
+
+The execution methods described above are made possible by the following
+architectural components and processes:
+
+**NPM packages**
+
+Gemini CLI project is a monorepo that publishes two core packages to the NPM
+registry:
+
+- `@google/gemini-cli-core`: The backend, handling logic and tool execution.
+- `@google/gemini-cli`: The user-facing frontend.
+
+These packages are used when performing the standard installation and when
+running Gemini CLI from the source.
+
+**Build and packaging processes**
+
+There are two distinct build processes used, depending on the distribution
+channel:
+
+- **NPM publication:** For publishing to the NPM registry, the TypeScript source
+  code in `@google/gemini-cli-core` and `@google/gemini-cli` is transpiled into
+  standard JavaScript using the TypeScript Compiler (`tsc`). The resulting
+  `dist/` directory is what gets published in the NPM package. This is a
+  standard approach for TypeScript libraries.
+
+- **GitHub `npx` execution:** When running the latest version of Gemini CLI
+  directly from GitHub, a different process is triggered by the `prepare` script
+  in `package.json`. This script uses `esbuild` to bundle the entire application
+  and its dependencies into a single, self-contained JavaScript file. This
+  bundle is created on-the-fly on the user's machine and is not checked into the
+  repository.
+
+**Docker sandbox image**
+
+The Docker-based execution method is supported by the `gemini-cli-sandbox`
+container image. This image is published to a container registry and contains a
+pre-installed, global version of Gemini CLI.
+
+## Release process
+
+The release process is automated through GitHub Actions. The release workflow
+performs the following actions:
+
+1.  Build the NPM packages using `tsc`.
+2.  Publish the NPM packages to the artifact registry.
+3.  Create GitHub releases with bundled assets.