sfagent

A terminal agent for Salesforce developers — powered by the Salesforce Models API.

Think of it as a Claude Code-like experience for building on Salesforce: query data, deploy metadata, run Apex, and manage orgs — all from your terminal with AI assistance.

Install

npm install -g sfagent

Quick Start

sfagent --setup   # first-time: configure Models API credentials
sfagent           # start the agent

Or without installing:

npx sfagent

Prerequisites

1. Node.js 20+
2. Salesforce CLI installed and authenticated:

   npm install -g @salesforce/cli
   sf org login web --set-default

3. Agentforce enabled on your Salesforce org

Setup

On first run, configure the Models API connection:

sfagent --setup

This walks you through:

1. Selecting your Salesforce org
2. Creating an External Client App (with step-by-step instructions)
3. Entering your Consumer Key and Secret
4. Testing the connection

Credentials are stored locally in .sfagent/credentials.json (in the current directory). Add .sfagent/ to your .gitignore.

External Client App Settings

When creating the app in Salesforce Setup:

OAuth Scopes:

• Manage user data via APIs (api)
• Perform requests at any time (refresh_token, offline_access)
• Access the Salesforce API Platform (sfap_api)

Policies Tab:

• Enable Client Credentials Flow ✓
• Set a Run As user
• Issue JWT-based access tokens ✓

Usage

# Start the agent
sfagent

# Use a specific model
SF_MODEL=sfdc_ai__DefaultBedrockAnthropicClaude45Sonnet sfagent

# Target a specific org
SF_TARGET_ORG=my-sandbox sfagent

Example Interactions

sfagent> Query the first 5 accounts by revenue
sfagent> Show me my connected orgs
sfagent> Deploy the force-app directory to my sandbox
sfagent> Run this Apex: System.debug(UserInfo.getUserName());
sfagent> Read the Account trigger and add a validation

Commands

| Command | Description | |---------|-------------| | /setup | Configure Models API credentials | | /login [alias] | Log in to a Salesforce org via sf CLI | | /org | Show current org details | | /model [name] | Show or change the AI model | | /clear | Clear conversation history | | /help | Show all commands | | /exit | Exit sfagent |

Tools

sfagent has 7 built-in tools the AI can use:

| Tool | Read-only | Description | |------|-----------|-------------| | file_read | ✓ | Read local project files | | soql_query | ✓ | Execute SOQL queries with formatted tables | | org_info | ✓ | Display/list connected orgs | | file_edit | | Search-and-replace file edits | | sf_cli | | Run any sf command | | deploy | | Deploy metadata to an org | | apex_run | | Execute anonymous Apex |

Non-read-only tools require confirmation before executing. You can approve individually or allow all for the session.

Supported Models

Any model available through the Salesforce Models API:

| Model | API Name | |-------|----------| | Claude Sonnet 4 (default) | sfdc_ai__DefaultBedrockAnthropicClaude4Sonnet | | Claude Sonnet 4.5 | sfdc_ai__DefaultBedrockAnthropicClaude45Sonnet | | Claude Haiku 4.5 | sfdc_ai__DefaultBedrockAnthropicClaude45Haiku | | GPT-4o | sfdc_ai__DefaultGPT4Omni | | Gemini 2.5 Pro | sfdc_ai__DefaultVertexAIGeminiPro25 |

Environment Variables

| Variable | Default | Description | |----------|---------|-------------| | SF_MODEL | sfdc_ai__DefaultBedrockAnthropicClaude4Sonnet | Model API name | | SF_TARGET_ORG | (auto-detected) | Org alias or username |

How It Works

sfagent uses prompt-engineered tool use over the Salesforce Models API. The AI model receives tool descriptions in the system prompt and outputs structured <tool_call> blocks when it needs to perform actions. The harness parses these, executes the tools locally via the Salesforce CLI, and feeds results back to the model.

User input → Models API (LLM) → Tool calls → sf CLI execution → Results → LLM → Response

License

MIT