> ## Documentation Index
> Fetch the complete documentation index at: https://herwaka.shesharp.org.nz/llms.txt
> Use this file to discover all available pages before exploring further.

# Set up your tools

> Install Gemini CLI and Google Workspace CLI — connect AI to your Gmail, Calendar, and Google Docs.

Before we start turning emails into actions, let's get your AI tools connected to Gmail, Calendar, and Google Docs.

<Warning>
  **You will need:** a laptop with internet access and a Google account (Gmail + Calendar + Docs). No coding experience is required — we will guide you through every step.
</Warning>

<Steps>
  <Step title="Install Node.js">
    <Info>
      **Already have Node.js?** If you installed it for a previous tutorial, skip this step. Run `node --version` in your terminal to check — you should see a version number like `v22.x.x`.
    </Info>

    Node.js is a free tool that lets you run Gemini CLI on your computer.

    <Tabs>
      <Tab title="Windows">
        1. Go to [nodejs.org](https://nodejs.org)
        2. Click the big green **LTS** button to download the installer
        3. Open the downloaded `.msi` file
        4. Click **Next** through all the screens — the default settings are fine
        5. Click **Install**, then **Finish**
      </Tab>

      <Tab title="macOS">
        1. Go to [nodejs.org](https://nodejs.org)
        2. Click the big green **LTS** button to download the installer
        3. Open the downloaded `.pkg` file
        4. Click **Continue** through all the screens — the default settings are fine
        5. Click **Install**, then **Close**
      </Tab>
    </Tabs>

    <Accordion title="How do I know it worked?">
      Open your terminal and type:

      ```bash theme={null}
      node --version
      ```

      You should see a version number like `v22.x.x`. If you see an error, try closing and reopening your terminal, then run the command again.
    </Accordion>
  </Step>

  <Step title="Install Gemini CLI">
    <Info>
      **Already have Gemini CLI?** If you installed it for a previous tutorial, skip this step. Just run `gemini` in your terminal to check it still works.
    </Info>

    Gemini CLI is Google's free AI assistant. It runs in your terminal and helps you with tasks based on your descriptions.

    Open your terminal and type:

    ```bash theme={null}
    npm install -g @google/gemini-cli
    ```

    Wait for the installation to finish. Then start it by typing:

    ```bash theme={null}
    gemini
    ```

    The first time you run it, Gemini CLI will ask you to sign in:

    * Choose **"Sign in with Google"**
    * A browser window will open — sign in with your Google account
    * Come back to the terminal when it says you're connected

    <Info>
      **Free tier:** 60 requests per minute, 1,000 requests per day — more than enough for this tutorial and everyday use.
    </Info>

    <Accordion title="'npm' is not recognised">
      This means Node.js isn't installed correctly. Go back and reinstall Node.js. After reinstalling, **close your terminal completely and open a new one** before trying again.
    </Accordion>

    <Accordion title="Permission denied error">
      **Windows:** Close PowerShell and reopen it by right-clicking and choosing **"Run as Administrator"**. Then try the install command again.

      **macOS:** Add `sudo` before the command:

      ```bash theme={null}
      sudo npm install -g @google/gemini-cli
      ```

      Enter your computer password when prompted (you won't see characters as you type — that's normal).
    </Accordion>

    Type `/quit` to exit Gemini CLI for now. We will start it again after installing the Google Workspace tools.
  </Step>

  <Step title="Install the Google Workspace CLI (gws)">
    `gws` is a command-line tool that controls all your Google apps — Gmail, Calendar, Drive, Docs, Sheets — from the terminal. It's what lets AI manage your Google Workspace without opening a browser.

    Open your terminal and type:

    ```bash title="Copy this command" theme={null}
    npm install -g @googleworkspace/cli
    ```

    Wait for the installation to finish. Then set up your Google Cloud project:

    ```bash title="Copy this command" theme={null}
    gws auth setup
    ```

    <Info>
      **What does `gws auth setup` do?** It creates a Google Cloud project for you, enables the APIs you need, and prepares everything for sign-in. It requires the `gcloud` CLI — if you don't have it, see the troubleshooting section below.
    </Info>

    Once setup is complete, sign in and choose which Google services to connect:

    ```bash title="Copy this command" theme={null}
    gws auth login -s gmail,calendar,drive,docs,sheets
    ```

    A browser window will open — sign in with your Google account and approve the permissions.

    <Warning>
      **"Google hasn't verified this app" warning:** This is normal. Click **Advanced** → **Go to \[app name] (unsafe)** to continue. This is safe for personal use — Google shows this for all apps that haven't gone through their official review process.
    </Warning>

    <Warning>
      **Scope checkboxes:** If you see a list of permission checkboxes, select all of them (or click **Select all**) before clicking **Continue**. These are the permissions `gws` needs to read and manage your Google apps.
    </Warning>

    Verify the installation by checking today's calendar:

    ```bash title="Copy this command" theme={null}
    gws calendar +agenda
    ```

    You should see your upcoming events listed in your terminal. If you do, `gws` is working.

    <Info>
      **Free to use:** `gws` is free and open-source. It connects to Google's APIs using your own Google account — there are no usage limits beyond Google's own API quotas.
    </Info>

    <Accordion title="'gws' is not recognised">
      The installation may not have added `gws` to your system PATH. Try closing your terminal completely and opening a new one, then run `gws --version`. If it still doesn't work, try reinstalling:

      ```bash theme={null}
      npm install -g @googleworkspace/cli
      ```
    </Accordion>

    <Accordion title="'gcloud' is not installed">
      `gws auth setup` uses the `gcloud` CLI to automate project creation. You have two options:

      1. **Install gcloud** from [cloud.google.com/sdk/docs/install](https://cloud.google.com/sdk/docs/install), then run `gws auth setup` again
      2. **Skip gcloud** — set up OAuth credentials manually in the [Google Cloud Console](https://console.cloud.google.com/). Create a project, enable the APIs you need, create an OAuth Desktop App client, download the JSON, and save it to `~/.config/gws/client_secret.json`. Then run `gws auth login`.
    </Accordion>

    <Accordion title="Permission denied error">
      **Windows:** Close PowerShell and reopen it by right-clicking and choosing **"Run as Administrator"**. Then try the install command again.

      **macOS:** Add `sudo` before the command:

      ```bash theme={null}
      sudo npm install -g @googleworkspace/cli
      ```

      Enter your computer password when prompted (you won't see characters as you type — that's normal).
    </Accordion>

    <Accordion title="API not enabled error">
      If you see an error like "Gmail API has not been used in project...", the API needs to be enabled:

      1. Look for the `enable_url` link in the error message
      2. Open that link in your browser
      3. Click **Enable**
      4. Wait 10 seconds, then retry your command

      You can also run `gws auth setup` again — it enables all required APIs automatically.
    </Accordion>

    <Accordion title="'Access blocked' or 403 during login">
      Your Google account is not listed as a test user for the OAuth app. Open the [OAuth consent screen](https://console.cloud.google.com/apis/credentials/consent) in your Google Cloud project → **Test users** → **Add users** → enter your Google account email. Then retry `gws auth login`.
    </Accordion>
  </Step>

  <Step title="Connect Gemini CLI to gws">
    Now let's give Gemini CLI the ability to use your Google Workspace tools. Open your terminal and run:

    ```bash title="Copy this command" theme={null}
    gemini extensions install https://github.com/googleworkspace/cli
    ```

    This connects Gemini CLI to `gws`, so when you give a natural language instruction, Gemini can read your Gmail, create calendar events, and write to Google Docs on your behalf.

    <Info>
      **What does this do?** It installs an extension that lets Gemini CLI call `gws` commands automatically. Instead of you typing `gws calendar +insert ...`, you can just say "Create a calendar event for Friday" and Gemini handles the rest.
    </Info>

    <Accordion title="The command fails or hangs">
      Make sure you have an internet connection and that Node.js is installed correctly. Try running `node --version` first. If that works but the extension install fails, try closing and reopening your terminal, then running the command again.
    </Accordion>
  </Step>

  <Step title="Install Wispr Flow (optional)">
    <Info>
      **This step is optional.** Wispr Flow lets you speak instead of type — handy if you prefer talking over typing. Skip this step if you'd rather type your prompts.
    </Info>

    <Tip>
      **Sign up using this invite link to get a free month of Pro:**
      [https://wisprflow.ai/r?CHAN115](https://wisprflow.ai/r?CHAN115)

      Both you and the tutorial author benefit — you get a free month of Pro, and they get a free month when you dictate 2,000 words!
    </Tip>

    1. **Sign up** at [wisprflow.ai/r?CHAN115](https://wisprflow.ai/r?CHAN115)
    2. **Download and install** the app for your operating system
    3. **Configure settings** — enable these options for the best experience:
       * Experimental > **Command Mode** — Enable advanced voice commands
       * **Press Enter Command** — Automatically press enter when you say "press enter"
       * **Bulk Import** — Import snippets and dictionary items

    <Accordion title="What is Wispr Flow?">
      Wispr Flow is a voice-to-text tool that lets you dictate instead of type. It works in any application, including your terminal. Instead of typing a long prompt to Gemini CLI, you can just say it out loud. This is especially useful if you find typing slow or tiring.
    </Accordion>
  </Step>

  <Step title="Test the connection">
    Start Gemini CLI and try these two prompts to make sure everything is connected:

    ```bash title="Copy this command" theme={null}
    gemini
    ```

    Then say (with Wispr Flow) or type:

    ```text title="Say this or copy this prompt" theme={null}
    Check my Gmail and tell me how many unread emails I have.
    ```

    You should see Gemini CLI access your Gmail and return information about your inbox. Now try this:

    ```text title="Say this or copy this prompt" theme={null}
    What meetings do I have today?
    ```

    You should see your calendar events listed. If both work, everything is connected and ready.

    <Tip>
      **Gemini asks for permission?** If Gemini CLI asks to approve a tool call, type `y` and press **Enter**. This is normal — it is asking your permission before accessing your Google apps.
    </Tip>

    <Accordion title="Gemini says it has no Gmail or Calendar tools">
      The extension may not have installed correctly. Try running the install command again:

      ```bash theme={null}
      gemini extensions install https://github.com/googleworkspace/cli
      ```

      Then exit (`/quit`) and restart Gemini CLI. You can check installed extensions with `/extensions list`.
    </Accordion>

    <Accordion title="I see a permission or authentication error">
      Your Google authorisation may have expired. Exit Gemini CLI and run `gws auth login -s gmail,calendar,drive,docs,sheets` again to re-authorise. Then restart Gemini CLI.
    </Accordion>
  </Step>
</Steps>

## Verify your setup

<AccordionGroup>
  <Accordion title="Node.js installed">
    Run `node --version` in your terminal. You should see a version number.
  </Accordion>

  <Accordion title="Gemini CLI installed and signed in">
    Run `gemini` in your terminal. It starts up and shows a prompt where you can type.
  </Accordion>

  <Accordion title="gws installed and signed in">
    Run `gws calendar +agenda` in your terminal. You should see your upcoming calendar events.
  </Accordion>

  <Accordion title="Gemini CLI extension installed">
    The extension installed without errors. You can verify with `/extensions list` inside Gemini CLI.
  </Accordion>

  <Accordion title="Gmail and Calendar access working">
    Gemini CLI can tell you about your unread emails and today's meetings when you ask.
  </Accordion>

  <Accordion title="Connection tested">
    Both test prompts returned real results from your Gmail and Calendar.
  </Accordion>
</AccordionGroup>

<Note>
  All set? Head to [Automate your workflow](/tutorial/email-to-action/automate) to start turning emails into actions.
</Note>