Getting Started

Welcome to gShell, now let's get started!

As an overview, you'll need to do the following steps to start using gShell.

1. Make sure you have PowerShell
   
2. Allow your domain to use APIs
   
3. Create a Google Developer's Console project
   
4. Install gShell
   
5. Import the Module
   
6. Set the Client ID and Secret
   
7. Authenticate
   

PowerShell

In order to use gShell, you'll need PowerShell, which is a Windows OS only tool, available in Windows XP and higher.

I recommend you have at least PowerShell 3.0, but if you're installing you may as well go ahead and install PowerShell 4.0. Both come as part of their respective Windows Management Framework installers which can be found along with a list of their own prerequisites on the Windows PowerShell System Requirements page.

Allow your domain to use APIs

You'll need to configure your Google Apps domain to allow the use of the APIs. If you haven't already, you can do so by following the Provisioning API and Google Apps utilities instructions on the Administrative APIs.

Create a Google Developer's Console project

Before you can use gShell, you must create your own project in the [The Google Developer's Console] and get a Client ID and Secret. GShell is a toolbelt that you customize to work for you, on behalf of you. With a Developer's Console project, you're creating the bits that gShell will connect to, customized just for you. More or less. Either way, it's necessary!

For more information on OAuth 2.0 setup, see [setting Up Oauth 2.0].

Here is a rundown of what you need to do:

1) Create a new project.

Name it something that makes sense to you, like 'gShell Toolkit for My Domain'. For more information, see [how to create, shut down, and restore projects].

2) Choose and enable which APIs you'd like to access.

Once you're in the API manager, look for a tab called Enabled APIs (accessible from the Overview area). Choose and enable any APIs you'll be using. If you don't enable an API here, gShell won't be able to access that API on your behalf.

For more information, see [how to enable and disable APIs].

If you're not sure which APIs to enable, you can see which APIs are available here. You can always come back and change this later. For instance, if you only plan to use this to create users, use the Admin Directory API.

3) Create new credentials.

In the navigation bar on the left, click on the Credentials link. Once there, click the blue Create credentials button and choose OAuth client ID. In the next step, under Application Type choose other. You'll be prompted with the Client ID and Client Secret. Copy these down for a bit later (put them in Notepad or something handy).

If you lose them or forget to copy them down you can always come back to get them later.

Installation

Once you have the prerequisites installed, the API enabled for your domain(s) and you have your project Client ID and Secret, head on over to the Downloads page and find the newest version of gShell to install. Then install it.

Import the Module

Once you've installed go ahead and boot up PowerShell. There are a few first-time steps to get going.

Note: If you've never run PowerShell before you may run in to an issue at some point where you see an error regarding 'the execution of scripts'. If you do, you may want to read this article that gives some PowerShell basics, and this page that has more information specific to the execution policy.

The first time you're in PowerShell after installing gShell, you'll need to import the module. That's as easy as typing the following:

Import-Module gShell

You may see a pause and a brief loading bar, but once that's done you're ready to start using gShell! Almost.

Enter the Client ID and Secret

Easy enough, just run the Set-gShellClientSecrets cmdlet to load this information in to gShell. For example:

Set-gShellClientSecrets -ClientId "sfalskdhflaksdf23234-adsfpkasdgalskjdf.apps.googleusercontent.com" -ClientSecret "a235fbdosidhf3f8dSDfwefo" #Note - this is gibberish that won't work for you!

Authentication

Any time you want to use a Cmdlet that is part of a particular API set with a particular user, you have to authenticate that user for that API. For example:

• if you use User A for the Gmail cmdlets, you have to authenticate.
• if you want to use User B for the Gmail cmdlets, you'll have to give gShell permission for THAT user as well
• if you then use User A for the Calendar cmdlets, you have to authenticate there too.

This should only have to be done once each time, however. gShell handles the rest.

So, the first time you run you'll need to authenticate, but that can be done by running pretty much any Cmdlet in gShell that talks to Google's servers (any cmdlet that doesn't have a noun starting with gShell). Alternately you can force this by running Invoke-ScopeManager. So, let's start with an easy one - be sure to replace the user and domain with something that exists for your domain:

Get-GAUser myuser mydomain.com

After you hit enter after typing that in with your own username and domain, you will have to interact with a scope (permissions) wizard in PowerShell - just follow the directions. Once you have finished your primary browser will open up taking you to a page asking you to authenticate. Just make sure you log in to (or are already logged in to) the domain and account you want to authenticate with, and follow the prompts. After you accept the browser window will either close itself or you'll see the message:

Received verification code. Closing...

At that point you can close the window and go back to your PowerShell window and carry on!

That's it for the basics! Once you get the information back you're all set and ready to go. From here you can take a look at the Cmdlets Index to see what other Cmdlets are available and how to use them or do anything else.

Enjoy!

######Edited: 2016/07/19