help audit

[jdx]

I went through the help and these are my findings. We either create separate issues for these or just knock them off and mark as completed:

CLI Manual Changes

General

• should explain how to get help from individual command on topic list
• aliases should be displayed on each command
• headers should say heroku apps not just apps
• org should be renamed to team within help
• defaults should be displayed somehow (we don't have good support for this in the CLI currently)
• --ssh-git use SSH git protocol instead of HTTPS
• --app and --org flags are missing
• -- is becoming –
• make bash comments gray:

Commands

• 2fa
  • "check 2fa status" should be more descriptive, say something else
• 2fa:generate-recovery-codes
  • s/generates/generate
• 2fa:disable
  • s/2fa/two-factor authentication
• "stupid thing is skipping topic _certs"
  • ???
• access:add
  • s/your/an
• access:add
  • make it clear flags are for org apps only
• access:add
  • --privileges needs description
• access:remove
  • s/your/an
• addons:create
  • should offer --wait-interval
• addons:docs
  • s/show URL, do not open browser/show URL but do not open browser
• apps:fork
  • should be hidden (may just need to be updated)
• apps:rename
  • I feel this command should be heroku apps:rename from to or heroku apps:rename to if it can be inferred from git. We can continue to support heroku apps:rename -a from too, but I think the default should be changed
• apps:stacks
  • should we hide this command?
• apps:set
  • check if apps:set shows correct git remote
• apps:transfer
  • should include bulk example output
• auth:2fa
  • 2fa stuff is shows under auth:2fa and 2fa. Let's just have auth:2fa
• auth:login
  • --sso do we have a documentation link for this?
• auth:logout
  • says "display the current logged in user"
• auth:token
  • "display the current auth token from the netrc file" (maybe "from ~/.netrc")
• authorizations
  • nest under oauth:authorizations
• authorizations
  • not very descriptive description
• authorizations:create
  • show scope examples
• buildpacks
  • buildpack_url weird snake casing
• buildpacks:add
  • should show example of how indexing works (it's not intuitive)
  • should use inquirer to make this easier
• buildpacks:clear
  • "clear all buildpacks set on the app" -> "clear all buildpacks from the app"
• buildpacks:remove
  • should use inquirer if index and URL not specified
• buildpacks:set
  • use inquirer if index not set
  • OR explain where it will be added
• certs
  • "for an app" -> "on an app"
• certs:auto
  • ACM -> Automatic Certificate Management
  • for an app -> on an app
• certs:auto:remove
  • for an app -> on an app
• certs:auto:refresh
  • for an app -> on an app
• certs:generate
  • --selfsigned -> --self-signed?
  • --keysize -> --key-size
  • -- is turning into –
• ci
  • strike: display the most recent CI runs for the given pipeline
• ci:debug
  • opens -> open
• ci:open
  • get rid of help text
  • change description to "open Heroku CI in browser"
• ci:rerun/run
  • how are these different?
• clients
  • nest under oauth:clients
• clients:update
  • sudo?
• "stupid thing is skipping topic commands"
  • ???
• config
  • for an app -> on an app
• config:get
  • for an app -> on an app
• config:set
  • ...on an app
• config:unset
  • ...on on app
• container
  • use containers - not a description of the command
  • this should not be displayed as it is not a core plugin
• container:login
  • logs in -> login
• container:logout
  • logs out -> logout
• container:push
  • builds -> build
• domains
  • for an app -> on an app
• domains:wait
  • for an app -> on an app
• drains
  • of an app -> on an app
  • --extended should be hidden
• drains:add
  • adds -> add
• drains:remove removes -> remove
• dyno:forward
  • --localPort -> --local-port
• features
  • should be explained more
• join/leave
  • hide this, leave it under apps:join
• keys
  • "display SSH keys added to your Heroku account"
• keys:add
  • --quiet needs description
• local
  • heroku -> Heroku
  • run Heroku app locally using node-foreman (link)
• local:run
  • run a one-off command using node-foreman (link)
  • --env needs description
  • --port needs description
• local:start
  • maybe hide this or local (use v6 alias)
• lock
  • hide this, use apps:lock
• login/logout
  • use auth:login/logout
• logout
  • "display the current logged in user"
• logs
  • extra line in example output
• maintenance
  • move under apps:maintenance
• members
  • --pending show only pending team invitations? (I may not be understanding what this does, let's make it clear)
• members:add
  • adds -> add
• members:remove
  • removes -> remove
• members:set
  • sets -> set
• orgs:open
  • does this not take an org? are we missing needsOrg flags maybe?
• outbound-rules
  • Outbound Rules -> outbound rules
• outbound-rules:add
  • Private Space -> space
• outbound-rules:remove
  • Rules -> rule?
  • Outbound Rules -> outbound rules
• pg:backups
  • flags all need descriptions
• pg:backups:cancel
  • (default newest) should be arg description
• pg:backups:capture
  • needs flag descriptions
• pg:backups:download
  • use flag default (note that core needs a bit of work for this)
• pg:backups:restore
  • needs flag descriptions
  • use arg description
• pg:backups:schedule
  • use flag default field
• pg:backups:schedule
  • description could be better
  • flag description should explain quotes on windows
• pg:backups:url
  • maybe something like this:
  • description: "generate URL to access backup"
  • help: "Note: Generated URL will be publicly accessible if it is known"
• pg:copy
  • only place we use "db", change to database
  • need flag descriptions
• pg:credentials
  • --reset: there are lots of commands already, but I feel this should be pg:credentials:reset instead
• pg:credentials:create
  • show a psql example maybe?
• pg:credentials:repair-default
  • why not pg:credentials:repair?
• pg:kill
  • --force needs description
• pg:links
  • typo "datbases"
• pg:links:destroy
  • destroys -> destroy
• pg:maintenance:run
  • needs more description
• pg:promote
  • your -> app's
• pg:pull/push
  • would it be possible for this to all be pg:copy?
• pg:unfollow
  • writeable or writable? I think we use both, we should settle on one
• pg:wait
  • we should get some consistency around how we describe these like with addons:wait
  • very least should be block not blocks
• pipelines:add
  • stage of first app? I only see 1 app
• pipelines:list
  • hide this alias
• ps
  • hide all ps commands, I think we decided this should be dyno, some commands are already in both
• psql
  • hide this alias from the root
• run
  • dyno size - can we list the sizes here? may require a web request, but that's maybe ok if we can figure out a way to cache it or something. This would require asyncing the loading of commands, but that work is already started for other reasons. Maybe we could take advantage of the events idea and replace the help content later?
• sessions
  • lets nest this under oauth:sessions
• spaces:create
  • channel missing description
• spaces:peerings:accept
  • accepts -> accept
• spaces:peerings:destroy
  • destroys -> destroy
• spaces:peerings:rename
  • I've had different feelings on this in the past, but I feel like rename is a common enough convention to have 2 args here instead of flags
• spaces:vpn:destroy
  • destroys -> destroy
• spaces:vpn:wait
  • interval should be wait-interval to match others
• spaces:wait
  • interval should be wait-interval to match others
• teams
  • why are there no commands underneath teams?
• twofactor
  • remove this in favor of auth:2fa
• unlock
  • remove me in favor of apps:unlock
• which
  • "show which plugin a command is a part of"
• whoami
  • hide in favor of auth:whoami
• releases:last?