> ## Documentation Index
> Fetch the complete documentation index at: https://docs.braingrid.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Installing the GitHub CLI

> Step-by-step guide to install the GitHub CLI on Mac and Windows

The GitHub CLI (`gh`) lets you interact with GitHub from your terminal. BrainGrid uses it to connect with your repositories, create branches, and manage pull requests.

## What is GitHub?

GitHub is a platform where developers store and collaborate on code. Think of it as a shared folder for your project's code, where you can track every change, work with teammates, and review each other's work. BrainGrid connects to GitHub to analyze your code and help manage your development workflow.

## Create a GitHub Account

If you are going to build a BrainGrid requirement locally, you will first need the GitHub CLI installed to download the code and upload any changes you make. To use the GitHub CLI, you need a GitHub account.

<Steps>
  <Step title="Go to GitHub">
    Open [github.com](https://github.com) in your browser and click **Sign up**.
  </Step>

  <Step title="Enter your details">
    Provide your email address, create a password, and choose a username. Follow the verification steps to confirm your account.
  </Step>

  <Step title="Choose a plan">
    Select the **Free** plan. It includes everything you need to use BrainGrid.
  </Step>
</Steps>

## Opening a Terminal

A terminal is a text-based application where you type commands. You'll need one to install the GitHub CLI.

<Tabs>
  <Tab title="Mac">
    1. Press **Command + Space** to open Spotlight Search
    2. Type **Terminal**
    3. Press **Enter** to open it

    A window with a text prompt will appear — this is your terminal.
  </Tab>

  <Tab title="Windows">
    1. Press the **Windows key** on your keyboard
    2. Type **PowerShell**
    3. Click **Windows PowerShell** from the results

    A blue window with a text prompt will appear — this is your terminal.

    <Warning>
      Use **PowerShell**, not Command Prompt. PowerShell comes pre-installed on Windows 10 and later.
    </Warning>
  </Tab>
</Tabs>

## Install the GitHub CLI

<Tabs>
  <Tab title="Mac">
    The easiest way to install on Mac is with Homebrew, a popular package manager.

    <Steps>
      <Step title="Install Homebrew (if you don't have it)">
        Paste this command into your terminal and press **Enter**:

        ```bash theme={null}
        /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
        ```

        Follow the on-screen instructions. You may need to enter your Mac password — the characters won't appear as you type, but they are being entered.

        <Note>
          If you already have Homebrew, you can skip this step. To check, type `brew --version` and press Enter. If you see a version number, it's already installed.
        </Note>
      </Step>

      <Step title="Install the GitHub CLI">
        Run this command:

        ```bash theme={null}
        brew install gh
        ```

        Wait for the installation to finish.
      </Step>
    </Steps>

    <Accordion title="Alternative: download the installer">
      If you prefer not to use Homebrew, you can download the `.pkg` installer directly from the [GitHub CLI releases page](https://github.com/cli/cli/releases/latest). Open the downloaded file and follow the installation wizard.
    </Accordion>
  </Tab>

  <Tab title="Windows">
    <Steps>
      <Step title="Install with winget">
        Windows 10 and later include a built-in package manager called `winget`. Paste this command into PowerShell and press **Enter**:

        ```powershell theme={null}
        winget install --id GitHub.cli
        ```

        Follow any prompts that appear.
      </Step>
    </Steps>

    <Accordion title="Alternative: download the installer">
      If `winget` is not available, download the `.msi` installer from the [GitHub CLI releases page](https://github.com/cli/cli/releases/latest). Open the downloaded file and follow the installation wizard.
    </Accordion>
  </Tab>
</Tabs>

## Verify the Installation

Close your terminal and open a new one (this ensures the new command is recognized). Then run:

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

You should see output like `gh version 2.x.x`. If you see an error like "command not found", try closing and reopening your terminal again.

## Log In to GitHub

Before using the GitHub CLI, you need to connect it to your GitHub account:

<Steps>
  <Step title="Start the login process">
    Run this command:

    ```bash theme={null}
    gh auth login
    ```
  </Step>

  <Step title="Answer the prompts">
    The CLI will ask you a series of questions. Choose the following:

    1. **Where do you use GitHub?** → Select `GitHub.com`
    2. **Preferred protocol for Git operations?** → Select `HTTPS`
    3. **Authenticate Git with your GitHub credentials?** → Select `Yes`
    4. **How would you like to authenticate?** → Select `Login with a web browser`
  </Step>

  <Step title="Complete browser authentication">
    The CLI will display a one-time code and open your browser. Paste the code into the browser page and authorize access.

    Once complete, you'll see a confirmation message in your terminal.
  </Step>
</Steps>

## Verify Authentication

Run this command to confirm you're logged in:

```bash theme={null}
gh auth status
```

You should see your GitHub username and a confirmation that you're logged in.

## Troubleshooting

<AccordionGroup>
  <Accordion title="'command not found' after installing">
    Close your terminal completely and open a new one. The terminal needs to restart to recognize newly installed commands.

    On Mac, if it still doesn't work after restarting the terminal, run the command that matches your Mac's chip. This is a temporary fix for the current session:

    ```bash theme={null}
    # Apple Silicon (M1/M2/M3/M4)
    eval "$(/opt/homebrew/bin/brew shellenv)"

    # Intel
    eval "$(/usr/local/bin/brew shellenv)"
    ```

    On Windows, try restarting your computer.
  </Accordion>

  <Accordion title="'winget' is not recognized (Windows)">
    Your version of Windows may not include `winget`. Download the GitHub CLI installer directly from the [releases page](https://github.com/cli/cli/releases/latest) and run the `.msi` file.
  </Accordion>

  <Accordion title="Homebrew installation asks for a password (Mac)">
    This is your Mac user password (the one you use to log in to your computer). The characters won't appear as you type — this is normal. Type your password and press Enter.
  </Accordion>

  <Accordion title="Browser doesn't open during login">
    If the browser doesn't open automatically, copy the URL shown in your terminal and paste it into your browser manually.
  </Accordion>

  <Accordion title="'Permission denied' errors (Mac)">
    This typically means your Homebrew directory has incorrect ownership. **Do not use `sudo` with `brew` commands** — it can break your Homebrew installation.

    Instead, fix the directory ownership by running this command, then try installing again:

    ```bash theme={null}
    sudo chown -R $(whoami) $(brew --prefix)
    ```

    You'll be prompted for your Mac password.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Install the GitHub App" icon="github" href="/github-installation">
    Connect your repositories to BrainGrid
  </Card>

  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Set up your first BrainGrid project
  </Card>
</CardGroup>