chore: fix descriptions and other docs issues

packages/cli/package.json

@@ -200,6 +200,12 @@
         "description": "two-factor authentication",
         "hidden": true
       },
+      "access": {
+        "description": "manage user access to apps"
+      },
+      "addons": {
+        "description": "tools and services for developing, extending, and operating your app"
+      },
       "apps": {
         "description": "manage apps on Heroku"
       },
@@ -224,6 +230,9 @@
       "commands": {
         "hidden": true
       },
+      "container": {
+        "description": "Use containers to build and deploy Heroku apps"
+      },
       "config": {
         "description": "environment variables of apps"
       },
@@ -260,16 +269,28 @@
       "maintenance": {
         "description": "enable/disable access to app"
       },
+      "members": {
+        "description": "manage organization members"
+      },
+      "orgs": {
+        "description": "manage organizations"
+      },
       "outbound-rules": {
         "description": "space outbound IP rules",
         "hidden": true
       },
+      "pg": {
+        "description": "manage postgresql databases"
+      },
       "pipelines": {
         "description": "manage pipelines"
       },
       "ps": {
         "description": "manage app dynos"
       },
+      "redis": {
+        "description": "manage heroku redis instances"
+      },
       "reviewapps": {
         "description": "manage reviewapps in pipelines"
       },
@@ -283,6 +304,9 @@
         "description": "list available stacks",
         "hidden": true
       },
+      "teams": {
+        "description": "manage teams"
+      },
       "twofactor": {
         "description": "two-factor authentication",
         "hidden": true

packages/cli/src/commands/addons/index.ts

@@ -222,7 +222,15 @@ function displayJSON(addons: Heroku.AddOn[]) {
 
 export default class Addons extends Command {
   static topic = topic
-  static description = 'lists your add-ons and attachments'
+  static usage = 'addons [--all|--app APP]'
+  static description = `
+  Lists your add-ons and attachments.
+
+  The default filter applied depends on whether you are in a Heroku app
+  directory. If so, the --app flag is implied. If not, the default of --all
+  is implied. Explicitly providing either flag overrides the default
+  behavior.
+  `
   static flags = {
     all: flags.boolean({char: 'A', description: 'show add-ons and attachments for all accessible apps'}),
     json: flags.boolean({description: 'return add-ons in json format'}),
@@ -235,11 +243,6 @@ export default class Addons extends Command {
     `$ heroku ${topic} --app acme-inc-www`,
   ]
 
-  static help = `The default filter applied depends on whether you are in a Heroku app
-  directory. If so, the --app flag is implied. If not, the default of --all
-  is implied. Explicitly providing either flag overrides the default
-  behavior.`
-
   public async run(): Promise<void> {
     const {flags} = await this.parse(Addons)
     const {app, all, json} = flags

packages/cli/src/commands/addons/upgrade.ts

@@ -11,8 +11,15 @@ import type {AddOnAttachmentWithConfigVarsAndPlan} from '../../lib/pg/types'
 export default class Upgrade extends Command {
   static aliases = ['addons:downgrade']
   static topic = 'addons'
-  static description = 'change add-on plan'
-  static help = 'See available plans with `heroku addons:plans SERVICE`.\n\nNote that `heroku addons:upgrade` and `heroku addons:downgrade` are the same.\nEither one can be used to change an add-on plan up or down.\n\nhttps://devcenter.heroku.com/articles/managing-add-ons'
+  static description = `
+  change add-on plan.
+  See available plans with \`heroku addons:plans SERVICE\`.
+
+  Note that \`heroku addons:upgrade\` and \`heroku addons:downgrade\` are the same.\
+  Either one can be used to change an add-on plan up or down.
+
+  https://devcenter.heroku.com/articles/managing-add-ons
+  `
   static examples = ['Upgrade an add-on by service name:\n$ heroku addons:upgrade heroku-redis:premium-2\n\nUpgrade a specific add-on:\n$ heroku addons:upgrade swimming-briskly-123 heroku-redis:premium-2']
   static flags = {
     app: flags.app(),

packages/cli/src/commands/certs/add.ts

@@ -33,8 +33,11 @@ async function configureDomains(app: string, heroku: APIClient, cert: SniEndpoin
 export default class Add extends Command {
   static topic = 'certs'
   static strict = true
-  static description = 'add an SSL certificate to an app'
-  static help = 'Note: certificates with PEM encoding are also valid'
+  static description = `
+  Add an SSL certificate to an app.
+
+  Note: certificates with PEM encoding are also valid.
+  `
   static examples = [
     heredoc(`$ heroku certs:add example.com.crt example.com.key
     If you require intermediate certificates, refer to this article on merging certificates to get a complete chain:

packages/cli/src/commands/container/pull.ts

@@ -7,7 +7,7 @@ import color from '@heroku-cli/color'
 export default class Pull extends Command {
   static topic = 'container'
   static description = 'pulls an image from an app\'s process type'
-  static usage = '$ heroku container:pull -a APP [-v] PROCESS_TYPE...'
+  static usage = 'container:pull -a APP [-v] PROCESS_TYPE...'
   static example = `
   ${color.cmd('$ heroku container:pull web')}        # Pulls the web image from the app
   ${color.cmd('$ heroku container:pull web worker')} # Pulls both the web and worker images from the app

packages/cli/src/commands/container/release.ts

@@ -19,7 +19,7 @@ type ImageResponse = {
 export default class ContainerRelease extends Command {
   static topic = 'container'
   static description = 'Releases previously pushed Docker images to your Heroku app'
-  static usage = 'heroku container:release'
+  static usage = 'container:release'
   static example = `
   ${color.cmd('heroku container:release web')}        # Releases the previously pushed web process type
   ${color.cmd('heroku container:release web worker')} # Releases the previously pushed web and worker process types`

packages/cli/src/commands/container/rm.ts

@@ -5,7 +5,7 @@ import color from '@heroku-cli/color'
 export default class Rm extends Command {
   static topic = 'container'
   static description = 'remove the process type from your app'
-  static usage = '$ heroku container:rm -a APP [-v] PROCESS_TYPE...'
+  static usage = 'container:rm -a APP [-v] PROCESS_TYPE...'
   static example = `
   ${color.cmd('heroku container:rm web')}        # Destroys the web container
   ${color.cmd('heroku container:rm web worker')} # Destroys the web and worker containers`

packages/cli/src/commands/container/run.ts

@@ -7,7 +7,7 @@ import color from '@heroku-cli/color'
 export default class Run extends Command {
   static topic = 'container'
   static description = 'builds, then runs the docker image locally'
-  static usage = '$ heroku container:pull -a APP [-v] PROCESS_TYPE...'
+  static usage = 'container:run -a APP [-v] PROCESS_TYPE...'
   static example = `
   ${color.cmd('$ heroku container:pull web')}        # Pulls the web image from the app
   ${color.cmd('$ heroku container:pull web worker')} # Pulls both the web and worker images from the app

packages/cli/src/commands/pg/backups/index.ts

@@ -17,6 +17,7 @@ export default class Index extends Command {
     at: flags.string({hidden: true}),
     quiet: flags.boolean({char: 'q', hidden: true}),
     app: flags.app({required: true}),
+    remote: flags.remote(),
   }
 
   public async run(): Promise<void> {

packages/cli/src/commands/pg/maintenance/window.ts

@@ -10,8 +10,8 @@ import heredoc from 'tsheredoc'
 export default class Window extends Command {
   static topic = 'pg';
   static description = heredoc(`
-    set weekly maintenance window
-    All times are in UTC
+    Set weekly maintenance window.
+    All times are in UTC.
   `);
 
   static example = '$ heroku pg:maintenance:window "Sunday 06:00" postgres-slippery-100';

packages/cli/src/commands/pg/settings/auto-explain.ts

@@ -10,7 +10,7 @@ export default class AutoExplain extends PGSettingsCommand {
   static description = heredoc(`
   Automatically log execution plans of queries without running EXPLAIN by hand.
   The auto_explain module is loaded at session-time so existing connections will not be logged.
-  Restart your Heroku app and/or restart existing connections for logging to start taking place.'
+  Restart your Heroku app and/or restart existing connections for logging to start taking place.
   `)
 
   static flags = {

packages/cli/src/commands/releases/index.ts

@@ -66,11 +66,11 @@ const getDescriptionTruncation = function (releases: Heroku.Formation[], columns
 export default class Index extends Command {
   static topic = 'releases'
   static description = 'display the releases for an app'
-  static usage = `$ heroku releases
-=== example Releases
-v1 Config add FOO_BAR email@example.com 2015/11/17 17:37:41 (~ 1h ago)
-v2 Config add BAR_BAZ email@example.com 2015/11/17 17:37:41 (~ 1h ago)
-v3 Config add BAZ_QUX email@example.com 2015/11/17 17:37:41 (~ 1h ago)`
+  static examples = [
+    'v1 Config add FOO_BAR email@example.com 2015/11/17 17:37:41 (~ 1h ago)',
+    'v2 Config add BAR_BAZ email@example.com 2015/11/17 17:37:41 (~ 1h ago)',
+    'v3 Config add BAZ_QUX email@example.com 2015/11/17 17:37:41 (~ 1h ago)'
+  ]
 
   static flags = {
     num: flags.string({char: 'n', description: 'number of releases to show'}),

packages/cli/src/commands/releases/rollback.ts

@@ -8,8 +8,11 @@ import {stream} from '../../lib/releases/output'
 export default class Rollback extends Command {
   static topic = 'releases'
   static hiddenAliases = ['rollback']
-  static description = 'rollback to a previous release'
-  static help = 'If RELEASE is not specified, it will rollback one release'
+  static description = `
+    Roll back to a previous release.
+
+    If RELEASE is not specified, it will roll back one release.
+    `
   static flags = {
     remote: flags.remote(),
     app: flags.app({required: true}),