> ## 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

> Register for the free Auckland Transport API, install Gemini CLI, and optionally set up Wispr Flow — everything you need to start querying real-time commute data by voice or text.

Before we start checking commute data, let's get your tools ready. There are three things to set up: your Auckland Transport API key (to access the data), Gemini CLI (to ask questions about it), and optionally Wispr Flow (to speak instead of type).

<Warning>
  **You will need:** a laptop with internet access and a Google account (for Gemini CLI). 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 once everything else is set up.
  </Step>

  <Step title="Register for the Auckland Transport API">
    The Auckland Transport API gives you access to real-time data for every bus, train, and ferry in Auckland. It's free — you just need to register.

    1. Go to [dev-portal.at.govt.nz](https://dev-portal.at.govt.nz/)
    2. Click **Sign Up** (or **Register**) in the top-right corner
    3. Fill in your name, email, and create a password
    4. Check your email for a verification link and click it
    5. Sign in to the developer portal
    6. Once signed in, look for a **Profile** or **Subscriptions** page
    7. You may need to subscribe to a product — look for **"GTFS Realtime"** or **"General Transit Feed"** and subscribe (it's free)
    8. Find your **Primary Key** (also called **Subscription Key**) — it will be a long string of letters and numbers
    9. **Copy this key and save it somewhere safe** — you will need it in the next section

    <Info>
      **What is an API key?** Think of it as a library card. The Auckland Transport data is free and public, but they need to know who is using it — mainly to prevent misuse. Your key identifies you as a registered user. It doesn't cost anything and doesn't give access to your personal information.
    </Info>

    <Accordion title="I can't find my subscription key">
      After signing in, look for a section called **Profile**, **Subscriptions**, or **API Keys**. Some portals show the key on a "Products" page after you subscribe to a product. Try clicking on "GTFS Realtime" or "General Transit Feed" in the product list, then subscribe (free), and the key will appear.
    </Accordion>

    <Accordion title="Do I need to subscribe to a specific product?">
      Yes — you may need to subscribe to the **"General Transit Feed Specification (GTFS)"** product or a similarly named product. This is free. Once subscribed, your subscription key will appear on your profile page.
    </Accordion>

    <Warning>
      **Your API key is like a password.** Do not share it publicly, post it on social media, or include it in screenshots. Anyone with your key could use your quota.
    </Warning>
  </Step>

  <Step title="Get your API subscription key">
    Once you have subscribed to the GTFS product, your subscription key will be visible on your profile page. You need this key for every API request.

    1. Go to your **Profile** page on the AT developer portal
    2. Find your **Primary Key** (or **Subscription Key**)
    3. Click **Show** to reveal the full key
    4. Copy it and save it somewhere you can easily access — a text file, a note, or your password manager

    <Tip>
      **You will paste this key into prompts throughout the tutorial.** Every API URL includes `YOUR_API_KEY` as a placeholder — you will replace it with your actual key each time. Keep it handy.
    </Tip>
  </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 your setup">
    Let's make sure everything works before we move on. Start Gemini CLI:

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

    Now say (with Wispr Flow) or type this prompt. **Replace `YOUR_API_KEY`** with the subscription key you saved earlier.

    ```text title="Say this or copy this prompt" theme={null}
    Can you help me check the Auckland Transport API?
    Fetch this URL and tell me what you get back:
    https://api.at.govt.nz/realtime/legacy/servicealerts?subscription-key=YOUR_API_KEY

    If the response contains data, summarise the first 2-3 service alerts in plain English.
    If you get an error, tell me what went wrong.
    ```

    <Tip>
      **Replace `YOUR_API_KEY`** with your actual subscription key. If you are using Wispr Flow, speak the description part naturally, then paste the API URL with your key. Keep the key inside the URL — do not add spaces around the `=` sign.
    </Tip>

    You should see Gemini describe some current service alerts — for example, "There is a detour on route 123 due to road works near Queen Street." If you see this, your API key is working and you're ready to go.

    <Accordion title="Gemini says 'access denied' or '401 error'">
      Your API key is incorrect or hasn't been activated yet. Go back to [dev-portal.at.govt.nz](https://dev-portal.at.govt.nz/), check your profile, and copy the key again. Make sure you subscribed to the GTFS product. Some keys take a few minutes to activate after registration.
    </Accordion>

    <Accordion title="Gemini says 'rate limit exceeded'">
      This is unlikely on your first try, but if it happens, wait 60 seconds and try again. The free tier allows 600 calls per minute, which is very generous.
    </Accordion>

    <Accordion title="Gemini returns garbled data or strange characters">
      The API might be returning Protocol Buffer format instead of JSON. Try asking Gemini: "Fetch this URL with the header Accept: application/json" followed by the full URL. This tells the API to return human-readable JSON format.
    </Accordion>

    <Accordion title="Gemini says it can't access the URL">
      Make sure the entire URL is on a single line with no line breaks. Check that `subscription-key=YOUR_API_KEY` has your actual key with no spaces around the `=` sign. Also try asking Gemini to use `curl` to fetch the URL instead.
    </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="AT API key saved">
    You have a subscription key from dev-portal.at.govt.nz saved somewhere safe.
  </Accordion>

  <Accordion title="API key tested">
    Gemini CLI successfully fetched and described Auckland Transport service alerts.
  </Accordion>

  <Accordion title="Wispr Flow installed (optional)">
    You can speak into your terminal and see your words appear as text.
  </Accordion>
</AccordionGroup>

<Note>
  All set? Head to [Check your commute](/tutorial/auckland-commute/check-commute) to start getting real-time commute intelligence.
</Note>