24 Feb Force CLI Introduction
A COMMAND LINE INTERFACE TO FORCE.COM!
The Force.com CLI allows you to work with Force.com data directly from the command line. You can browse and Create Force.com objects, view, edit, create, and delete records, execute APEX code and SOQL queries, and more.
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.
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
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:
Usage: force 
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:
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.
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:
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
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
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.
“Know more about Salesforce Consulting at Techila”