How to Use SOQL and SOSL with Salesforce CLI: A 2025 Guide
The Salesforce Command Line Interface (CLI) is a powerful tool for interacting with your Salesforce org, and when paired with SOQL (Salesforce Object Query Language) and SOSL (Salesforce Object Search Language), it becomes a go-to solution for querying data. Whether you’re an admin pulling reports or a developer debugging records, mastering these query languages via the CLI can save time and unlock deeper insights. As of April 4, 2025, this guide walks you through using SOQL and SOSL with the Salesforce CLI, from setup to practical examples.
What Are SOQL and SOSL?
- SOQL: A SQL-like language for retrieving specific data from Salesforce objects. It’s precise, targeting exact fields and records (e.g., SELECT Name FROM Account).
- SOSL: A search-based language for finding text across multiple objects and fields. It’s broader, ideal for fuzzy searches (e.g., finding “Acme” in any record).
The CLI lets you run both from your terminal, bypassing the need for browser-based tools like Developer Console.
Prerequisites
Before querying, ensure you’re set up:
- Salesforce CLI Installed: Download and install it (see for steps).
- Authenticated Org: Log in to your Salesforce org with: bashСвернутьПереносКопировать
sf org login web --alias MyOrg - Terminal Ready: Use Command Prompt (Windows), Terminal (macOS), or a Linux shell.
- Permissions: Your user must have access to the objects and fields you’re querying.
Using SOQL with Salesforce CLI
Basic SOQL Command
The sf data query command runs SOQL queries. Here’s the syntax:
bashСвернутьПереносКопировать
sf data query --query "SELECT Id, Name FROM Account" --target-org MyOrg
- –query: Your SOQL statement.
- –target-org: The alias of your connected org (e.g., MyOrg).
Example 1: Fetching Records
To get the first 10 accounts:
bashСвернутьПереносКопировать
sf data query --query "SELECT Id, Name FROM Account LIMIT 10" --target-org MyOrg
Output is in JSON format, showing each record’s Id and Name.
Example 2: Filtering Data
Find accounts in California:
bashСвернутьПереносКопировать
sf data query --query "SELECT Name, BillingState FROM Account WHERE BillingState = 'CA'" --target-org MyOrg
Exporting Results
Save results to a file with –result-format:
bashСвернутьПереносКопировать
sf data query --query "SELECT Id, Name FROM Account" --target-org MyOrg --result-format csv > accounts.csv
Options include csv, json, or human (readable table).
Using SOSL with Salesforce CLI
Basic SOSL Command
SOSL also uses sf data query, but with a different query structure:
bashСвернутьПереносКопировать
sf data query --query "FIND {Acme} IN ALL FIELDS RETURNING Account(Name), Contact(FirstName, LastName)" --target-org MyOrg
- FIND {term}: The search term (e.g., “Acme”).
- IN ALL FIELDS: Searches all text fields (or specify NAME FIELDS, EMAIL FIELDS, etc.).
- RETURNING: Lists objects and fields to return.
Example 1: Simple Search
Search for “Acme” across accounts and contacts:
bashСвернутьПереносКопировать
sf data query --query "FIND {Acme} IN ALL FIELDS RETURNING Account(Name), Contact(FirstName, LastName)" --target-org MyOrg
Results show matches grouped by object.
Example 2: Narrowing Scope
Search only account names:
bashСвернутьПереносКопировать
sf data query --query "FIND {Acme} IN NAME FIELDS RETURNING Account(Name, Industry)" --target-org MyOrg
Exporting SOSL Results
Like SOQL, save to a file:
bashСвернутьПереносКопировать
sf data query --query "FIND {Sales} IN ALL FIELDS RETURNING Account(Name)" --target-org MyOrg --result-format csv > search_results.csv
Key Differences Between SOQL and SOSL
- Precision vs. Breadth: SOQL targets specific objects and fields; SOSL searches broadly across multiple objects.
- Use Case: Use SOQL for structured queries (e.g., reports), SOSL for text searches (e.g., finding a keyword).
- Performance: SOQL is faster for exact matches; SOSL excels with large datasets and fuzzy logic.
Tips for Success
- Test in Sandbox: Run queries in a non-production org first to avoid surprises.
- Escape Quotes: In complex queries, wrap strings with single quotes and escape inner quotes (e.g., WHERE Name = ‘O\’Brien’).
- Check Limits: Salesforce caps queries at 50,000 records (SOQL) and has SOSL search limits—use LIMIT to stay within bounds.
- Default Org: Set a default org with sf config set target-org=MyOrg to skip –target-org in commands.
- Debug Errors: If a query fails, check syntax or permissions (e.g., “Invalid field” means the field isn’t accessible).
Advanced Usage
- Batch Queries: Use a script to loop through queries: bashСвернутьПереносКопировать
for i in {1..5}; do sf data query --query "SELECT Name FROM Account LIMIT 10 OFFSET $((i*10))" --target-org MyOrg; done - Tooling API: Query metadata (e.g., Apex classes) with –use-tooling-api: bashСвернутьПереносКопировать
sf data query --query "SELECT Name FROM ApexClass" --target-org MyOrg --use-tooling-api
Final Thoughts
Using SOQL and SOSL with the Salesforce CLI empowers you to query data efficiently from the command line, bypassing slower GUI tools. Whether you’re pulling precise records with SOQL or casting a wide net with SOSL, the CLI offers flexibility and speed. As of 2025, it’s a cornerstone of Salesforce automation and development workflows. Start experimenting with these commands today, and watch your productivity soar!