heroku / heroku-orgs

this code is now in https://github.com/heroku/cli

Heroku Orgs CLI

Available commands

https://github.com/heroku/heroku-orgs/blob/master/index.js.

Development

First, please read Developing CLI Plugins on Heroku's DevCenter.

Run Tests

$ npm test

Deploy

1. Release a new version of this npm package.

$ npm version patch/minor/major

2. Open a new pr in https://github.com/heroku/cli/blob/master/package.json, updating to the appropriate heroku-orgs version.

Commands

• heroku access
• heroku access:add EMAIL
• heroku access:remove EMAIL
• heroku access:update EMAIL
• heroku apps:join
• heroku apps:leave
• heroku apps:lock
• heroku apps:transfer RECIPIENT
• heroku apps:unlock
• heroku join
• heroku leave
• heroku lock
• heroku members
• heroku members:add EMAIL
• heroku members:remove EMAIL
• heroku members:set EMAIL
• heroku orgs
• heroku orgs:open
• heroku teams
• heroku unlock

heroku access

list who has access to an app

USAGE
  $ heroku access

OPTIONS
  -a, --app=app        (required) app to run command against
  -r, --remote=remote  git remote of app to use
  --json               output in json format

heroku access:add EMAIL

add new users to your app

USAGE
  $ heroku access:add EMAIL

OPTIONS
  -a, --app=app                  (required) app to run command against
  -p, --permissions=permissions  list of permissions comma separated
  -r, --remote=remote            git remote of app to use

EXAMPLES
  $ heroku access:add [email protected] --app APP # add a collaborator to your app
  $ heroku access:add [email protected] --app APP --permissions deploy,manage,operate # permissions must be comma separated

heroku access:remove EMAIL

remove users from a team app

USAGE
  $ heroku access:remove EMAIL

OPTIONS
  -a, --app=app        (required) app to run command against
  -r, --remote=remote  git remote of app to use

EXAMPLES
  $ heroku access:remove [email protected] --app APP

heroku access:update EMAIL

update existing collaborators on an team app

USAGE
  $ heroku access:update EMAIL

OPTIONS
  -a, --app=app                  (required) app to run command against
  -p, --permissions=permissions  comma-delimited list of permissions to update (deploy,manage,operate)
  -r, --remote=remote            git remote of app to use

EXAMPLES
  $ heroku access:update [email protected] --app APP --permissions deploy,manage,operate

heroku apps:join

add yourself to an organization app

USAGE
  $ heroku apps:join

OPTIONS
  -a, --app=app        (required) app to run command against
  -r, --remote=remote  git remote of app to use

heroku apps:leave

remove yourself from an organization app

USAGE
  $ heroku apps:leave

OPTIONS
  -a, --app=app        (required) app to run command against
  -r, --remote=remote  git remote of app to use

heroku apps:lock

prevent organization members from joining an app

USAGE
  $ heroku apps:lock

OPTIONS
  -a, --app=app        (required) app to run command against
  -r, --remote=remote  git remote of app to use

heroku apps:transfer RECIPIENT

transfer applications to another user or team

USAGE
  $ heroku apps:transfer RECIPIENT

ARGUMENTS
  RECIPIENT  user or team to transfer applications to

OPTIONS
  -a, --app=app        app to run command against
  -l, --locked         lock the app upon transfer
  -r, --remote=remote  git remote of app to use
  --bulk               transfer applications in bulk

EXAMPLES
  $ heroku apps:transfer [email protected]
  Transferring example to [email protected]... done

  $ heroku apps:transfer acme-widgets
  Transferring example to acme-widgets... done

  $ heroku apps:transfer --bulk acme-widgets
  ...

heroku apps:unlock

unlock an app so any organization member can join

USAGE
  $ heroku apps:unlock

OPTIONS
  -a, --app=app        (required) app to run command against
  -r, --remote=remote  git remote of app to use

heroku join

add yourself to an organization app

USAGE
  $ heroku join

OPTIONS
  -a, --app=app        (required) app to run command against
  -r, --remote=remote  git remote of app to use

heroku leave

remove yourself from an organization app

USAGE
  $ heroku leave

OPTIONS
  -a, --app=app        (required) app to run command against
  -r, --remote=remote  git remote of app to use

heroku lock

prevent organization members from joining an app

USAGE
  $ heroku lock

OPTIONS
  -a, --app=app        (required) app to run command against
  -r, --remote=remote  git remote of app to use

heroku members

list members of an organization or a team

USAGE
  $ heroku members

OPTIONS
  -r, --role=role  filter by role
  -t, --team=team  team to use
  --json           output in json format
  --pending        filter by pending team invitations

heroku members:add EMAIL

adds a user to an organization or a team

USAGE
  $ heroku members:add EMAIL

OPTIONS
  -r, --role=role  (required) member role (admin, collaborator, member, owner)
  -t, --team=team  team to use

heroku members:remove EMAIL

removes a user from an organization or a team

USAGE
  $ heroku members:remove EMAIL

OPTIONS
  -t, --team=team  team to use

heroku members:set EMAIL

sets a members role in an organization or a team

USAGE
  $ heroku members:set EMAIL

OPTIONS
  -r, --role=role  (required) member role (admin, collaborator, member, owner)
  -t, --team=team  team to use

heroku orgs

list the organizations that you are a member of

USAGE
  $ heroku orgs

OPTIONS
  --enterprise  filter by enterprise orgs
  --json        output in json format
  --teams       filter by teams

heroku orgs:open

open the organization interface in a browser window

USAGE
  $ heroku orgs:open

OPTIONS
  -t, --team=team  team to use

heroku teams

list the teams that you are a member of

USAGE
  $ heroku teams

OPTIONS
  --json  output in json format

heroku unlock

unlock an app so any organization member can join

USAGE
  $ heroku unlock

OPTIONS
  -a, --app=app        (required) app to run command against
  -r, --remote=remote  git remote of app to use

heroku-orgs's Issues

Update members help text

The help text from heroku help members needs to be reworked around teams.

• There should be examples with the --team flag that mention team instead of org
• members:add text needs to mention that members are invited for teams but added for orgs
• members:remove text needs to mention that it will either revoke an invite or remove a sitting member
• members:set should probably mention that pending invitations will be revoked and a new one issued with the new role, while sitting members will be updated

Heroku-orgs using API v2 endpoint for the leave command

I just found this one! Otherwise I think we're all good:

heroku-orgs/commands/apps/leave.js

Line 12 in 68a6cf5

path: `/v1/app/${context.app}/join`,

/cc @raulb

Consolidate this plugin into the existing heroku-cli

• Rename heroku-access to heroku-orgs
• Consolidate new with old design.
• Make sure that everything works in sudo
• Making sure the output over the existing orgs commands doesn't change

cc @dickeyxxx

Add message to deprecate `heroku orgs:default`

https://github.com/heroku/heroku/blob/master/lib/heroku/command/orgs.rb#L50-L52

It should be clear that permissions are ignored when using static-permissions orgs

$ heroku access:add [email protected] --privileges deploy -a app-name
Adding [email protected] access to the app app-name... done

$ heroku access -a app-name
[email protected]     collaborator  deploy,operate,view

That looks like a bug, but the reason [email protected] has that extra deploy permission is because app-name belongs to an organization with static-permissions, which can't be selected.

Be specific with CLI error messaging

When adding comma-delimited items in a CLI command. if a user adds a space after the comma the CLI presents a misleading error. Example:

The error is the inclusion of the space, not the "manage" parameter.

Note that the beta example does include spaces:

cc @raulb

Update / add docs for orgs commands

• heroku apps:transfer

- [ ] heroku access:*

Fix error when there is an orphan org

herokutest11 doesn't have any members:

➼  scripts [rbarroso-ltm] { master } ✗ heroku members -o herokutest11
No members in herokutest11 with role undefined

members:set is broken

maciek@mothra:~$ heroku members:set --role admin [email protected] --org dod
Inviting [email protected] to dod as admin... !
 ▸    [email protected] user cannot be invited because they are already in dod team

It looks like there was an API change that means you can't "upsert" roles anymore, which seems to be the behavior that members:set was relying on (since it's just a copy of members:add).

port these commands to this plugin

• apps:join
• apps:leave
• apps:lock
• apps:unlock
• members
• members:add
• members:remove
• members:set
• orgs
• orgs:open

- [ ] orgs:info ❓

• sharing
• sharing:add
• sharing:remove
• sharing:transfer

Customers cannot cancel app transfers

$ curl -XDELETE -H "Authorization: Bearer `h auth:token`" https://api.heroku.com/account/app-transfers/<uuid> -H "Content-Type: application/json" \
  -H "Accept: application/vnd.heroku+json; version=3"

is a thing. Customers can create app transfers via the CLI, but the can't kill them.

Add CONTRIBUTING.md

Make sure `heroku access` works for admins in FGAC orgs

Nesting commands under apps:* and orgs:*

I'm working on reducing the number of topics under heroku help. Right now there are a lot of uncommonly used commands that I think would be better if they were nested outside of main topics (like heroku stack could be heroku apps:stacks for example).

I think a lot of these commands could be moved into better places to both clean up the help and make the CLI easier to use. (Note that when I say 'move', I mean move but leave a hidden alias so the old commands will still work, just be hidden from help).

I always get confused when I should be using access:* or members:*. I think these could be moved to apps:access:* and orgs:access:* to keep the same language and patterns across both.

So for example, instead of heroku access:add it would be heroku apps:access:add and instead of heroku members:add it would be heroku orgs:access:add.

This has another benefit of helping users find out how to work with orgs and apps, if they run heroku help orgs it doesn't tell them how to actually add someone to an org right now, this would solve that problem.

Correct "No members in <orgname>" text when --pending used

STR:

1. Ensure you're a member of an org that has no pending member invites
2. Run heroku members --org my-org-name --pending

Expected:
"No pending invites in my-org-name" (or similar)

Actual:
"No members in my-org-name"

Using:
heroku-cli/5.6.27-7c0098a (windows-amd64) go1.7.5

Add headers to the commands that already exist

Improve discovery on teams

Implement

heroku teams

heroku apps --team TEAM-NAME

etc...

Allow access:add to update an existing user's permissions

STR:

1. As an enterprise org admin, have a user come to you and ask to be given manage permissions on multiple apps.
2. Try to give the user the permissions using heroku access:add <EMAIL> --permissions view,deploy,operate,manage --app <APP> on each app.

Expected:
Regardless of whether the user is already a collaborator on the app, the access:add command ensures that their permissions are updated to include manage. Alternatively, have a command like access:set which does that.

Actual:
If the user was already a collaborator on the app, but just had say only 'view' permissions, then their permissions aren't updated and instead the command returns with:

Adding <EMAIL> access to the app <APP> with deploy,manage,operate,view permissions... !
 !    User is already a collaborator on app <APP>

Trying to avoid this using access:update for each app doesn't work either, since in the opposite case (the user not being an existing collaborator), the command then errors with:

Updating <EMAIL> in application <APP> with deploy,manage,operate,view permissions... !
 !    Couldn't find that collaborator.

(Using heroku-cli/6.14.25-4fab11b (windows-x64) node-v8.4.0.)

As such in my bash script, I have to first try heroku access:add and if that fails then try again with heroku:update:

for app in "${apps[@]}"; do
    echo -e "\nAdjusting ${app}..."
    heroku access:add "${email}" --permissions "${permissions}" --app "${app}" \
        || heroku access:update "${email}" --permissions "${permissions}" --app "${app}"
done

It would be cleaner (and more performant) to be able to replace that with either a single access:add call or a new command that achieves the same (eg access:set).

Many thanks :-)

update to use `/teams/...` endpoints

apps:lock doesn't register as a command

$ heroku which apps:lock 
 ▸    apps:lock is not a heroku command.

Add help about --privileges

This doesn't say anything about how to use it with privileges

➼  heroku-access [rbarroso-ltm] { master } ✗ heroku help access
Usage: heroku access



Additional commands, type "heroku help COMMAND" for more details:

  access:add USER     #  Add new users to your app using specific privileges
  access:remove USER  #  Remove users from your app
  access:update USER  #  Update existing collaborators

Implement orgs:delete

Deprecate `sharing:*`

• heroku sharing:transfer = heroku apps:transfer
• heroku sharing = heroku access
• heroku sharing:add = heroku access:add
• heroku sharing:remove = heroku access:remove

says I'm an admin when I'm a collab

$ heroku members:remove [email protected] -o addons-ux
Removing [email protected] from addons-ux... !!!
 ▸    Your role admin on the organization addons-ux is not allowed to perform that action.

$ heroku orgs
heroku orgs
addons-ux                   collaborator
ex-idfed-sfdc-idp           collaborator
heroku                      admin
heroku-add-ons              admin
heroku-business-operations  collaborator
heroku-marketing            collaborator
heroku-support              collaborator

Start using heroku-cli-util

https://github.com/heroku/heroku-cli-util

-r flag doesn't work

heroku members:set [email protected] -r admin -o ORG-NAME
 ▸    Required flag:  -r, --role ROLE

also doesn't work if you user heroku members:set [email protected] -o ORG-NAME -r admin

Help discoverability of nested commands

i.e.: $ heroku help transfer should give me information about where that command lives (heroku apps:transfer), or even run it for me automatically.

Giving a hint could relevant in case of conflict (e.g.: heroku apps:transfer or heroku orgs:transfer, if the latter existed).

add heroku user to plugin

just in case someone needs to push a patch, it would be good to add the shared heroku account as a collab: https://www.npmjs.com/~heroku

Show collaborated apps in members command

e.g.: In a command like:

$ heroku members -o my-org
[email protected]    collaborator
[email protected]          collaborator
[email protected]         admin

I'd like to see in what apps the users collaborator and jack are collaborating to without having to navigate through each application.

bulk filtering

a couple things about --bulk. First, I think it would be useful to filter the list somehow. So I could look at just the apps I own personally, or from a specific org as a starting point.

Also, I think I found a bug I wasn't able to repro where they weren't all sorted alphabetically. So maybe it would be good to double-check the sorting logic?

Update README.md

`heroku teams` truncated

heroku teams only shows a subset of my teams.

$ heroku orgs
heroku-devex  admin
starfleet     admin

$ heroku teams
starfleet   admin

I believe teams and orgs should be synonymous.

Show what members have been federated in Enterprise Orgs

Something like:

$ heroku members -o ORG
[email protected]                        role           federated
[email protected]             role