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. If gShell has Cmdlets that work with a Gmail account and you have no intention of using anything else, you can skip anything related to a domain (step 2, mostly).

1. Install Prerequisites
   
2. Enable API
   
3. Install gShell
   
4. First cmdlet
   
5. Set the Client ID and Secret
   
6. Authenticate
   

##Prerequisites 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.

##Enable the API 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.

##Installation Once you have the prerequisites installed and the API enabled for your domain(s), head on over to the Downloads page and find the newest version of gShell to install.

##First Cmdlet 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!

##Enter the Client ID and Secret Google requires that you have a project in the Developer's Console from which you can retrieve a Client ID and Secret, used to track your own personal instance of gShell. Head over to the instructions on Set-gShellClientSecrets for more information on this step. It's one-time only for most everyone.

##Authentication You'll need to authenticate yourself the first time you run, but that can be done by running pretty much any Cmdlet in gShell that talks to Google's servers. (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! 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!