Using AGM

Basic Usage

usage: agm [-h] [-v] [-u [USER [USER ...]]] [--outfile OUTFILE] [-d]
           [--version] [--scopes SCOPES [SCOPES ...]] [--keyfile KEYFILE] [-V]
           [--run_oauth] [--auth_info]
           [command [command ...]]

 _______ _______ __   __
|   _   |       |  |_|  |
|  |_|  |    ___|       |
|       |   | __|       |
|       |   ||  |       |
|   _   |   |_| | ||_|| |
|__| |__|_______|_|   |_|
version: 0.1.0

optional arguments:
  -h, --help            show this help message and exit
  -v, --verbose         longer output

API:
  Call the Google API or get docs with agm [service] [resource] [method]

  command               The name of the service to call e.g. drive files list.
  -u [USER [USER ...]], --user [USER [USER ...]], --users [USER [USER ...]]
                        The impersonated user(s).
  --outfile OUTFILE     Send output to a given file.
  -d, --docs            Open the documentation for this function.
  --version             specify api version, ie 'v2'. Optional
  --scopes SCOPES [SCOPES ...]
                        API scopes to give the key. Optional and usually
                        unnecessary. If not specified, AGM will try all
                        possible scopes that could authenticate a command
                        until it finds one that works. You can drop everything
                        before the last slash in the url, eg just use
                        gmail.readonly
  --keyfile KEYFILE     Optional. specify the keyfile to authenticate with. By
                        default, AGMlooks for a .json file inside ~/.agm

Tools:
  AGM tools

  -V                    AGM version
  --run_oauth           Authenticate an individual Google account and store
                        the credentials.Requires scopes and user to be set.
  --auth_info            Print information about authenticated keys

AGM maps commands to the associated Google API. Not all APIs have been tested, so please report any issues to the GitHub Issues page. Separate the API name (e.g. gmail) from the resources (e.g. user messages) from the method, like so:

agm gmail users messages list --user myemail@gmail.com --maxResults 100 --userId me

This will return a json with a summary of the request and and the response from the server. If the request failed, the error message will be in the “error” field. You can provide a list for any parameter and AGM will iterate over that list. For example, if I wanted to get information about a list of files,

NOTE: If you want to get a list of items and specify a field selection, make sure to specify “nextPageToken” in your fields query

agm drive files get --user myemail@gmail.com --fileId abc def ghi

And AGM will iterate over that list in order to get information about each file. If you provide multiple values for multiple parameters, AGM will iterate over each list together. AGM uses batch requests and multithreading for high performance, so AGM is especially suitable for very large, long-running tasks that involve many API requests.

AGM will automatically convert flags into data to send to the request body. For example if I want to create a file in drive, I can send the body directly as a key-value dictionary, such as

agm drive files create --user myemail@gmail.com --body "{'name': 'myfile'}"

This is a bit cumbersome, so AGM allows you to pass flags, and will determine whether or not they should be in the body of the request, like so:

agm drive files create --user myemail@gmail.com --name myfile

For documentation on a command, run the command with the -d or --docs flag. This flag can be ommitted if you want information about a service or resource. Just typing agm will list all of the available APIs.

If --outfile is ommitted, output will be printed to the console.

Logs are in ~/.agm/logs. Check them for debugging or if you need a record of recent actions performed by AGM.

Piping input

You can pipe input into AGM. For our previous command, if we wanted to get information about a large number of files, we could save these files to a text document, files.txt, and then pipe that file into AGM:

cat files.txt | agm drive files get --user myemail@gmail.com --fileId

AGM will also accept a json string as piped input of the format:

{
  "parameter": "value"
}

Note that performance will degrade if you try and pipe in an extremely large amount of input. This is an open issue that I am looking to resolve.

Advanced Usage

AGM is built to interact with other Unix command line tools, such as [jq](https://stedolan.github.io/jq/)

See the [examples](https://github.com/Cloudbakers/agm/tree/master/examples) folder for some examples of more complex actions