gsm

README

GSM

GoSpace Manager - Manage Google Workspace resources using a developer-friendly CLI written in Go.

Documentation

View complete documentation at https://gsm.hayashi-ke.online/.

Introduction

I created this tool first and foremost for myself for the following reasons:

• I wanted to get better at Go
• The existing tools like GAM and PSGSuite, while excellent, did not fit my use cases sometimes and I wanted to have the flexibility to quickly make changes myself
• Programming is fun!

If you need a mature and battle-tested tool with an active community, feel free to try one of the linked alternatives.
GSM does exactly what I need, but that does not necessarily mean that it will be useful to everyone.
However, by making it open source, I hope that I can help someone looking for a solution that other tools don't offer.

General Information

GSM was intentionally designed to be as close to the actual APIs as possible.
Because of that, it may not be as user-friendly as some of the alternatives out there.
On the plus-side, you can usually look at the Google API documentation that is linked to in every command's description to figure out how something works. Most flag descriptions are also taken from the official API docs, so I take no credit there!

License and Copyright

GoSpace Manager (GSM) is licensed under the GPLv3 as free software.
Copyright © 2020 Hannes Hayashi.

Third Party Libraries

GSM is based on open source technology and would not exist without the incredible work of some people:

• The engineers at Google who created the APIs and Go libraries GSM is based on
  • https://github.com/googleapis/google-api-go-client
• GSM uses Cobra and Viper for command and configuration management
  • https://github.com/spf13/cobra

Features

GSM currently supports the following APIs:

• Admin SDK Directory API
• Admin SDK Groups Settings API
• Admin SDK Enterprise License Manager API
• Cloud Identity Beta API
• Gmail API
• Google Calendar API
• Domain Shared Contacts API
• Google People API
• Google Drive API
• Google Sheets API (partly)

Most of these APIs allow you to manage multiple object types with each object type allowing multiple operations.
Overall, GSM supports over 65 main commands, with each one representing an API with multiple methods and each method implemented as a sub command. This amounts to over 500 commands in total, including over 200 "batch" commands that allow you to utilize CSV files to apply updates to multiple objects in a multi-threaded manner and over 30 "recursive" commands that allow you to apply updates to multiple users in one command, by specifying one or more organizational unit(s) (OUs) and/or group(s).

You can use GSM in one of two modes

• user: User mode allows you to use any Google account (even private ones) to access the APIs.
  Note that you will only have access to the resources and APIs your account can access!
• dwd: DWD (Domain Wide Delegation) allows you to utilize a GCP service account to impersonate user accounts in a Workspace domain.
  You need to add the service account and the appropriate scopes in the Admin Console of your Workspace domain to us this mode.

You can set up multiple configurations using gsm configs and switch between them using gsm configs load or by specifying the name of the config with the --config flag.

Output

GSM is a CLI for the official Google API. It is designed to be easily usable in scripts and workflows. To that end, I made the decision to ommit the implementation of "interesting" output that tells you what GSM is doing, because, while it may be neat to watch, it doesn't serve a purpose when you want to create a script that actually uses the output and I hate the idea of parsing unformatted text to make decisions. Therefore, all* of GSM's console output is parseable JSON or XML (mostly what the API returns).

If you want to use GSM's output in scripts, you may want to consider using the --compressOutput flag, to keep GSM from unnecessarily "prettying up" the output.

*the configs command is a notable exception.

Scripting examples

I highly recommend considering using GSM together with PowerShell or Python when creating scripts.
GSM works nicely with PowerShell's ConvertFrom-Json commandlet (although there are some issues with very large amounts of data).

You can take a look at some examples under scripting.

You can also try the auto-generated PowerShell module.
Note that this module is still experimental and is created with Crescendo, which is also still in beta. However, for an auto-generated module with over 500 functions and 70k lines of code, it seems to work reasonably well :).

Logging

As useful as the above may be, sometimes you need to understand what is happening or need to know why something didn't work as expected. For those times, GSM creates a log file in your home directory called "gsm.log" that contains error messages.
You can configure the location and name of the log file, either in your config file (see configs) or by using the --logFile flag when running a command. You can also use the log command to view or clear the log, wthout having to manually open it.

See Also

• Setup - How to set up GSM
• GSM - Command overview
• Batch commands - How to use batch commands
• Recursive commands - How to use recursive commands
• Examples - See some examples
• Scripting examples - Some examples on how to use GSM in scripts
• PowerShell module - Auto-generated PowerShell module

Documentation

Overview

Copyright © 2020 Hannes Hayashi

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see <http://www.gnu.org/licenses/>.