Repository: deis/deis

Issue:
`deis help` doesn't list 'sharing' commands
When running 'deis help', commands related to sharing aren't listed. It lists perms (which looking at the code 'sharing' is a shortcut to), but docs refer to sharing.



Discussion:
Good point--we implemented the sharing-related commands as `deis perms` and made `sharing` the Heroku-compatible shortcut name, but that's confusing. @gmeans would simply replacing "perms" with "sharing" in the main help message clear this up?

@mboersma (disclaimer: I'm new to deis) I think there's context for both terms in the platform, so I'd be concerned about just switching the help text.

For example, at the moment perms:add --admin sets someone as a platform admin, but will there be use for application admins? For example when service discovery comes into play, I could see wanting some developers having access to define the services for an app (or env vars) while others can only push.

I don't mean to open up a larger topic, but perhaps 'perms' should imply platform level permissions while 'sharing' points at application level permissions? Or something more explicit using the perms command w/ a flag indicating platform or application level?

I'm sure some of that is up in the air though, so maybe just adding sharing to the list (even though sharing / perms are the same thing) in the help text would be the way to go for the short term.

What I'd like to avoid is documenting both `sharing` and `perms` in the main `deis help` usage string, since one is a shortcut for the other. But that would involve tidying up all documentation to ensure we only reference `deis sharing`, and also fixing this somehow:

``` console
$ deis help sharing
Lists all users with permission to use an app, or lists all users with system
administrator privileges.

Usage: deis perms:list [-a --app=<app>|--admin]

Options:
  -a --app=<app>
    lists all users with permission to <app>. <app> is the uniquely identifiable name
    for the application.

  --admin
    lists all users with system administrator privileges.
$ deis help perms
Valid commands for perms:

perms:list            list permissions granted on an app
perms:create          create a new permission for a user
perms:delete          delete a permission for a user

Use `deis help perms:[command]` to learn more.
```

We can't have `deis help perms` show available commands that `deis help sharing` doesn't, or at least there needs to be a way to show them.

Another solution for this issue might be to refer _only_ to `deis perms` in the documentation and allow `deis sharing` to be a quiet shortcut. It would still be visible here:

``` console
$ deis shortcuts
Valid shortcuts are:

create     -> apps:create
destroy    -> apps:destroy
info       -> apps:info
login      -> auth:login
logout     -> auth:logout
logs       -> apps:logs
open       -> apps:open
passwd     -> auth:passwd
pull       -> builds:create
register   -> auth:register
rollback   -> releases:rollback
run        -> apps:run
scale      -> ps:scale
sharing    -> perms:list
whoami     -> auth:whoami

Use `deis help [command]` to learn more
```

I'm not sure what the best solution is here yet, just throwing out some ideas.

@gmeans that's the permissions model as of today, however anyone you add has permission to push, add envvars, etc. similar to Heroku. There's 3 concepts of user perms: platform administrators, application owners and application users. Having `perms` (or a `groups` command) imply platform-level permissions is something we can discuss in another bug. Let's keep the discussion in the present :)

I think only referring to `deis perms` in the docs would be the simplest and most straight-forward approach. 


Resolving patch:
diff --git a/client/deis.py b/client/deis.py
--- a/client/deis.py
+++ b/client/deis.py
@@ -24,7 +24,7 @@
   keys          manage ssh keys used for `git push` deployments
   perms         manage permissions for applications
 
-Developer shortcut commands::
+Shortcut commands, use ``deis shortcuts`` to see all::
 
   create        create a new application
   scale         scale processes by type (web=2, worker=1)


Test patch: