diff --git a/README.rst b/README.rst
index 6e629fe597..8ac6ce5ff9 100644
--- a/README.rst
+++ b/README.rst
@@ -2,29 +2,31 @@
 OpenStack Client
 ================
 
-This is an unified command-line client for the OpenStack APIs.  It is
+python-openstackclient is a unified command-line client for the OpenStack APIs.  It is
 a thin wrapper to the stock python-*client modules that implement the
-actual API clients.
+actual REST API client actions.
 
 This is an implementation of the design goals shown in 
 http://wiki.openstack.org/UnifiedCLI.  The primary goal is to provide
 a unified shell command structure and a common language to describe
 operations in OpenStack.
 
+python-openstackclient is designed to add support for API extensions via a
+plugin mechanism
+
+
 Configuration
 =============
 
-The cli is entirely configured with environment variables and command-line
-options.  It looks for the standard variables listed in
-http://wiki.openstack.org/UnifiedCLI/Authentication for
-the 'password flow' variation.
+The cli is configured via environment variables and command-line
+options as listed in http://wiki.openstack.org/UnifiedCLI/Authentication.
 
-::
+The 'password flow' variation is most commonly used::
 
-   export OS_AUTH_URL=url-to-openstack-identity
-   export OS_TENANT_NAME=tenant
-   export OS_USERNAME=user
-   export OS_PASSWORD=password    # yes, it isn't secure, we'll address it in the future
+   export OS_AUTH_URL=<url-to-openstack-identity>
+   export OS_TENANT_NAME=<tenant-name>
+   export OS_USERNAME=<user-name>
+   export OS_PASSWORD=<password>    # yes, it isn't secure, we'll address it in the future
 
 The corresponding command-line options look very similar::
 
@@ -33,9 +35,23 @@ The corresponding command-line options look very similar::
    --os-username <user-name>
    --os-password <password>
 
+The token flow variation for authentication uses an already-aquired token
+and a URL pointing directly to the service API that presumably was acquired
+from the Service Catalog::
+
+    export OS_TOKEN=<token>
+    export OS_URL=<url-to-openstack-service>
+
+The corresponding command-line options look very similar::
+
+    --os-token <token>
+    --os-url <url-to-openstack-service>
+
 Additional command-line options and their associated environment variables
 are listed here::
 
    --debug             # turns on some debugging of the API conversation
                          (via httplib2)
-
+   --verbose | -v      # Increase verbosity of output. Can be repeated.
+   --quiet | -q        # suppress output except warnings and errors
+   --help | -h         # show a help message and exit
\ No newline at end of file
diff --git a/openstackclient/shell.py b/openstackclient/shell.py
index f01b76c931..cd7a50bad1 100644
--- a/openstackclient/shell.py
+++ b/openstackclient/shell.py
@@ -70,12 +70,12 @@ class OpenStackShell(App):
         :param tenant_name: name of tenant
         :param auth_url: endpoint to authenticate against
         """
-        _ksclient = ksclient.Client(username=kwargs.get('username'),
+        self.ksclient = ksclient.Client(username=kwargs.get('username'),
                                     password=kwargs.get('password'),
                                     tenant_id=kwargs.get('tenant_id'),
                                     tenant_name=kwargs.get('tenant_name'),
                                     auth_url=kwargs.get('auth_url'))
-        return _ksclient.auth_token
+        return self.ksclient.auth_token
 
     def build_option_parser(self, description, version):
         parser = super(OpenStackShell, self).build_option_parser(
@@ -178,9 +178,12 @@ class OpenStackShell(App):
                 'auth_url': self.options.os_auth_url
             }
             token = self._authenticate(**kwargs)
-            # get service catalog via cmd.api
-        # get client instance here
-        print "api: %s" % cmd.api
+            endpoint = self.ksclient.service_catalog.url_for(service_type=cmd.api)
+
+        if self.options.debug:
+            print "api: %s" % cmd.api
+            print "token: %s" % token
+            print "endpoint: %s" % endpoint
 
     def clean_up(self, cmd, result, err):
         self.log.debug('clean_up %s', cmd.__class__.__name__)