diff --git a/README.md b/README.md index ddb55f99..24ff6cc5 100644 --- a/README.md +++ b/README.md @@ -28,6 +28,8 @@ If you need to use a specific model or require a higher request capacity, you ca export GEMINI_API_KEY="YOUR_API_KEY" ``` +For other authentication methods, see the [authentication](./docs/cli/authentication.md) guide. + ## Examples Once the CLI is running, you can start interacting with Gemini from your shell. Try a simple query: @@ -44,81 +46,6 @@ Or ask it to perform a task using its tools: Take a look at some [popular tasks](#popular-tasks) for more inspiration. -## Authentication Setup - -The Gemini CLI requires you to authenticate with Google's AI services. On initial startup you'll need to configure **one** of the following authentication methods: - -1. **Login with Google (Gemini Code Assist):** - - - Use this option to log in with the standard, free account you use for services like Gmail, Google Photos, and Google Drive for personal use (e.g. your-name@gmail.com). - - During initial startup, Gemini CLI will direct you to a webpage for authentication. Once authenticated, your credentials will be cached locally so the web login can be skipped on subsequent runs. - - Note that the web login must be done in a browser that can communicate with the machine Gemini CLI is being run from. (Specifically, the browser will be redirected to a localhost url that Gemini CLI will be listening on). - -2. **Gemini API key:** - - - Obtain your API key from Google AI Studio: [https://aistudio.google.com/app/apikey](https://aistudio.google.com/app/apikey) - - Set the `GEMINI_API_KEY` environment variable. In the following methods, replace `YOUR_GEMINI_API_KEY` with the API key you obtained from Google AI Studio: - - You can temporarily set the environment variable in your current shell session using the following command: - ```bash - export GEMINI_API_KEY="YOUR_GEMINI_API_KEY" - ``` - - For repeated use, you can add the environment variable to your `.env` file (located in the project directory or user home directory) or your shell's configuration file (like `~/.bashrc`, `~/.zshrc`, or `~/.profile`). For example, the following command adds the environment variable to a `~/.bashrc` file: - ```bash - echo 'export GEMINI_API_KEY="YOUR_GEMINI_API_KEY"' >> ~/.bashrc - source ~/.bashrc - ``` - -3. **Login with Google Work** - - - Use this option to log in with the **Google Workspace Accounts**. This is a paid service for businesses and organizations that provides a suite of productivity tools, including a custom email domain (e.g. your-name@your-company.com), enhanced security features, and administrative controls. These accounts are often managed by an employer or school. - - Google Workspace Account must configure a Google Cloud Project Id to use. You can temporarily set the environment variable in your current shell session using the following command: - ```bash - export GOOGLE_CLOUD_PROJECT_ID="YOUR_PROJECT_ID" - ``` - - For repeated use, you can add the environment variable to your `.env` file (located in the project directory or user home directory) or your shell's configuration file (like `~/.bashrc`, `~/.zshrc`, or `~/.profile`). For example, the following command adds the environment variable to a `~/.bashrc` file: - ```bash - echo 'export GOOGLE_CLOUD_PROJECT_ID="YOUR_PROJECT_ID"' >> ~/.bashrc - source ~/.bashrc - ``` - - During startup, Gemini CLI will direct you to a webpage for authentication. Once authenticated, your credentials will be cached locally so the web login can be skipped on subsequent runs. - - Note that the web login must be done in a browser that can communicate with the machine Gemini CLI is being run from. (Specifically, the browser will be redirected to a localhost url that Gemini CLI will be listening on). - -4. **Vertex AI:** - - If not using express mode: - - Ensure you have a Google Cloud project and have enabled the Vertex AI API. - - Set up Application Default Credentials (ADC), using the following command: - ```bash - gcloud auth application-default login - ``` - For more information, see [Set up Application Default Credentials for Google Cloud](https://cloud.google.com/docs/authentication/provide-credentials-adc). - - Set the `GOOGLE_CLOUD_PROJECT`, `GOOGLE_CLOUD_LOCATION`, and `GOOGLE_GENAI_USE_VERTEXAI` environment variables. In the following methods, replace `YOUR_PROJECT_ID` and `YOUR_PROJECT_LOCATION` with the relevant values for your project: - - You can temporarily set these environment variables in your current shell session using the following commands: - ```bash - export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID" - export GOOGLE_CLOUD_LOCATION="YOUR_PROJECT_LOCATION" # e.g., us-central1 - export GOOGLE_GENAI_USE_VERTEXAI=true - ``` - - For repeated use, you can add the environment variables to your `.env` file (located in the project directory or user home directory) or your shell's configuration file (like `~/.bashrc`, `~/.zshrc`, or `~/.profile`). For example, the following commands adds the environment variables to a `~/.bashrc` file: - ```bash - echo 'export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"' >> ~/.bashrc - echo 'export GOOGLE_CLOUD_LOCATION="YOUR_PROJECT_LOCATION"' >> ~/.bashrc - echo 'export GOOGLE_GENAI_USE_VERTEXAI=true' >> ~/.bashrc - source ~/.bashrc - ``` - - If using express mode: - - Set the `GOOGLE_API_KEY` environment variables. In the following methods, replace `YOUR_GOOGLE_API_KEY` with your Vertex AI API key provided by express mode: - - You can temporarily set these environment variables in your current shell session using the following commands: - ```bash - export GOOGLE_API_KEY="YOUR_GOOGLE_API_KEY" - export GOOGLE_GENAI_USE_VERTEXAI=true - ``` - - For repeated use, you can add the environment variables to your `.env` file (located in the project directory or user home directory) or your shell's configuration file (like `~/.bashrc`, `~/.zshrc`, or `~/.profile`). For example, the following commands adds the environment variables to a `~/.bashrc` file: - ```bash - echo 'export GOOGLE_API_KEY="YOUR_GOOGLE_API_KEY"' >> ~/.bashrc - echo 'export GOOGLE_GENAI_USE_VERTEXAI=true' >> ~/.bashrc - source ~/.bashrc - ``` - ## Popular tasks ### Explore a new codebase diff --git a/docs/cli/authentication.md b/docs/cli/authentication.md new file mode 100644 index 00000000..f1a8ba58 --- /dev/null +++ b/docs/cli/authentication.md @@ -0,0 +1,74 @@ +## Authentication Setup + +The Gemini CLI requires you to authenticate with Google's AI services. On initial startup you'll need to configure **one** of the following authentication methods: + +1. **Login with Google (Gemini Code Assist):** + + - Use this option to log in with the standard, free account you use for services like Gmail, Google Photos, and Google Drive for personal use (e.g. your-name@gmail.com). + - During initial startup, Gemini CLI will direct you to a webpage for authentication. Once authenticated, your credentials will be cached locally so the web login can be skipped on subsequent runs. + - Note that the web login must be done in a browser that can communicate with the machine Gemini CLI is being run from. (Specifically, the browser will be redirected to a localhost url that Gemini CLI will be listening on). + +2. **Gemini API key:** + + - Obtain your API key from Google AI Studio: [https://aistudio.google.com/app/apikey](https://aistudio.google.com/app/apikey) + - Set the `GEMINI_API_KEY` environment variable. In the following methods, replace `YOUR_GEMINI_API_KEY` with the API key you obtained from Google AI Studio: + - You can temporarily set the environment variable in your current shell session using the following command: + ```bash + export GEMINI_API_KEY="YOUR_GEMINI_API_KEY" + ``` + - For repeated use, you can add the environment variable to your `.env` file (located in the project directory or user home directory) or your shell's configuration file (like `~/.bashrc`, `~/.zshrc`, or `~/.profile`). For example, the following command adds the environment variable to a `~/.bashrc` file: + ```bash + echo 'export GEMINI_API_KEY="YOUR_GEMINI_API_KEY"' >> ~/.bashrc + source ~/.bashrc + ``` + +3. **Login with Google Work** + + - Use this option to log in with the **Google Workspace Accounts**. This is a paid service for businesses and organizations that provides a suite of productivity tools, including a custom email domain (e.g. your-name@your-company.com), enhanced security features, and administrative controls. These accounts are often managed by an employer or school. + - Google Workspace Account must configure a Google Cloud Project Id to use. You can temporarily set the environment variable in your current shell session using the following command: + ```bash + export GOOGLE_CLOUD_PROJECT_ID="YOUR_PROJECT_ID" + ``` + - For repeated use, you can add the environment variable to your `.env` file (located in the project directory or user home directory) or your shell's configuration file (like `~/.bashrc`, `~/.zshrc`, or `~/.profile`). For example, the following command adds the environment variable to a `~/.bashrc` file: + ```bash + echo 'export GOOGLE_CLOUD_PROJECT_ID="YOUR_PROJECT_ID"' >> ~/.bashrc + source ~/.bashrc + ``` + - During startup, Gemini CLI will direct you to a webpage for authentication. Once authenticated, your credentials will be cached locally so the web login can be skipped on subsequent runs. + - Note that the web login must be done in a browser that can communicate with the machine Gemini CLI is being run from. (Specifically, the browser will be redirected to a localhost url that Gemini CLI will be listening on). + +4. **Vertex AI:** + - If not using express mode: + - Ensure you have a Google Cloud project and have enabled the Vertex AI API. + - Set up Application Default Credentials (ADC), using the following command: + ```bash + gcloud auth application-default login + ``` + For more information, see [Set up Application Default Credentials for Google Cloud](https://cloud.google.com/docs/authentication/provide-credentials-adc). + - Set the `GOOGLE_CLOUD_PROJECT`, `GOOGLE_CLOUD_LOCATION`, and `GOOGLE_GENAI_USE_VERTEXAI` environment variables. In the following methods, replace `YOUR_PROJECT_ID` and `YOUR_PROJECT_LOCATION` with the relevant values for your project: + - You can temporarily set these environment variables in your current shell session using the following commands: + ```bash + export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID" + export GOOGLE_CLOUD_LOCATION="YOUR_PROJECT_LOCATION" # e.g., us-central1 + export GOOGLE_GENAI_USE_VERTEXAI=true + ``` + - For repeated use, you can add the environment variables to your `.env` file (located in the project directory or user home directory) or your shell's configuration file (like `~/.bashrc`, `~/.zshrc`, or `~/.profile`). For example, the following commands adds the environment variables to a `~/.bashrc` file: + ```bash + echo 'export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"' >> ~/.bashrc + echo 'export GOOGLE_CLOUD_LOCATION="YOUR_PROJECT_LOCATION"' >> ~/.bashrc + echo 'export GOOGLE_GENAI_USE_VERTEXAI=true' >> ~/.bashrc + source ~/.bashrc + ``` + - If using express mode: + - Set the `GOOGLE_API_KEY` environment variables. In the following methods, replace `YOUR_GOOGLE_API_KEY` with your Vertex AI API key provided by express mode: + - You can temporarily set these environment variables in your current shell session using the following commands: + ```bash + export GOOGLE_API_KEY="YOUR_GOOGLE_API_KEY" + export GOOGLE_GENAI_USE_VERTEXAI=true + ``` + - For repeated use, you can add the environment variables to your `.env` file (located in the project directory or user home directory) or your shell's configuration file (like `~/.bashrc`, `~/.zshrc`, or `~/.profile`). For example, the following commands adds the environment variables to a `~/.bashrc` file: + ```bash + echo 'export GOOGLE_API_KEY="YOUR_GOOGLE_API_KEY"' >> ~/.bashrc + echo 'export GOOGLE_GENAI_USE_VERTEXAI=true' >> ~/.bashrc + source ~/.bashrc + ``` diff --git a/docs/cli/index.md b/docs/cli/index.md index e0b41096..430548b9 100644 --- a/docs/cli/index.md +++ b/docs/cli/index.md @@ -4,6 +4,7 @@ Within Gemini CLI, `packages/cli` is the frontend for users to send and receive ## Navigating this section +- **[Authentication](./authentication.md):** A guide to setting up authentication with Google's AI services. - **[Commands](./commands.md):** A reference for Gemini CLI commands (e.g., `/help`, `/tools`, `/theme`). - **[Configuration](./configuration.md):** A guide to tailoring Gemini CLI behavior using configuration files. - **[Themes](./themes.md)**: A guide to customizing the CLI's appearance with different themes.