Merge pull request #612 from salesforcecli/jshackell/messages

fix: edit messages for sf-ized list metadata commands

Author: mshanemc

messages/list.metadata.md

@@ -1,67 +1,47 @@
 # description
 
-This command is useful when you want to identify individual components in your manifest file or if you want a high-level
-view of particular components in your organization. For example, you could use this target to return a list of names of
-all Layout components in your org, then use this information in a retrieve operation that returns a subset of these
-components.
+Use this command to identify individual components in your manifest file or if you want a high-level view of particular metadata types in your org. For example, you can use this command to return a list of names of all the CustomObject or Layout components in your org, then use this information in a retrieve command that returns a subset of these components.
+
+The username that you use to connect to the org must have the Modify All Data or Modify Metadata Through Metadata API Functions permission.
 
 # summary
 
-display properties of metadata components of a specified type
+List the metadata components and properties of a specified type.
 
 # examples
 
-- $ <%= config.bin %> <%= command.id %> -m CustomObject
-
-- $ <%= config.bin %> <%= command.id %> -m CustomObject -a 43.0
-
-- $ <%= config.bin %> <%= command.id %> -m CustomObject -o [email protected]
-
-- $ <%= config.bin %> <%= command.id %> -m CustomObject -f /path/to/outputfilename.txt
-
-- $ <%= config.bin %> <%= command.id %> -m Dashboard --folder foldername
-
-- $ <%= config.bin %> <%= command.id %> -m Dashboard --folder foldername -a 43.0
-
-- $ <%= config.bin %> <%= command.id %> -m Dashboard --folder foldername -o [email protected]
-
-- $ <%= config.bin %> <%= command.id %> -m Dashboard --folder foldername -f /path/to/outputfilename.txt
-
-- $ <%= config.bin %> <%= command.id %> -m CustomObject -o [email protected] -f /path/to/outputfilename.txt
-
-# flags.api-version
+- List the CustomObject components, and their properties, in the org with alias "my-dev-org":
 
-API version to use
+  $ <%= config.bin %> <%= command.id %> --metadata-type CustomObject --target-org my-dev-org
 
-# flags.output-file
+- List the CustomObject components in your default org, write the output to the specified file, and use API version 57.0:
 
-path to the file where results are stored
+  $ <%= config.bin %> <%= command.id %> --metadata-type CustomObject --api-version 57.0 --output-file /path/to/outputfilename.txt
 
-# flags.metadatatype
+- List the Dashboard components in your default org that are contained in the "folderSales" folder, write the output to the specified file, and use API version 57.0:
 
-metadata type to be retrieved, such as CustomObject; metadata type value is case-sensitive
+  $ <%= config.bin %> <%= command.id %> --metadata-type Dashboard --folder folderSales --api-version 57.0 --output-file /path/to/outputfilename.txt
 
-# flags.folder
+# flags.api-version.summary
 
-folder associated with the component; required for components that use folders; folder names are case-sensitive
+API version to use; default is the most recent API version.
 
-# flagsLong.apiversion
+# flags.output-file.summary
 
-The API version to use. The default is the latest API version
+Pathname of the file in which to write the results.
 
-# flagsLong.output-file
+# flags.metadata-type.summary
 
-The path to the file where the results of the command are stored. The default output destination is the console.
+Metadata type to be retrieved, such as CustomObject; metadata type names are case-sensitive.
 
-# flagsLong.metadatatype
+# flags.folder.summary
 
-The metadata type to be retrieved, such as CustomObject or Report. The metadata type value is case-sensitive.
+Folder associated with the component; required for components that use folders; folder names are case-sensitive.
 
-# flagsLong.folder
+# flags.folder.description
 
-The folder associated with the component. This parameter is required for components that use folders, such as Dashboard,
-Document, EmailTemplate, or Report. The folder name value is case-sensitive.
+Examples of metadata types that use folders are Dashboard, Document, EmailTemplate, and Report.
 
 # noMatchingMetadata
 
-No metadata found for type: %s in org: %s
+No metadata found for type: %s in org: %s.

messages/metadata-types.md

@@ -1,47 +1,37 @@
 # description
 
-Use this information to identify the syntax needed for a <name> element in package.xml. The most recent API version is
-the default, or you can specify an older version.
+The information includes Apex classes and triggers, custom objects, custom fields on standard objects, tab sets that define an app, and many other metadata types. Use this information to identify the syntax needed for a <name> element in a manifest file (package.xml).
 
-The default target username is the admin user for the default scratch org. The username must have the Modify All Data
-permission or the Modify Metadata permission (Beta). For more information about permissions, see Salesforce Help.
+The username that you use to connect to the org must have the Modify All Data or Modify Metadata Through Metadata API Functions permission.
 
 # summary
 
-display details about the metadata types enabled for your org
+Display details about the metadata types that are enabled for your org.
 
 # examples
 
-- $ <%= config.bin %> <%= command.id %> -a 43.0
+- Display information about all known and enabled metadata types in the org with alias "my-dev-org" using API version 57.0:
 
-- $ <%= config.bin %> <%= command.id %> -o [email protected]
+  $ <%= config.bin %> <%= command.id %> --api-version 57.0 --target-org my-dev-org
 
-- $ <%= config.bin %> <%= command.id %> -f /path/to/outputfilename.txt
+- Display only the metadata types that aren't yet supported by Salesforce CLI in your default org and write the results to the specified file:
 
-- $ <%= config.bin %> <%= command.id %> -o [email protected] -f /path/to/outputfilename.txt
+  $ <%= config.bin %> <%= command.id %> --output-file /path/to/outputfilename.txt --filter-known
 
-# flags.api-version
+# flags.api-version.summary
 
-API version to use
+API version to use; default is the most recent API version.
 
-# flags.output-file
+# flags.output-file.summary
 
-path to the file where results are stored
+Pathname of the file in which to write the results.
 
-# flags.filterknown
+# flags.filter-known.summary
 
-filter metadata known by the CLI
-
-# flagsLong.apiversion
-
-The API version to use. The default is the latest API version
+Filter the known metadata types from the result to display only the types not yet fully supported by Salesforce CLI.
 
-# flagsLong.output-file
-
-The path to the file where the results of the command are stored. Directing the output to a file makes it easier to
-extract relevant information for your package.xml manifest file. The default output destination is the console.
+filter metadata known by the CLI
 
-# flagsLong.filterknown
+# flags.output-file.description
 
-Filters all the known metadata from the result such that all that is left are the types not yet fully supported by the
-CLI.
+Directing the output to a file makes it easier to extract relevant information for your package.xml manifest file. The default output destination is the terminal or command window console.

messages/open.md

@@ -4,14 +4,13 @@ Open your default scratch org, or another specified org, in a browser.
 
 # description
 
-To open a specific page, specify the portion of the URL after "https://MyDomainName.my.salesforce.com/" as the value for
-the --path flag. For example, specify "--path lightning" to open Lightning Experience, or specify "--path
-/apex/YourPage" to open a Visualforce page.
+To open a specific page, specify the portion of the URL after "https://MyDomainName.my.salesforce.com/" as the value for the --path flag. For example, specify "--path lightning" to open Lightning Experience, or specify "--path /apex/YourPage" to open a Visualforce page.
+
+Use the --source-file to open a Lightning Page from your local project in Lightning App Builder. Lightning page files have the suffix .flexipage-meta.xml, and are stored in the "flexipages" directory.
 
 To generate a URL but not launch it in your browser, specify --url-only.
 
-To open in a specific browser, use the --browser flag. Supported browsers are "chrome", "edge", and "firefox". If you
-don't specify --browser, the org opens in your default browser.
+To open in a specific browser, use the --browser flag. Supported browsers are "chrome", "edge", and "firefox". If you don't specify --browser, the org opens in your default browser.
 
 # examples
 
@@ -23,22 +22,21 @@ don't specify --browser, the org opens in your default browser.
 
   $ <%= config.bin %> <%= command.id %> --target-org MyTestOrg1 --browser firefox
 
-- Display the navigation URL for the Lightning Experience page for your default org, but don't open the page in a
-  browser:
+- Display the navigation URL for the Lightning Experience page for your default org, but don't open the page in a browser:
 
   $ <%= config.bin %> <%= command.id %> --url-only --path lightning
 
-- Open a specific ApexPage or Flexipage in the org using the --source-path flag
+- Open a local Lightning page in your default org's Lightning App Builder:
 
-  $ <%= config.bin %> <%= command.id %> --source-path <path to page>
+  $ <%= config.bin %> <%= command.id %> --source-path force-app/main/default/flexipages/Hello.flexipage-meta.xml
 
 # flags.browser.summary
 
 Browser where the org opens.
 
 # flags.source-file.summary
 
-Path to an ApexPage or FlexiPage to open in the browser.
+Path to an ApexPage or FlexiPage to open in Lightning App Builder.
 
 # flags.path.summary
 

src/commands/org/list/metadata-types.ts

@@ -23,23 +23,22 @@ export class ListMetadataTypes extends SfCommand<DescribeMetadataResult> {
     'api-version': Flags.orgApiVersion({
       aliases: ['apiversion', 'a'],
       deprecateAliases: true,
-      summary: messages.getMessage('flags.api-version'),
+      summary: messages.getMessage('flags.api-version.summary'),
     }),
     loglevel,
     'target-org': requiredOrgFlagWithDeprecations,
     'output-file': Flags.file({
       aliases: ['resultfile'],
       deprecateAliases: true,
       char: 'f',
-      summary: messages.getMessage('flags.output-file'),
-      description: messages.getMessage('flagsLong.output-file'),
+      summary: messages.getMessage('flags.output-file.summary'),
+      description: messages.getMessage('flags.output-file.description'),
     }),
     'filter-known': Flags.boolean({
       aliases: ['filterknown'],
       deprecateAliases: true,
       char: 'k',
-      summary: messages.getMessage('flags.filterknown'),
-      description: messages.getMessage('flagsLong.filterknown'),
+      summary: messages.getMessage('flags.filter-known.summary'),
       hidden: true,
     }),
   };

src/commands/org/list/metadata.ts

@@ -25,27 +25,26 @@ export class ListMetadata extends SfCommand<ListMetadataCommandResult> {
     'api-version': Flags.orgApiVersion({
       aliases: ['apiversion', 'a'],
       deprecateAliases: true,
-      summary: messages.getMessage('flags.api-version'),
+      summary: messages.getMessage('flags.api-version.summary'),
     }),
     loglevel,
     'target-org': requiredOrgFlagWithDeprecations,
     'output-file': Flags.file({
       aliases: ['resultfile'],
       deprecateAliases: true,
       char: 'f',
-      summary: messages.getMessage('flags.output-file'),
+      summary: messages.getMessage('flags.output-file.summary'),
     }),
     'metadata-type': Flags.string({
       aliases: ['metadatatype'],
       deprecateAliases: true,
       char: 'm',
-      summary: messages.getMessage('flags.metadatatype'),
-      description: messages.getMessage('flagsLong.metadatatype'),
+      summary: messages.getMessage('flags.metadata-type.summary'),
       required: true,
     }),
     folder: Flags.string({
-      summary: messages.getMessage('flags.folder'),
-      description: messages.getMessage('flagsLong.folder'),
+      summary: messages.getMessage('flags.folder.summary'),
+      description: messages.getMessage('flags.folder.description'),
     }),
   };