GoSpace Manager

Version v0.11.0

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

GSM

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

Go Report Card

Introduction

GSM is like gcloud for Google Workspace. It is a no-dependency, free and open source command line interface (CLI) for managing Google Workspace resources. You don’t need any software except for the GSM binary itself and it is easy to set up.

GSM is extremely powerful and flexible, especially when used in scripts to implement your own custom logic for your specific use case. Since GSM supports pretty much every API endpoint that Google offers for Workspace, there shouldn’t really be anything you can’t do with GSM, as long as the API supports it.
You can also configure pretty much every aspect of GSM, because everyone likes having choices.

GSM also supports many custom commands for common tasks to make your life easier, such as

and many more.

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.

Features

GSM currently supports the following APIs:

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 three 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.
  • adc: ADC (“Application Default Credentials”) mode works like DWD mode, but it allows you to utilize Application Default Credentials, such as the implicit credentials of a Compute Engine instance’s Service Account or the “application-default” credentials of the Google Cloud SDK (gcloud), to impersonate a Service Account. This means you don’t have to manage Service Account key files.

See Setup on how to set up GSM in these modes.

You can also 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. Depending on the tools you use and how you want to build your workflow, you may also want to consider using the --streamOutput flag, which will cause GSM to stream single objects directly to stdout. This may be significantly faster and use a lot less memory, but keep in mind that not all applications can properly utilize a stream of JSON objects.

*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 created with Crescendo, which is also still in beta. However, for an auto-generated module, it seems to work reasonably well. The module also automatically utilizes streaming.

Shell Autocompletion

GSM offers scripts to enable autocompletion in bash, PowerShell and zsh, courtesy of https://github.com/spf13/cobra/blob/master/bash_completions.md. For details see shell completion.

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 --log flag when running a command. You can also use the log command to view or clear the log, wthout having to manually open it.

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

Third Party Libraries

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

See Also

Downloads and Source Code

GSM on Github

Current version: v0.11.0 (released on 2023-10-30)