🚀 sf-soql

A powerful Node.js CLI to execute Salesforce SOQL queries using an access token and export results as CSV.

Built for automation, DevOps, CI/CD, and large dataset exports.

✨ Features

• ✅ Standard REST Query API
• ✅ Tooling API support (-t)
• ✅ Auto-pagination (handles >2000 records automatically)
• ✅ Nested relationship fields (Owner.Name)
• ✅ Query from CLI (-q)
• ✅ Query from file (-f)
• ✅ Combine file + inline query
• ✅ Clean stdout (CSV only)
• ✅ API version override
• ✅ CI/CD friendly

📦 Installation

npm install -g sf-soql-cli

🔐 Authentication File

Create a JSON file with your Salesforce session details:

• You can use this Chrome Extension to get Access token (sid)

while you are the Salesforce URL like:

https://xyz.my.salesforce-setup.com/lightning/setup/SetupOneHome/home

Using Chrome DevTools Console

• Paste this code when you in the /lightning/setup/SetupOneHome/home page:

document.cookie.split(';')

OR

(function () {
  const rows = document.cookie.split(';').map(cookie => {
    const [name, ...rest] = cookie.trim().split('=');
    return {
      Name: name,
      Value: decodeURIComponent(rest.join('='))
    };
  });
  console.table(rows);
})();

• Instance URL:

const instanceUrl = location.origin.replace('-setup', '') + '/';
console.log(instanceUrl);

{
  "accessToken": "YOUR_ACCESS_TOKEN",
  "instanceUrl": "https://yourInstance.salesforce.com"
}

Or you can use this sf cli command to get access.json

sf org display -o username --json > access.json

🧪 Basic Usage

Inline Query

sf-soql -a access.json -q "SELECT Id, Name FROM Account"

Query From File

sf-soql -a access.json -f query.soql

Example query.soql:

SELECT Id, Name FROM Account

Combine File + Inline Query

Very useful for reusable base queries.

sf-soql -a access.json -f base.soql -q "WHERE CreatedDate = TODAY ORDER BY Name"

If base.soql contains:

SELECT Id, Name FROM Account

Final executed query becomes:

SELECT Id, Name FROM Account WHERE CreatedDate = TODAY ORDER BY Name

📤 Output Options

Print to Terminal

sf-soql -a access.json -q "SELECT Id, Name FROM Account"

Save to File

sf-soql -a access.json -q "SELECT Id, Name FROM Account" -o accounts.csv

Pipe to File

sf-soql -a access.json -q "SELECT Id FROM Contact" > contacts.csv  

✔ stdout contains only CSV ✔ logs are written to stderr ✔ safe for scripting

Pipe to csv-datatble

sf-soql -a access.json -q "SELECT Id FROM Contact" | csv-datatable

Install csv-datatable for this

🔄 Handling Large Result Sets

Salesforce REST API returns up to 2000 records per batch.

This CLI automatically:

• Follows nextRecordsUrl
• Fetches all pages
• Combines results
• Outputs a single CSV

Example:

Executing Standard API query...
Total records fetched: 1509

🔗 Relationship Fields (Nested Fields)

Supports relationship flattening.

Example:

sf-soql -a access.json -q "SELECT Id, Name, Owner.Name FROM Account"

Output:

Id,Name,Owner.Name
001xx000003DGbEAAW,Acme,John Doe

✔ Only selected fields are exported ✔ No full nested object dumping

🛠 Tooling API Support

Use -t to query metadata objects like:

• ApexClass
• ApexTrigger
• CustomObject
• ValidationRule
• etc.

Example:

sf-soql -a access.json -q "SELECT Id, Name FROM ApexClass" -t

🔢 API Version Override

Default API version: 59.0

Override:

sf-soql -a access.json -q "SELECT Id FROM Account" -v 60.0

📋 CLI Options

| Option | Description | | ----------------------------- | -------------------------------------- | | -a, --auth <file> | Auth JSON file (required) | | -q, --query <soql> | Inline SOQL query | | -f, --file <queryFile> | SOQL query file | | -o, --output <file> | Output CSV file | | -t, --tooling | Use Tooling API | | -v, --api-version <version> | Salesforce API version (default: 59.0) | | -h, --help | Show help | | -V, --version | Show version |

🧱 Architecture

• commander — CLI argument parsing
• axios — Salesforce REST calls
• json2csv — CSV generation
• Auto-pagination logic

🧑‍💻 Common Use Cases

• CI/CD metadata extraction
• Data export automation
• DevOps Salesforce scripts
• Reporting automation
• Tooling API inspection
• Governance auditing

🔒 Security Best Practices

• Do not store access tokens in source control
• Use environment-specific auth files
• Rotate access tokens regularly
• Prefer OAuth flow for production systems

🚀 Future Enhancements

• Streaming CSV for very large datasets
• Bulk API 2.0 mode
• JSON output mode
• Retry with exponential backoff
• Progress bar
• OAuth auto-login

📜 License

MIT (c) Mohan Chinnappan

Built for Salesforce developers who prefer powerful CLI automation.