@salesforce/sfvm

The Salesforce CLI version manager.

Usage no npm install needed!

<script type="module">
  import salesforceSfvm from 'https://cdn.skypack.dev/@salesforce/sfvm';
</script>

README

Salesforce CLI Version manager (sfvm)

oclif Version Downloads/week License

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 darwin-x64 node-v10.14.1
$ sfvm --help [COMMAND]
USAGE
  $ sfvm COMMAND
...

Commands

sfvm channels

lists available channels

USAGE
  $ sfvm channels

ALIASES
  $ sfvm all
  $ sfvm ls-remotes

EXAMPLE
  $ sfvm releases
  release
  stable

See code: lib/commands/channels.js

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: lib/commands/clean.js

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: lib/commands/config/copy.js

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: lib/commands/config/link.js

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: lib/commands/config/reset.js

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: lib/commands/current.js

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: lib/commands/exec.js

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: lib/commands/install.js

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: lib/commands/list.js

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: lib/commands/property.js

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: lib/commands/releases.js

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: lib/commands/revert.js

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: lib/commands/run.js

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: lib/commands/show.js

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: lib/commands/uninstall.js

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: lib/commands/unload.js

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: lib/commands/use.js

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: lib/commands/zero.js