sfvm
)
Salesforce CLI Version manager (
- Salesforce CLI Version manager (
sfvm
) - What it is
- How to get it
- Disclaimers
- Getting started
- How it works
- Examples
- or
- Usage
- Commands
What it is
sfvm
is a "version manager" for the Salesforce CLI (sfdx). If you've ever heard of nvm
, pyenv
, mvnvm
, jabba
, etc, then this concept should be familiar. It is written using oclif, and was created to help accelerate the development and testing process in delivering the v7 update of the sfdx
CLI.
Have you ever been in one of these scenarios?
- You wish you could easily run multiple versions of the CLI to diagnose issues.
- You wish you could easily maintain multiple plugin configurations:
- one for linking your development plugins
- one for testing specific versions of installed plugins
- one for testing with no plugins
- You wish you could keep from mixing your main
.sfdx
configuration with test cases used to reproduce bugs or customer issues. - You just updated
sfdx
but there was a regression. You want to easily revert to the previous version to unblock yourself. - You just want to know where the heck the CLI stores things on your computer.
sfvm
has solutions for all of these problems and more.
How to get it
$ npm install --global @salesforce/sfvm
Disclaimers
This is still in active development and subject to change. Issue reports and PRs welcome!
OS Support
Available on all platforms supported by sfdx
, but only well tested on Mac. For Linux and Windows, your mileage may vary. Backup your $HOME/.sfdx
config just in case :P
Getting started
Once installed, it will instruct you to add a new OS-specific directory to your PATH
, such as /Users/rbergman/.local/share/sfvm
.
You want to add this to your PATH
before wherever your installer version of sfdx
is located. On Mac and Linux, for example, make sure it comes before before /usr/local/bin
.
While it's still only available internally, you will also need to set the following environment variable:
export SFDX_S3_HOST=http://10.252.156.165:9000/sfdx/media/salesforce-cli
How it works
Versions managed by sfvm
are given an isolated home directory, independent of your user home directory. This allows each version to have it's own isolated CLI data, updates, caches, and configuration.
sfvm
provides several tools to manage these independent CLI configurations without touching your global configuration, but while allowing you to link or copy the global configuration to each managed version (or allow the managed version to have a clean environment of its own).
Version resolution
Versions are often required or optional arguments to sfvm
commands. Versions may be whole or partial values. Partial version disambiguation is made by selecting the most recent matching version first.
Some commands will use the currently selected version if one is not explicitly given. Some commands also accept global
to refer to whatever version of sfdx
is globally resolvable in your path that does not match sfvm
's own sfdx
proxy script.
Installation
By default, installing a new version will automatically create a symlink to your $HOME
/.sfdx` directory. You can disable that if desired, or copy a configuration instead of linking to one. You can also easily change the configuration after installation.
By adding the -p
flag to an install, the currently installed (but not linked) plugins in whatever version is currently in use will be installed after the CLI. You can install a specific set of plugins by specifying a version like so: -P <version>
. For example, use -P global
to copy your global plugin configuration after installation.
More features are planned for plugin management, but they aren't yet available.
Autoupdates
By default, the autoupdater is disabled for managed versions. You can still manually update them using the usual update syntax: sfvm update
.
Destructive operations
Destructive commands require the use of the --force
(-f
) flag. With the exception of revert
, these do not work on the global installation for safety reasons.
Examples
Install the latest version
$ sfvm install latest
Install a specific version
$ sfvm install 7.1.4
Install the latest version of v6
$ sfvm install 6
Switch to using the latest v7
$ sfvm use 7
Switch to using the the version you have globally installed
$ sfvm use global
# or
$ sfvm unload
Uninstall the latest v7 you have installed
$ sfvm uninstall 7 --force
Show details about the currently selected version
$ sfvm show
Show details about the global version
$ sfvm show global
List all installed versions
$ sfvm list
List all installed versions, including update info (slower)
$ sfvm list --updates
Remove an update from the latest v7 version
$ sfvm revert 7 --force
Remove an update from your global install
$ sfvm revert global --force
Wipe the configuration for the current version
$ sfvm config:reset --force
Re-link the configuration for the current version
$ sfvm config:link --force
List contents of the current version's home directory
$ ls -a $(sfvm property home)
Wipe caches for the current version
$ rm -rf $(sfvm property caches)
Don't do this on Windows or you will remove more than just your caches!
Usage
$ npm install -g @salesforce/sfvm
$ sfvm COMMAND
running command...
$ sfvm (-v|--version|version)
@salesforce/sfvm/0.53.0 linux-x64 node-v12.20.1
$ sfvm --help [COMMAND]
USAGE
$ sfvm COMMAND
...
Commands
sfvm channels
sfvm clean [VERSION]
sfvm config:copy [VERSION]
sfvm config:link [VERSION]
sfvm config:reset [VERSION]
sfvm current
sfvm exec VERSION
sfvm help [COMMAND]
sfvm install VERSION [CHANNEL]
sfvm list
sfvm plugins
sfvm plugins:install PLUGIN...
sfvm plugins:link PLUGIN
sfvm plugins:uninstall PLUGIN...
sfvm plugins:update
sfvm property PROPERTY [VERSION]
sfvm releases [CHANNEL]
sfvm revert [VERSION]
sfvm run
sfvm show [VERSION]
sfvm uninstall VERSION
sfvm unload
sfvm use VERSION
sfvm which COMMAND
sfvm zero
sfvm channels
lists available channels
USAGE
$ sfvm channels
ALIASES
$ sfvm all
$ sfvm ls-remotes
EXAMPLE
$ sfvm releases
release
stable
See code: src/commands/channels.ts
sfvm clean [VERSION]
resets a managed installation to pristine condition
USAGE
$ sfvm clean [VERSION]
ARGUMENTS
VERSION some or all of the target sfdx version
OPTIONS
-c, --copy copies your home sfdx config after cleaning
-f, --copyfrom=copyfrom copies a specified sfdx config after cleaning
-f, --force force the clean operation
-l, --link links your home sfdx config after cleaning
-w, --linkwith=linkwith links a specified sfdx config after cleaning
ALIASES
$ sfvm reset
$ sfvm burninate
EXAMPLE
$ sfvm clean -f
Cleaning home dir for version 7.0.0-52-df92f81459... done.
See code: src/commands/clean.ts
sfvm config:copy [VERSION]
copies an sfdx config to a managed installation
USAGE
$ sfvm config:copy [VERSION]
ARGUMENTS
VERSION some or all of the target sfdx version
OPTIONS
-c, --config=config path to any sfdx config dir
-f, --force force the link operation
EXAMPLE
$ sfvm config:copy
Copying sfdx configuration to version 7.0.0-52-df92f81459... done.
See code: src/commands/config/copy.ts
sfvm config:link [VERSION]
links an sfdx config to a managed installation
USAGE
$ sfvm config:link [VERSION]
ARGUMENTS
VERSION some or all of the target sfdx version
OPTIONS
-c, --config=config path to any sfdx config dir
-f, --force force the copy operation
EXAMPLE
$ sfvm config:link
Linking sfdx configuration to version 7.0.0-52-df92f81459... done.
See code: src/commands/config/link.ts
sfvm config:reset [VERSION]
resets an sfdx config for a managed installation
USAGE
$ sfvm config:reset [VERSION]
ARGUMENTS
VERSION some or all of the target sfdx version
OPTIONS
-f, --force force the reset operation
EXAMPLE
$ sfvm config:reset
Resetting sfdx configuration for version 7.0.0-52-df92f81459... done.
See code: src/commands/config/reset.ts
sfvm current
displays the current version in use, if any
USAGE
$ sfvm current
ALIASES
$ sfvm used
EXAMPLE
$ sfvm current
7.0.0-52-df92f81459 (managed)
See code: src/commands/current.ts
sfvm exec VERSION
executes an sfdx command using the specified version
USAGE
$ sfvm exec VERSION
ARGUMENTS
VERSION some or all of the target sfdx version, or "global" for an installer version
EXAMPLE
$ sfvm exec 7 [sfdx command and arguments]
[sfdx command output]
See code: src/commands/exec.ts
sfvm help [COMMAND]
display help for sfvm
USAGE
$ sfvm help [COMMAND]
ARGUMENTS
COMMAND command to show help for
OPTIONS
--all see all commands in CLI
See code: @oclif/plugin-help
sfvm install VERSION [CHANNEL]
installs a release given a version and optional channel
USAGE
$ sfvm install VERSION [CHANNEL]
ARGUMENTS
VERSION some or all of the target sfdx version, or "latest" for the most recent release
CHANNEL [default: stable] the channel from which to install
OPTIONS
-C, --copyfrom=copyfrom copies a specified sfdx config after installing
-L, --linkwith=linkwith links a specified sfdx config after installing
-P, --pluginsfrom=pluginsfrom also installs plugins present in the specified version, if any
-c, --copy copies your home sfdx config after installing
-l, --[no-]link links your home sfdx config after installing
-p, --plugins also installs plugins present in the current version, if any
-u, --[no-]use switches to the new version once installed
ALIASES
$ sfvm i
EXAMPLE
$ sfvm install latest
Installing 7.0.0-52-df92f81459... done.
See code: src/commands/install.ts
sfvm list
lists all installed, managed versions
USAGE
$ sfvm list
OPTIONS
-s, --simple only emit versions
-u, --updates include updated versions (slower)
--[no-]global include global version
--[no-]managed include managed versions
ALIASES
$ sfvm ls
$ sfvm installed
EXAMPLE
$ sfvm list --updates
Type Version Updated
global 7.1.3 [↑ 7.1.4-79f97a7df8]
managed 6.56.0-e3fd846a1f
✓ managed 7.1.3-ece97e8491
See code: src/commands/list.ts
sfvm plugins
list installed plugins
USAGE
$ sfvm plugins
OPTIONS
--core show core plugins
EXAMPLE
$ sfvm plugins
See code: @oclif/plugin-plugins
sfvm plugins:install PLUGIN...
installs a plugin into the CLI
USAGE
$ sfvm plugins:install PLUGIN...
ARGUMENTS
PLUGIN plugin to install
OPTIONS
-f, --force yarn install with force flag
-h, --help show CLI help
-v, --verbose
DESCRIPTION
Can be installed from npm or a git url.
Installation of a user-installed plugin will override a core plugin.
e.g. If you have a core plugin that has a 'hello' command, installing a user-installed plugin with a 'hello' command
will override the core plugin implementation. This is useful if a user needs to update core plugin functionality in
the CLI without the need to patch and update the whole CLI.
ALIASES
$ sfvm plugins:add
EXAMPLES
$ sfvm plugins:install myplugin
$ sfvm plugins:install https://github.com/someuser/someplugin
$ sfvm plugins:install someuser/someplugin
See code: @oclif/plugin-plugins
sfvm plugins:link PLUGIN
links a plugin into the CLI for development
USAGE
$ sfvm plugins:link PLUGIN
ARGUMENTS
PATH [default: .] path to plugin
OPTIONS
-h, --help show CLI help
-v, --verbose
DESCRIPTION
Installation of a linked plugin will override a user-installed or core plugin.
e.g. If you have a user-installed or core plugin that has a 'hello' command, installing a linked plugin with a 'hello'
command will override the user-installed or core plugin implementation. This is useful for development work.
EXAMPLE
$ sfvm plugins:link myplugin
See code: @oclif/plugin-plugins
sfvm plugins:uninstall PLUGIN...
removes a plugin from the CLI
USAGE
$ sfvm plugins:uninstall PLUGIN...
ARGUMENTS
PLUGIN plugin to uninstall
OPTIONS
-h, --help show CLI help
-v, --verbose
ALIASES
$ sfvm plugins:unlink
$ sfvm plugins:remove
See code: @oclif/plugin-plugins
sfvm plugins:update
update installed plugins
USAGE
$ sfvm plugins:update
OPTIONS
-h, --help show CLI help
-v, --verbose
See code: @oclif/plugin-plugins
sfvm property PROPERTY [VERSION]
displays a single property of the current or given version
USAGE
$ sfvm property PROPERTY [VERSION]
ARGUMENTS
PROPERTY (dir|root|home|sfdx|bin|data|caches|config|client) the name of the property to display
VERSION some or all of the target sfdx version, or "global" for an installer version
ALIASES
$ sfvm prop
$ sfvm p
EXAMPLE
$ sfvm property dir
TODO
See code: src/commands/property.ts
sfvm releases [CHANNEL]
lists available releases by channel
USAGE
$ sfvm releases [CHANNEL]
ARGUMENTS
CHANNEL [default: stable] the channel for which to list available releases
ALIASES
$ sfvm all
$ sfvm ls-remotes
EXAMPLE
$ sfvm releases
7.0.0-42-8ec08ef076
7.0.0-44-903ac98d08
7.0.0-45-3f6613da57
7.0.0-46-ae2d91ab64
7.0.0-47-5ada94ee67
7.0.0-50-bc86d8cf05
7.0.0-52-df92f81459
See code: src/commands/releases.ts
sfvm revert [VERSION]
removes any CLI updates from your user home dir
USAGE
$ sfvm revert [VERSION]
ARGUMENTS
VERSION some or all of the target sfdx version, or "global" for an installer version
OPTIONS
-f, --force force the revert operation
EXAMPLE
$ sfvm revert
Reverting update at /Users/username/.local/share/sfdx/client... done.
See code: src/commands/revert.ts
sfvm run
runs an sfdx command using the current version, if any
USAGE
$ sfvm run
EXAMPLE
$ sfvm run [sfdx command and arguments]
[sfdx command output]
See code: src/commands/run.ts
sfvm show [VERSION]
shows details of the current or given version
USAGE
$ sfvm show [VERSION]
ARGUMENTS
VERSION some or all of the target sfdx version, or "global" for an installer version
OPTIONS
-p, --property=(dir|root|home|sfdx|bin|data|caches|config|client) only emit the value of the given property
ALIASES
$ sfvm view
EXAMPLE
$ sfvm show
version: 7.0.0-67-864c2b32ad
installed: 3/21/2019, 6:00:13 PM
type: managed root dir: ~/.sfvm/sfdx-cli-v7.0.0-67-864c2b32ad-darwin-x64
home dir: ~/.sfvm/sfdx-cli-v7.0.0-67-864c2b32ad-darwin-x64/home
caches dir: ~/.sfvm/sfdx-cli-v7.0.0-67-864c2b32ad-darwin-x64/home/Library/Caches/sfdx
client dir: ~/.sfvm/sfdx-cli-v7.0.0-67-864c2b32ad-darwin-x64/home/.local/share/sfdx/client
config dir: ~/.sfvm/sfdx-cli-v7.0.0-67-864c2b32ad-darwin-x64/home/.sfdx
data dir: ~/.sfvm/sfdx-cli-v7.0.0-67-864c2b32ad-darwin-x64/home/.local/share/sfdx
bin path: ~/.sfvm/sfdx-cli-v7.0.0-67-864c2b32ad-darwin-x64/bin/sfdx
See code: src/commands/show.ts
sfvm uninstall VERSION
removes a managed installation
USAGE
$ sfvm uninstall VERSION
ARGUMENTS
VERSION some or all of the target sfdx version
OPTIONS
-f, --force force the uninstall operation
ALIASES
$ sfvm rm
$ sfvm remove
EXAMPLE
$ sfvm uninstall 7 -f
Uninstalling version 7.0.0-52-df92f81459... done.
See code: src/commands/uninstall.ts
sfvm unload
removes the managed sfdx
command from your PATH
USAGE
$ sfvm unload
EXAMPLE
$ sfvm unload
Removed managed `sfdx` command. Run `sfvm use <version>` to restore it.
See code: src/commands/unload.ts
sfvm use VERSION
switches the current sfdx to the given version
USAGE
$ sfvm use VERSION
ARGUMENTS
VERSION some or all of the target sfdx version
ALIASES
$ sfvm load
EXAMPLE
$ sfvm use 7
Switched sfdx to version 7.0.0-52-df92f81459.
See code: src/commands/use.ts
sfvm which COMMAND
show which plugin a command is in
USAGE
$ sfvm which COMMAND
See code: @oclif/plugin-which
sfvm zero
uninstalls all managed versions
USAGE
$ sfvm zero
OPTIONS
-f, --force force the zero operation
ALIASES
$ sfvm nuke
$ sfvm purge
$ sfvm uninstall-all
EXAMPLE
$ sfvm zero -f
Uninstalling all managed versions... BOOM!
See code: src/commands/zero.ts