Salesforce CLI library for Ruby

This is a class library for introducing Salesforce CLI to Ruby scripting.
It is designed to be similar usability to the original command.
Currently only sf command is the target of development.

rubygems: rubygems.org/gems/sf_cli
official document: tmkw.github.io/sf_cli/

prerequisite

Salesforce CLI must be installed.
As of as of September in 2024, ver.2.56.7 is the development target.

install

Rubygem

the simplest way:

$ gem install sf_cli

Bundler

in Gemfile:

gem 'sf_cli'

then,

$ bundle install

Usage

Load module

require 'sf_cli'

sf.org.login_web

Get Salesforce Object schema

sf.sobject.describe :Account

Get a record

sf.data.get_record :Account, record_id: 'xxxxxxx'
sf.data.get_record :Account, where: {Name: 'Jonny B.Good', Country: 'USA'}

Execute SOQL

sf.data.query "SELECT Id, Name FROM Account LIMIT 1" # => [{Id: "abc", Name: "account name"}]

Create a record

sf.data.create_record :TheCustomObject__c, values: {Name: "John Smith", Age: 33}

Update a record

sf.data.update_record :Account, record_id: 'xxxxxxx', values: {Name: 'New Account Name'}
sf.data.update_record :Hoge__c, where: {Name: 'Jonny B.Good', Country: 'USA'}, values: {Phone: 'xxxxx', bar: 2000}

Delete a record

sf.data.delete_record :Hoge__c, record_id: 'xxxxxxx'
sf.data.delete_record :Hoge__c, where: {Name: 'Jonny B.Good', Country: 'USA'}

Using Bulk API 2.0

sf.data.upsert_bulk sobject: :TestCustomObject__c, file: 'upsert.csv', wait: 5  # waiting for 5 minutes at maximum

Run Apex

sf.apex.run file: 'path/to/file'
sf.apex.run file: StringIO.new("System.debug('Hello World')")

Object Model Support

With sf command:

rows = sf.data.query "SELECT Id, Name FROM Contact WHERE Name = 'Akin Kristen'", model_class: Contact
rows.first      # <Contact: @Id="0035j00001RW3xbAAD", @Name="Akin Kristen">
rows.first.Name # Akin Kristen

Doing the same thing independently:

contact = Contact.select(:Id, :Name).where(Name: 'Akin Kristen').take
contact.Name # Akin Kristen

Developer Console

Developer console integrates both sf_cli’s command methods and object model librry into IRB to make scripting easier in REPL.

You can directly use sf_cli’s command methods:

$ sf_cli
> sf.query "SELECT Id, Name FROM Case", target_org: :your_org

Object Model is also available:

> use :your_org_name
> gen :Account, :Contact, :User  #=> generate 3 Object model classes
> acc = Account.find_by Name: 'Hoge Fuga'

There are some other console commands:

> query "SELECT Id, Name, ... FROM BazBar__c" # just same as `sf data query` with human readable format
> apex "System.debug('abc');"                 # execute Apex code instantly

Type help to know all console commands