commands for sf plugin development
npm install @salesforce/plugin-dev  
- plugin-dev
- Install
- Usage
- Generate a new sf plugin
- Generate a new sf command in your plugin
- Generate a hook that will be used for existing sf commands
- Issues
- Contributing
- CLA
- Build
- Commands
- sf dev generate command
- sf dev generate flag
- sf dev generate hook
- sf dev generate library
- sf dev generate plugin
- sf dev hook HOOK
``bash`
sf plugins install @salesforce/plugin-dev@x.y.z
`
sf dev generate plugin
This will generate a new sf plugin based on our plugin template.
`
sf dev generate command --name create:awesome:stuff
This will generate the following:
- a new sf command.nut
- a markdown file that will be used for all your command's message (e.g. command summary, flag descriptions, examples, error messages, etc...)
- a test file (See docs for Non-Unit-Tests)--unit
- a unit test file (if the flag is provided)
`
sf dev generate hook --event sf:env:list
This will generate a sf hook that can be used to extend the functionality of an existing sf command. For example, if you want a new environment type to be shown in sf env list.
Please report any issues at https://github.com/forcedotcom/cli/issues
1. Please read our Code of Conduct
2. Create a new issue before starting your project so that we can keep track of
what you are trying to add/fix. That way, we can also offer suggestions or
let you know if there is already an effort in progress.
3. Fork this repository.
4. Build the plugin locally
5. Create a _topic_ branch in your fork. Note, this step is recommended but technically not required if contributing using a fork.
6. Edit the code in your fork.
7. Write appropriate tests for your changes. Try to achieve at least 95% code coverage on any new code. No pull request will be accepted without unit tests.
8. Sign CLA (see CLA below).
9. Send us a pull request when you are done. We'll review your code, suggest any needed changes, and merge it in.
External contributors will be required to sign a Contributor's License
Agreement. You can do so by going to https://cla.salesforce.com/sign-cla.
To build the plugin locally, make sure to have yarn installed and run the following commands:
`bashClone the repository
git clone git@github.com:salesforcecli/plugin-dev
To use your plugin, run using the local
or ./bin/dev.cmd file.`bash
Run using local run file.
./bin/dev hello world
`There should be no differences when running via the Salesforce CLI or using the local run file. However, it can be useful to link the plugin to do some additional testing or run your commands from anywhere on your machine.
bash
Link your plugin to the sf cli
sf plugins link .
To verify
sf plugins
`Commands
-
-
-
-
- Audit messages in a plugin's messages directory to locate unused messages and missing messages that have references in source code.
USAGE
$ sf dev audit messages [--json] [--flags-dir ] [-p ] [-m ] [-s ]FLAGS
-m, --messages-dir= [default: messages] Directory that contains the plugin's message files.
-p, --project-dir= [default: .] Location of the project where messages are to be audited.
-s, --source-dir= [default: src] Directory that contains the plugin's source code.
GLOBAL FLAGS
--flags-dir= Import flag values from a directory.
--json Format output as json.
EXAMPLES
Audit messages using default directories:
$ sf dev audit messages
Audit messages in the "messages" directory in the current working directory; the plugin's source directory is in
"src":
$ sf dev audit messages --messages-dir ./messages --source-dir ./src
FLAG DESCRIPTIONS
-m, --messages-dir= Directory that contains the plugin's message files.
The default is the "messages" directory in the current working directory.
-s, --source-dir= Directory that contains the plugin's source code.
The default is the "src" directory in the current working directory.
_See code: src/commands/dev/audit/messages.ts_
Convert a .json messages file into Markdown.
USAGE
$ sf dev convert messages -f [--json] [--flags-dir ] [-p ]FLAGS
-f, --file-name=... (required) Filename to convert.
-p, --project-dir= [default: .] Location of the project whose messages are to be converted.
GLOBAL FLAGS
--flags-dir= Import flag values from a directory.
--json Format output as json.
DESCRIPTION
Convert a .json messages file into Markdown.
Preserves the filename and the original messages file, then creates a new file with the Markdown extension and
standard headers for the command and flag summaries, descriptions, and so on. After you review the new Markdown file,
delete the old .json file.
EXAMPLES
Convert the my-command.json message file into my-command.md with the standard messages headers:
$ sf dev convert messages --filename my-command.json
Similar to previous example, but specify the plugin project directory:
$ sf dev convert messages --project-dir ./path/to/plugin --filename my-command.json
_See code: src/commands/dev/convert/messages.ts_
Convert a script file that contains deprecated sfdx-style commands to use the new sf-style commands instead.
USAGE
$ sf dev convert script -s [--json] [--flags-dir ]FLAGS
-s, --script= (required) Filepath to the script you want to convert.
GLOBAL FLAGS
--flags-dir= Import flag values from a directory.
--json Format output as json.
DESCRIPTION
Convert a script file that contains deprecated sfdx-style commands to use the new sf-style commands instead.
Important: Use this command only to get started on the sfdx->sf script migration. We don't guarantee that the new
sf-style command replacements work correctly or as you expect. You must test, and probably update, the new script
before putting it into production. We also don't guarantee that the JSON results are the same as before.
This command can convert a large part of your script, but possibly not all. There are some sfdx-style commands that
don't have an obvious sf-style equivalent. In this case, this command doesn't replace the sfdx-style command but
instead adds a comment to remind you that you must convert it manually. See the Salesforce CLI Command Reference for
migration information about each deprecated sfdx-style command:
https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/cli_reference.htm.
This command is interactive; as it scans your script, it prompts you when it finds an sfdx-style command or flag and
asks if you want to convert it to the displayed suggestion. The command doesn't update the script file directly;
rather, it creates a new file whose name is the original name but with "-converted" appended to it. The script
replaces all instances of "sfdx" with "sf". For each prompt you answer "y" to, the command replaces the sfdx-style
names with their equivalent sf-style ones. For example, "sfdx force:apex:execute --targetusername myscratch" is
replaced with "sf apex run --target-org myscratch".
EXAMPLES
Convert the YAML file called "myScript.yml" located in the current directory; the new file that contains the
replacements is called "myScript-converted.yml":
$ sf dev convert script --script ./myScript.yml
_See code: src/commands/dev/convert/script.ts_
Generate a new sf command.
USAGE
$ sf dev generate command -n [--flags-dir ] [--force] [--dry-run] [--nuts] [--unit]FLAGS
-n, --name= (required) Name of the new command. Use colons to separate the topic and command names.
--dry-run Display the changes that would be made without writing them to disk.
--force Overwrite existing files.
--[no-]nuts Generate a NUT test file for the command.
--[no-]unit Generate a unit test file for the command.
GLOBAL FLAGS
--flags-dir= Import flag values from a directory.
DESCRIPTION
Generate a new sf command.
You must run this command from within a plugin directory, such as the directory created with the "sf dev generate
plugin" command.
The command generates basic source files, messages (\*.md), and test files for your new command. The Typescript files
contain import statements for the minimum required Salesforce libraries, and scaffold some basic code. The new type
names come from the value you passed to the --name flag.
The command updates the package.json file, so if it detects conflicts with the existing file, you're prompted whether
you want to overwrite the file. There are a number of package.json updates required for a new command, so we recommend
you answer "y" so the command takes care of them all. If you answer "n", you must update the package.json file
manually.
EXAMPLES
Generate the files for a new "sf my exciting command":
$ sf dev generate command --name my:exciting:command
_See code: src/commands/dev/generate/command.ts_
Generate a flag for an existing command.
USAGE
$ sf dev generate flag [--flags-dir ] [-d]FLAGS
-d, --dry-run Print new flag code instead of adding it to the command file.
GLOBAL FLAGS
--flags-dir= Import flag values from a directory.
DESCRIPTION
Generate a flag for an existing command.
You must run this command from within a plugin directory, such as the directory created with the "sf dev generate
plugin" command.
This command is interactive. It first discovers all the commands currently implemented in the plugin, and asks you
which you want to create a new flag for. It then prompts for other flag properties, such as its long name, optional
short name, type, whether it's required, and so on. Long flag names must be kebab-case and not camelCase. The command
doesn't let you use an existing long or short flag name. When the command completes, the Typescript file for the
command is updated with the code for the new flag.
Use the --dry-run flag to review new code for the command file without actually updating it.
EXAMPLES
Generate a new flag and update the command file:
$ sf dev generate flag
Don't actually update the command file, just view the generated code:
$ sf dev generate flag --dry-run
_See code: src/commands/dev/generate/flag.ts_
Generate a new sf plugin.
USAGE
$ sf dev generate plugin [--flags-dir ] [--dry-run]FLAGS
--dry-run Display the changes that would be made without writing them to disk.
GLOBAL FLAGS
--flags-dir= Import flag values from a directory.
DESCRIPTION
Generate a new sf plugin.
This command is interactive. You're prompted for information to populate your new plugin, such as its name,
description, author, and percentage of code coverage you want. The command clones the
'salesforcecli/plugin-template-sf' GitHub repository, installs the plug-in's npm package dependencies using yarn
install, and updates the package properties.
When the command completes, your new plugin contains the source, message, and test files for a sample "sf hello world"
command.
ALIASES
$ sf plugins generate
EXAMPLES
$ sf dev generate plugin
_See code: src/commands/dev/generate/plugin.ts_