How to talk to GAM

An introduction to working with Google Admin Manager, a command-line interface to the Google Admin Console

There is a basic syntax for how to build a GAM command. Basically, get GAM’s attention (by calling its name) and then tell it what you want it to do.

So, for example, let’s say we want to tell GAM to create a new user in our domain. Let’s say we want give an account to Clark Kent, a new teacher in our High School. The simple command would be:

`gam create user clark.kent@school.org

That’s it. Let’s examine it, even though it’s simple. The command has four parts:

  1. gam: this initiates the GAM command; we are saying, “Hey, GAM, listen up! I’m about to tell you something.”
  2. create: this is an imperative verb; we are actually telling GAM to do something (in this case, we are telling it to create a new entity).
  3. user: grammatically speaking, this is the object of the verb. So far, we said “GAM, create!” With this additional word, we are telling GAM exactly what we want it to create, a new User.
  4. clark.kent@school.org: finally, we give this new entity a name. In the world of Google Workspace, every user has an email address to make them unique.
    Now, there is a lot more involved with creating Users. If you visit the official [online reference of GAM commands], a complete command for creating a User can look something like this:
    gam create user firstname lastname password [suspended on|off] [changepassword on|off] [gal on|off] [sha] [md5] [crypt] [nohash] [org ] [recoveryemail [recoveryphone ]

Relax. There’s a lot of options there, but it’s really not that scary. 🙂

First, let’s talk about how you read it. When looking at GAM reference materials and example commands, there are lots of options and possibilities. As we saw above, creating an account for Clark Kent was a simple, four-work command. But, as you might imagine, account creation could be more complex, and that big, scary block of code includes every single option you could set for a new User.

When you read example GAM commands (which you’re going to do more and more often and you feel out what you can use GAM to do), remember these rules:

  • Parts of a command enclosed in are mandatory.
  • Parts of a command enclosed in [square brackets] are optional.
  • Parts of a command separated by a vertical | line are choices you make. (That vertical line is called a “pipe” by nerds and is usually located on the key just above the Return/Enter key on your keyboard.)
  • In most cases, multiple optional fields may be included in a single command.

So, let’s return to Clark Kent, our heroic new teacher. We created a User account for him, but we didn’t set up his name, so when he sends out mail, it’s going to come from clark.kent@school.org instead of being from Clark Kent. We could have used some of those other optional commands to do it right.

Before, we told GAM:
gam create user clark.kent@school.org

But, looking back at the full set of options, you have probably already figured out that we could have specified values for his first and last name, too. If we did, the full command would look like this:
gam create user clark.kent@school.org firstname Clark lastname Kent

See what we did there? We took some optional code and added it in to our create user command. The list of options says, firstname <First Name> lastname <Last Name> and remember, things in are mandatory.

In English, our new command says, “Hey, GAM, I want you to create a new user for me, with the email address clark.kent@school.org. His first name is Clark and his last name is Kent.”

See? Not so complicated. Now that you’ve seen that, let’s take another look at the command, as we sent it to GAM:
gam create user clark.kent@school.org firstname Clark lastname Kent

You can probably read and understand that yourself, now. And, if we wanted to set some other options, we could just tack on more of the optional parts of the Create command. See if you can figure out what’s going on here:
gam create user clark.kent@school.org firstname Clark lastname Kent password '#1SonOfKrypton' changepassword on org Faculty/Highschool recoveryemail ckent974@aol.com
Did you get it?
“Hey, GAM, create a new User with the email clark.kent@school.org. His full name is Clark Kent and his password is #1SonOfKrypton but force him to change it when he first logs in. Create his account in the Highschool Org Unit inside the Faculty Org Unit and use his lame AOL email account for recovery if he ever forgets his password.”
A couple of details:

  • See how his password is wrapped in single quotes? We do that because passwords often contain special characters (L!k3 the$e) and we don’t want GAM to misinterpret those are commands.
  • Also, if you’re ever using two English words as the second part of a command, like firstname "Mary Jane" lastname Watson, you have to wrap those in double quotes to avoid confusion. (You could even wrap the single-word stuff in quotes if you want, but nobody does and GAM is OK with that.)

Leave a comment

Your email address will not be published. Required fields are marked *