nu-salesforce

A Nushell module for interacting with the Salesforce REST API. Query data, manage records, and call endpoints without leaving your shell.

Features

• Authentication — Log in via username/password + security token (SOAP) or a direct session ID.
• SOQL & SOSL — Run queries and searches with built-in auto-pagination.
• SObject CRUD — Create, read, update, upsert, and delete records.
• REST / Apex / Tooling — Make arbitrary calls to any Salesforce REST endpoint.
• Org Utilities — Inspect API limits, describe SObjects, and list recently changed records.

Installation

Git Clone

Clone this repository (or copy the nu-salesforce directory) somewhere on your machine, then import it in your Nushell session or config:

use /path/to/nu-salesforce *

Using nuance (an very experimental module manager for nu)

First, install nuance if you haven't already.

1. Using brew: brew install freepicheep/tap/nuance
2. Build from source using cargo: cargo install --git https://github.com/freepicheep/nuance
3. Shell script: curl --proto '=https' --tlsv1.2 -LsSf https://github.com/freepicheep/nuance/releases/latest/download/nuance-installer.sh | sh

Then, in your project directory, run nuance init. This creates the mod.toml necessary for managing dependencies and publishing your package if you choose to do so. Then, all you have to do is run nuance add "https://github.com/freepicheep/nu-salesforce" to install this module into your project's .nu-modules/ directory. If you are writing code that uses this module, add use ./nu-modules/nu-salesforce/nu-salesforce * to your code to load the module.

Quick Start

# 1. Authenticate
sf login --username "user@example.com" --password "xxxxxxxx" --token "xxxxxxxx"

# 2. Query records
sf query "SELECT Id, Name FROM Account LIMIT 10"

# 3. Create a record
sf create Account { Name: "Acme Corp", Industry: "Technology" }

# 4. Update a record
sf update Account 001XXXXXXXXXXXX { Name: "Updated Name" }

# 5. Delete a record
sf delete Account 001XXXXXXXXXXXX

# 6. Call a generic REST endpoint
sf rest "limits/"

# 7. Check your session
sf whoami

# 8. Log out
sf logout

Credential Management

With Email, Password, and Security Token

If you store your Salesforce username, password, and security token in a .env file, you can use the load-env-file function to add those to your environment variables.¹

Your .env File

SALESFORCE_USERNAME='user@example.com'
SALESFORCE_PASSWORD='xxxxxxxx'
SECURITY_TOKEN='xxxxxxxx'

In Your Script

use /path/to/nu-salesforce * 

# load your salesforce credentials from the .env file
load-env-file

# login to salesforce with your credentials
sf login --username $env.SALESFORCE_USERNAME --password $env.SALESFORCE_PASSWORD --token $env.SECURITY_TOKEN

With Session Id and Instance

If you want to login using a session id, you can obtain it several ways. One way is to run the following script in an "Execute Anonymous Window" and copy the id from the debug output in the console.

String id = UserInfo.getSessionId().Substring(15);

System.debug('My session id: ' + id);

Your instance is usually yourdomain.my.salesforce.com.

You can then log in to nu-salesforce like this:

sf login --session 'your_session_id' --instance 'yourdomain.my.salesforce.com'

Commands

Command	Description
sf login	Authenticate to Salesforce
sf logout	Clear the current session
sf whoami	Show session information
sf query	Run a SOQL query
sf query-more	Fetch the next page of query results
sf search	Run a SOSL search
sf quick-search	Shorthand SOSL search
sf get	Get a record by ID
sf get-by-custom-id	Get a record by external ID
sf create	Create a new record
sf update	Update an existing record
sf upsert	Upsert a record via external ID
sf delete	Delete a record
sf describe	Describe an SObject's metadata
sf metadata	Get lightweight SObject metadata
sf deleted	List records deleted in a date range
sf updated	List records updated in a date range
sf rest	Generic REST API call
sf apex	Call an Apex REST endpoint
sf tooling	Call the Tooling API
sf limits	Show org API usage limits
sf describe-all	Describe all available SObjects
load-env-file	Loads key-value data from a .env file

Learning More

Every command has built-in documentation. Use help to view a command's description, flags, and examples:

help sf query
help sf create
help sf login

Disclaimers

Most of the original code was written with Claude Opus 4.6 using Google's Antigravity. I used the excellent simple-salesforce python library to guide the llm on creating this module. I have not fully tested every feature yet and am not responsible for any unexpected behavior or misuse of this module.

License

MIT

Footnotes

1. Thanks to @pixl_xip on the nushell Discord for this handy function. ↩