Force CLI Part 1 - Getting Started
In one of my earlier blog posts around Lightning Components deployment (Deploying Lightning Components - Go Big or Go Missing) I made a passing reference to the fact that I use the Force CLI for automated deployments. A few people contacted me after this and said that while they were vaguely aware of the CLI, they’d never spent any time with it, so I decided to show this unsung hero some love with a series of blog posts.
A Command Line Interface to Force.com!
As someone who spent 20 or so years developing on Unix and Linux, I’m pretty comfortable with command line tools, and in many cases (resolving git conflicts!) I actually prefer them to a GUI. So when the CLI was released at Dreamforce 13, I couldn’t wait to get hold of it.
The first thing to do is download the CLI - you can do this from the home page at : https://force-cli.heroku.com/ - this has pre-built binaries for Mac OSX, Windows and Debian/Ubuntu. I’m a Mac user so any instructions/examples are based on OSX.
Clicking on the ‘Download for Mac OS X 64’ link downloads the ‘force’ application to my ‘Downloads’ directory. I clear this directory out regularly (yeah right, regularly being when I run out of disk space) so the first thing I need to do is move this to a safe place. I create a tools directory underneath my home directory and drag the file into that:
Trying it Out
Via the terminal (If you aren’t familiar with the terminal then I’d recommend following this tutorial from MacWorld) I can then test out whether the application works correctly
> cd ~/tools > ./force
and of course it doesn’t:
-bash: ./force: Permission denied
This is because files are downloaded without execute permission. To rectify this, execute:
> chmod +x ./force
Executing again now shows the (long) list of available options:
> ./force Usage: force  Available commands: login force login [-i=] [ ] logout Log out from force.com logins List force.com logins used active Show or set the active force.com account whoami Show information about the active account describe Describe the object or list of available objects sobject Manage standard & custom objects bigobject Manage big objects field Manage sobject fields record Create, modify, or view records bulk Load csv file use Bulk API fetch Export specified artifact(s) to a local directory import Import metadata from a local directory export Export metadata to a local directory query Execute a SOQL statement apex Execute anonymous Apex code trace Manage trace flags log Fetch debug logs eventlogfile List and fetch event log file oauth Manage ConnectedApp credentials test Run apex tests security Displays the OLS and FLS for a give SObject version Display current version update Update to the latest version push Deploy artifact from a local directory aura force aura push -resourcepath= password See password status or reset password notify Should notifications be used limits Display current limits help Show this help datapipe Manage DataPipes Run 'force help [command]' for details.
Access All Areas
By executing ‘./force’ I’m asking the operating system to execute the script named force in the local directory (the ./ part). This is going to be pretty unwieldy if I have to provide the location each time, so the last thing to do to get set up is to add the tools directory to my path - if you chose a different directory name to tools, just alter the following commands to use your name.
The default shell on OSX is bash (bourne again shell, as it was a replacement for the venerable Bourne shell - this is both a blog post and a history lesson!). When you login (or open a new terminal window on Mac OSX) the bash shell executes the .bash_profile script from your home directory, if one exists, so this is the easiest way to update your path.
Using your favourite editor (mine is vim, but that’s a bit like saying the developer console is your favourite IDE), open the .bash_profile file, from your home directory (/Users/<yourname>), or create one if it isn’t already there and add the following at the bottom:
Save the file, then execute the .bash_profile script to update your current context:
> . ~/.bash_profile
Next, change to your home directory and execute the force command without a path to check all is good:
> cd > force
and once again you should see the full output.
Congratulations - now you can run the force executable from anywhere without worrying about where it has been installed.
Now that everything is set up, you can login to Salesforce via the CLI by executing :
> force login
This opens up a browser window for you to enter your credentials:
and authorise access via oauth:
(Note that this process involves a Heroku app communicating with a local web server to return the oauth token to the command line, which may be problematic if you are behind a firewall that you can’t configure or using NAT. See the end of this post for an alternative, non-oauth approach).
This is the number 1 reason why I use the Force CLI for deployments - it removes the need to store usernames and passwords on disk, which has always been my issue with the Force Migration Tool.
If you have a number of orgs its quite easy to forget which one you have logged into, which is where the logins command comes in handy, as it will show you all the orgs that you have logged in to and which login is currently active:
> force logins
If you can’t use the oauth mechanism described above, you can always fall back on supplying the username and password to the CLI via the following command:
> force login -u=<username> -p=<password>
While this is slightly better than storing credentials on disk, it does mean that if someone were to compromise your machine they’d be able to see the username and password in your command history. For example, after executing:
> force login -email@example.com -p=Faking1t
If I then look at my command history
This shows the credentials:
685 force login -firstname.lastname@example.org -p=Faking1t 686 history
Luckily I can clean up afterwards and remove the command from my history, First delete the entry:
> history -d 685
then write the history to disk:
> history -w
viewing the history again shows that entry 685 has been replaced with the entry that was at 686:
Logging in to a Sandbox
The logins command supports production orgs, sandboxes and custom domains. To view the options, for this or any other command, execute ‘force <command> -help’:
> force login -help
Usage: force login
force login [-i=<instance>] [<-u=username> <-p=password> <-v=apiversion]
force login -i=test
force login -u=un -p=pw
force login -i=test -u=un -p=pw
force login -i=na1-blitz01.soma.salesforce.com -u=un -p=pw
That’s all Folks
This concludes getting started with the Force CLI. Assuming all went well you now have the CLI installed, in your path and you’ve been able to login to an org. In the next post I’ll take a look at interacting with your metadata.