update help markdown files for all "sf env" commands (#84)

Author: jshackell-sfdc

messages/display.md

@@ -1,27 +1,42 @@
+# summary
+  
+Display details about an environment.
+
 # description
 
-Display details about a specific environment
+Specify an environment with either the username you used when you ran the "sf login" command or the environment's alias. Run "sf env list" to view all your environments and their aliases.
+
+Output depends on the type of environment. For example, scratch org details include the access token, alias, username of the associated Dev Hub, the creation and expiration date, the generated scratch org username, and more.  Compute environment details include the associated orgs, the list of functions, the project name, and more.
 
 # examples
 
-- sf env display -e my-scratch-org
-- sf env display -e user@name.com
+- Display details about a scratch org with alias my-scratch-org:
+
+ <%= config.bin %> <%= command.id %> --environment=my-scratch-org
+
+- Specify a username instead of an alias:
+
+ <%= config.bin %> <%= command.id %> --environment=test-123456-abcdefg@example.com
+
+- Specify JSON format and redirect output into a file:
+
+ <%= config.bin %> <%= command.id %> --environment=my-scratch-org --json > tmp/MyOrdDesc.json
 
 # flags.environment.summary
 
-Environment name or alias to display.
+Environment alias or login user.
 
 # error.NoResultsFound
 
-No results found
+No results found.
 
 # error.NoEnvFound
 
 No environment found for %s.
 
 # error.NoDefaultEnv
 
-No default environment found. Use -e or --environment to specify which env to open.
+No default environment found. Use -e or --environment to specify an environment to open.
 
 # error.NoAuthsAvailable
 

messages/list.md

@@ -1,20 +1,43 @@
+# summary
+  
+List the environments you’ve created or logged into.
+
 # description
 
-List the environments you’ve created or logged into.
+By default, the command displays only active environments. For orgs, active means unexpired scratch orgs and orgs you’re currently logged into. For compute environments, active means the environments connected to orgs you’re currently logged into. Use the --all flag to list expired or deleted scratch orgs and compute environments that aren’t connected to logged-in orgs. Warning: the latter list could be very long.
+
+Output is displayed in multiple tables, one for each environment type.  For example, the Salesforce Orgs table lists the non-scratch orgs you’re logged into, such as sandboxes, Dev Hubs, production orgs, and so on. Scratch orgs and compute environments get their own tables.
+
+For non-scratch orgs, the Username column refers to the user you logged into the org with. For scratch orgs it refers to the username that was generated for you when you created the scratch org. The first column indicates the default environment for each type.
+
+Run "sf env display" to view details about a specific environment.
 
 # examples
 
-- sf env list
-- sf env list --all
+- List all environments:
+
+  <%= config.bin %> <%= command.id %> --all
+
+- Filter the output to list only connected orgs. Rows from only the Salesforce Orgs table are displayed because it’s the only table with a "Status" column.
+
+  <%= config.bin %> <%= command.id %> --filter "Status=Connected"
+
+- List only scratch orgs that expire after May 30, 2021:
+
+  <%= config.bin %> <%= command.id %> --filter "Expiration>2021-05-30"
+
+- Display only the Alias column and sort the aliases in descending order:
+
+  <%= config.bin %> <%= command.id %> --sort "-Alias" --columns "Alias"
 
 # flags.all.summary
 
-Show all environments, including inactive orgs.
+Show all environments, even inactive ones.
 
 # error.NoAuthsAvailable
 
 There are no authentications available.
 
 # error.NoResultsFound
 
-No results found
+No results found.

messages/open.md

@@ -6,23 +6,39 @@ Open an environment in your web browser.
 
 You can open the following types of environments in a web browser: scratch orgs, sandboxes, Dev Hubs, and production orgs.
 
-If you run the command without flags, it attempts to open your default environment in your default web browser.
+If you run the command without flags, it attempts to open your default environment in your default web browser. Run "sf env list" to view your default environment.
 
-# flags.path.summary
+Each of your environments is associated with an instance URL, such as https://login.salesforce.com. To open a specific web page, specify the portion of the URL after "<URL>/" with the --path flag, such as /apex/YourPage to open a Visualforce page.
+
+# examples
+
+- Open your default environment:
+
+  <%= config.bin %> <%= command.id %>
+
+- Open the Visualforce page /apex/StartHere in a scratch org with alias test-org:
 
-Path to append to the end of the open URL.
+  <%= config.bin %> <%= command.id %> --target-env test-org --path /apex/StartHere
 
-# flags.path.description
+- View the URL but don't launch it in a browser:
+
+  <%= config.bin %> <%= command.id %> --target-env test-org --path /apex/StartHere --url-only
+
+- Open the environment in the Google Chrome browser:
+
+  <%= config.bin %> <%= command.id %> --target-env test-org --path /apex/StartHere --browser chrome
+
+# flags.path.summary
 
-Each of your environments is associated with an instance URL, such as https://<mydomian>.my.salesforce.com. To open a specific web page at that URL, specify the portion of the URL after "<URL>/" with the --path flag, such as /apex/YourPage to open a Visualforce page.
+Path to append to the end of the login URL.
 
 # flags.url-only.summary
 
 Display the URL, but don’t launch it in a browser.
 
 # flags.target-env.summary
 
-Environment name or alias to open.
+Environment login user or alias to open.
 
 # flags.target-env.description
 
@@ -36,40 +52,20 @@ Browser in which to open the environment.
 
 # flags.browser.description
 
-Specify a browser by its app name according to your operating system. For example, Chrome’s app name is "google chrome" on macOS, "google-chrome" on Linux and "chrome" on Windows. So to open an environment in Chrome on macOS, specify --browser "google chrome". If you don’t specify --browser, the environment opens in your default browser.
-
-For convenience, "chrome", "firefox", and "edge" are mapped to the OS specific app name.
-
-# examples
-
-- To open your default environment, run the command without flags:
-
-  <%= config.bin %> env open
-
-- This example opens the Visualforce page /apex/StartHere in a scratch org with alias "test-org":
-
-  <%= config.bin %> env open --target-env test-org --path /apex/StartHere
-
-- If you want to view the URL for the preceding command, but not launch it in a browser:
-
-  <%= config.bin %> env open --target-env test-org --path /apex/StartHere --url-only
-
-- The preceding examples open the environment in your default web browser. To use a different browser, set the --browser flag to its OS-specific name. For example, to use Chrome on macOS:
-
-  <%= config.bin %> env open --target-env test-org --path /apex/StartHere --browser "google chrome"
+You can specify that the environment open in one of the following browsers: Firefox, Safari, Google Chrome, or Windows Edge. If you don’t specify --browser, the environment opens in your default browser.
 
 # error.NoDefaultEnv
 
-No default target-env found. Use --target-env to specify which env to open.
+No default target-env found. Use --target-env to specify the environment to open.
 
 # error.NoEnvFound
 
 No environment found for %s.
 
 # error.EnvironmentNotSupported
 
-The environment %s doesn't support bring opened.
+The environment %s doesn't support being opened.
 
 # error.ApplicationNotFound
 
-Unable to find application named %s.
+Can't find application named %s.

src/commands/env/open.ts

@@ -27,7 +27,6 @@ export default class EnvOpen extends Command {
     path: Flags.string({
       char: 'p',
       summary: messages.getMessage('flags.path.summary'),
-      description: messages.getMessage('flags.path.description'),
     }),
     'url-only': Flags.boolean({
       char: 'r',