Cli: The Great Subcommanding

[jdxcode]

I'd like to simplify our help by reducing the amount of topics we have in the CLI by nesting them in different places. For example, heroku stack and heroku stack:set are virtually useless now. This topic sits at the top-level though, so when heroku help is run, they show up alongside everything else. I think they're better moved to heroku apps:stacks and heroku apps:stacks:set (plural form keeps with convention in other parts of the CLI)

For reference, here is our help today:

Usage: heroku COMMAND [--app APP] [command-specific-options]

Primary help topics, type "heroku help TOPIC" for more details:

  addons    #  manage add-on resources
  apps      #  manage apps (create, destroy)
  auth      #  authentication (login, logout)
  config    #  manage app config vars
  domains   #  manage domains
  logs      #  display logs for an app
  ps        #  manage dynos (dynos, workers)
  releases  #  manage app releases
  run       #  run one-off commands (console, rake)

Additional topics:

  2fa            #  manage two-factor authentication settings
  access         #  CLI to manage access in Heroku Applications
  buildpacks     #  manage the buildpack for an app
  certs          #  manage ssl endpoints for an app
  deploy         #  deploy to an app
  drains         #  display drains for an app
  features       #  manage optional features
  fork           #  clone an existing app
  git            #  manage local git repository for app
  help           #  list commands and display help
  keys           #  manage authentication keys
  labs           #  manage optional features
  local          #  run heroku app locally
  login          #  login with your Heroku credentials.
  logout         #  clear your local Heroku credentials
  maintenance    #  manage maintenance mode for an app
  members        #  manage membership in organization accounts
  notifications  #  display notifications
  orgs           #  manage organization accounts
  pg             #  manage heroku-postgresql databases
  pgbackups      #  manage backups of heroku postgresql databases
  pipelines      #  manage collections of apps in pipelines
  plugins        #  manage plugins to the heroku gem
  regions        #  list available regions
  spaces         #  manage heroku private spaces
  stack          #  manage the stack for an app
  status         #  status of the Heroku platform
  twofactor      #  manage two-factor authentication settings
  update         #  update the heroku client
  version        #  display version

Here are my suggestions on where to move commands in order of how much I think they should be moved:

• [ ] access:* -> apps:access:* under discussion here: https://github.com/heroku/heroku-orgs/issues/40
• [ ] members:* -> orgs:members:*
• [x] pgbackups (this isn't even active, should definitely go)
• [x] version (still available, just doesn't need to be displayed in help, maybe help could just display the version too)
• [x] 2fa:* -> auth:2fa:*
• [x] twofactor:* -> auth:twofactor:* (probably get rid of this or 2fa as far as help goes)
• [x] fork -> apps:fork (I would like to kill this, review apps are way better and more reliable)

Commands like config, run, ps, and pipelines I think are better staying as top-level even though they're directly having to do with apps. Potentially though these could be aliased to apps:config etc for consistency though. It would be nice for heroku help apps to show everything you can do with an app.

Especially with the apps and orgs commands, I think this nesting makes the help much better. Right now if I say heroku help orgs, it doesn't actually tell me how to add someone to an org because that's not where those commands are nested!

In the new CLI I also plan to get rid of 'primary' vs 'additional' topics. I don't think it's very easy to find what you're looking for with the arbitrary splitting. Also, being a CLI you have to scroll back UP to see the primary ones. Which is not very usable IMO.

Note that when I say _move_ I mean move, but leave an alias to the old command. So you'll still be able to run everything as they were before, it just won't be displayed in help under the root heroku help.

Now what do you think? Is this a huge mistake? Am I overloading apps:*?

cc @heroku/management-experience @heroku/devex @heroku/hit

[jdxcode]

cc @heroku/ecosystem

[naaman]

Note that when I say move I mean move, but leave an alias to the old command. So you'll still be able to run everything as they were before, it just won't be displayed in help under the root heroku help.

👍

[bjeanes]

plural form keeps with convention in other parts of the CLI

I only think this makes sense if you can have more than 1 stack for an app, which you can't.

[bjeanes]

@dickeyxxx this sounds awesome. 👍 on the plan.

[jdxcode]

@bjeanes we might be able to make that command hidden, because I don't think we're intending to ever use it again, so the point may be moot. Though heroku stack lists all the available stacks, which seems like it would be better plural.

[jdxcode]

cc @heroku/devcenter

[jdxcode]

@bjeanes your comment made me think though, we should be more flexible in regards to accepting non-plura names when the command is plural. heroku app:buildpack should be the same as heroku apps:buildpacks since we know what the user meant

[jdxcode]

@heroku/dod-ux @heroku/dod-kzc I feel like if we do this, it would make sense to bring in heroku-redis, heroku-kafka, etc into the core. Free up useless commands for some we want to promote!

[uhoh-itsmaciek]

Are we set on the topic:subtopic:command syntax? With pg:backups we went with topic:subtopic command, which I believe we had discussed with CLI (I think it was even you @dickeyxxx) at the time. It would kinda suck to have inconsistent hierarchical namespacing.

Other than that, +1 on namespace cleanup.

[jdxcode]

@uhoh-itsmaciek that predated me, I've always pushed for subtopics. With the new CLI I can (though haven't yet) start doing better things with help using it. Essentially when someone runs heroku help pg:backups I could list out everything under heroku pg:backups:*. If the command has it's own subcommanding logic I won't be able to do that.

[jdxcode]

behind the scenes it'll be really primitive, just set up like this:

{
  topic: 'pg',
  command: 'backups:foo'
}

But when I run help I can just filter things matching the string before the colon. I think it'll work pretty well.

[jonmountjoy]

Great idea. Some thoughts:

Presumably the existing behavior will remain, while becoming secondary through the use of aliases?

With more to type, I'm sure there'll be more errors too. heroku apps:maintenance:on -a x I wish we had great command completion on zsh.

Labs: I'm not sure apps is the right place for labs. I suspect we've had "non-app-things" in labs. The same goes for features. This one feels odd.

Version: Agree it should display version by default when running help.

2FA, twofactor -> auth feel good

fork: looks good. To your comment, there's something very powerful about being able to "clone" an app, database and all, which review apps doesn't provide.

Looking at your help sample output, I spot a bug ( a mention of "gem" instead of "Heroku CLI" - "manage plugins to the heroku gem")

I've also, separately, proposed making login an alias for authenticate.

[gudmundur]

Nice! 👍

My main concern with this change is discoverability of commands and the fluency of typing the extra characters. Would heroku apps --help would list out all of the subtopics and commands? On the fluency, my assumption is that those are commands that are not often used, thus likely to be looked up with heroku help anyways.

Slight side note on fork, DevEx is likely going to pick it up this quarter in a similar way as we did with pipelines. I.e. kill the heroku-fork plugin, make it a platform primitive.

[jdxcode]

@gudmundur would be great to have fork get some attention, as a CLI plugin it's just not able to work as well as users expect. Should also work in dashboard ideally. It was also the first CLI plugin written, before I had good node conventions, and it is also just really complex, so the code is definitely the worst in the new CLI.

@jonmountjoy that's the current output, not sample output, but yeah the help text is a bit outdated there.

On labs, I'm not sure what you mean. Some labs features affect an app directly and some affect the user. I'm proposing we make the distinguishment clear, so app labs would be set via apps:labs:enable and user ones via apps:user:enable. There wouldn't be one command that tries to figure it out automatically. API also wants to add a feature that has the same name for a user and app, so we actually kind of have to resolve this somehow.

Autocompletion is somewhere on the road map. I have worked on it a bit, but I want to have it autocomplete not just command names, but flag and arg values (so it could complete app names and things). It'll take a bit more work, but certainly somewhere I would like to be.

For mistyping though, maybe we could do something like: https://github.com/nvbn/thefuck

I'm not sure what the command would be, but it would work like this:

$ heroku app:maintenance
Did you mean `heroku apps:maintenance`?
Run `heroku _` to run `heroku apps:maintenance`
$ heroku _
maintenance is on for myapp

Thoughts?

[jdxcode]

Oh and at least for now @gudmundur heroku help apps will list all subcommands individually

[jdxcode]

@raulb @naaman how do you feel about instead of moving heroku access to heroku apps:access we instead use heroku apps:members to match heroku orgs:members?

[naaman]

@dickeyxxx orgs:members doesn't really map to an app. A member of an org is an org-level concern. Whereas you manage a member or collaborator's access to apps at the app level. Because access can be managed for two kinds of things, member and collaborator, the more generic app:access still makes sense to me.

[uhoh-itsmaciek]

...so app labs would be set via apps:labs:enable and user ones via apps:user:enable.

I take it you meant user:labs:enable?

[jdxcode]

@uhoh-itsmaciek we decided not to go ahead with that one at shinzo. We're going to keep labs and features as-is.

[jdxcode]

this is actually done now (except the orgs stuff, but that is tracked here https://github.com/heroku/heroku-orgs/issues/40)