Installing GAM7 on macOS

This lesson is part of the "TAMING GAM7 - A practical guide to GAM7 and GAMADV-XTD3" course.

This lesson will guide you through setting up GAM7 on a macOS machine.

If you are trying to install GAM on another operating system, please refer to these articles:

GAM7 on Windows 11

GAM7 on Ubuntu Linux

GAMADV-XTD3 on Google Cloud Shell

GAM7 on ChromeOS

Welcome back, Mac admins! Today we are looking at GAM7. Not GAM, not GAMADV-XTD3, just the all-powerful, unified GAM7 on macOS.

If you’ve been managing Google Workspace with the old tools, you might know that the standard GAM and the advanced GAMADV-XTD3 have merged into one super-tool. If you’re ready to upgrade or install it from scratch on your Mac to become a command-line wizard, you are in the right place.

I’m going to walk you through this step-by-step. We’ll tackle the installation, the configuration (the "pro" way), and the authorisation. Open up your Terminal, grab a coffee, and let’s get your GAM on!

What You'll Need

Before we fire up the Terminal, let's make sure you have your supplies:

1. A Mac: Obviously! (Intel or Apple Silicon work fine).
2. Google Workspace Super Admin Rights: You need the keys to the kingdom to set this up.
3. Terminal Access: You can find this in your Applications > Utilities folder.
4. A Text Editor: Nano works, but if you prefer Visual Studio Code or TextEdit, have those ready.

Step-by-Step Installation Guide

Step 1: The Magic Install Command

We aren’t going to manually download files and drag them around. We’re going to use the official install script.

1. Open your Terminal.

2. Copy and paste the following command (this is the standard GAM install command):

<(curl -s -S -L https://gam-shortn.appspot.com/gam-install)

3. Hit Enter.

Heads Up: If this is a fresh Mac, you might get a pop-up saying "Python 3 command requires the command line developer tools."

• Click Install.
• Agree to the terms.
• Wait for it to finish (it might say "finding software" for a bit—don't worry, it usually takes about 5 minutes, not the 24 hours it sometimes predicts!).

Once the tools are installed, run that install command again. It will extract GAM7 to your home directory (usually ~/bin/gam7).

Step 2: Setting Up Your Configuration Directory (The "Pro" Way)

The installer will ask if you want to set up a project now. Say "No" (N) for a second. Why? Because we want to set up a clean, professional folder structure first, just like the pros do.

By default, GAM hides config files in a hidden .gam folder. We want them visible and manageable.

Create a Config Folder: In your terminal

mkdir -p ~/GAMConfig

Tell macOS where to look: We need to edit your shell profile (usually .zshrc on modern Macs). You can use nano.

Add this line to the bottom of the file

export GAMCFGDIR="~/GAMConfig"

Save and close the file.

Reload your profile so the Mac knows about the change

source ~/.zshrc

Step 3: Setting Up Your Working Directory

Next, let’s make a "Working" directory. This is where you’ll keep your CSVs for bulk uploads and where GAM will save reports. It keeps your actual program files clean.

Run this command to make the folder

mkdir -p ~/GAMWork

Now, initialize GAM with this new path

gam config drive_dir ~/GAMWork verify

GAM will now generate a gam.cfg file inside your new ~/GAMConfig folder. You are now officially configured!

Step 4: Create Your Google Cloud Project

Now it’s time to introduce GAM to Google.

Run: 

gam create project

Enter your Super Admin email address.

GAM will open a browser tab. Sign in.

Create the Project: Click the "Create Project" button when prompted.

Create the Client:

Go to "APIs & Services" > "Credentials".

Click Create Credentials > OAuth client ID.

Select Desktop App .

Name it something cool like "GAM7 Mac".

Click Create.

Step 5: The Client ID & Secret (Don't Lose These!)

You will see a pop-up with your Client ID and Client Secret.

• Copy the Client ID and paste it into your Terminal window where GAM is waiting.
• Copy the Client Secret and paste that into the Terminal next.

Important: Treat that Client Secret like a password. Don't share it!

Step 6: Authorization & Scopes

GAM will now ask for permission to manage your domain.

1. It will show a list of APIs (Calendar, Drive, Gmail, etc.).
2. Unless you have a specific reason not to, press c to continue with the default full access.
3. A browser window will open. Select your admin account.
4. The "Unverified App" Screen: You will see a scary warning saying "Google hasn't verified this app." This is normal—because you just created the app!
5. Click Advanced > Go to GAM7 Mac (unsafe).
6. Click Continue and Allow.
7. Copy the authorization code provided and paste it back into Terminal.

Step 7: Service Account & Domain-Wide Delegation

This is the final boss battle. We need to give a Service Account permission to act on behalf of your users.

1. In Terminal, GAM will ask if you want to authorize the Service Account. Say Yes.
2. It will fail the first time and give you a link to the Admin Console.
3. Open that link (it takes you to Security > Access and data control > API controls > Domain-wide delegation).
4. Click Add new.
5. Client ID: GAM will display the Client ID in your terminal. Copy and paste it.
6. OAuth Scopes: GAM will print a massive comma-separated list of URLs in your terminal. Copy that entire block.
7. Paste it into the "OAuth Scopes" field in the Admin Console.
8. Click Authorize.

Step 8: Verify the Install

Back in your Terminal, tell GAM to check everything one last time. It might verify the time sync (your Mac needs to be within 1 second of Google's time servers!) and check the scopes.

Once it says "Pass," you are ready to roll. Test it with:

gam info domain

If you see your domain details pop up, congratulations! You have successfully installed GAM7 on macOS.

Tips, Tricks, and Troubleshooting

• Know Your Shell: Not sure if you are using zsh or bash? Type echo $0 in your terminal. If it says -zsh, use the .zshrc instructions above.
• Time Sync Failures: If GAM complains that your system time is too far off, go to System Settings > General > Date & Time and toggle "Set time and date automatically" off and on again to force a sync.
• Editing Configs: You can edit your gam.cfg file in ~/GAMConfig to set defaults. For example, add default_user = your_email@domain.com so you don't have to type it every time.
• Where am I? If you get lost in folders, just type pwd (Print Working Directory) to see exactly where you are in the file system.

FAQ

Q: Can I install GAM7 if I already have the old GAM? 
A: Yes! The installer will detect it. However, creating the new GAMConfig folder structure (Step 2) helps keep the new installation clean and separate from legacy data.

Q: Do I need to use Terminal every time? 
A: Yes, GAM is a command-line tool. But don't worry, you can copy and paste commands from a text editor if you prefer drafting them there first.

Q: Why did the install "fail" on the Service Account step? 
A: That is expected! GAM tries to check for access before you grant it. It fails to show you exactly what is missing, which prompts you to go to the Admin Console and add the scopes.

Q: I'm getting a "command not found" error. 
A: Ensure you reloaded your profile using source ~/.zshrc or restart your Terminal completely after installing.

How was that? Easier than you thought, right? Happy GAM-ing!