tools-only CLI Guide
Complete reference for Salesforce CLI commands used with Agentforce agents.
⚠️ Note: These commands are in beta. Use
--helpto verify current flags.
Command Quick Reference
| Command | Purpose | Stage |
|---|---|---|
sf agent validate authoring-bundle |
Validate Agent Script syntax | Authoring |
sf agent publish authoring-bundle |
Publish authoring bundle | Authoring |
sf agent preview |
Preview agent behavior | Testing |
sf agent activate |
Activate published agent | Deployment |
sf agent deactivate |
Deactivate agent for changes | Deployment |
sf project retrieve start --metadata Agent:Name |
Sync agent from org | Sync |
sf project deploy start --metadata Agent:Name |
Deploy agent to org | Sync |
Authoring Commands
sf agent validate authoring-bundle
Validates Agent Script syntax before publishing.
sf agent validate authoring-bundle [flags]
| Flag | Description | Required |
|---|---|---|
-n, --api-name |
API name of authoring bundle | No (prompts if omitted) |
-o, --target-org |
Org username or alias | No (uses default) |
--api-version |
Override API version | No |
⚠️ No
--source-dirflag! The command finds bundles in your DX project automatically.
# Validate specific bundle
sf agent validate authoring-bundle --api-name Customer_Support_Agent --target-org myorg
Common Errors:
| Error | Cause | Solution |
|---|---|---|
SyntaxError: Unexpected token |
Invalid syntax | Check indentation, colons, quotes |
type integer is not supported |
Using integer type |
Use number instead |
Unexpected '<' |
Using list<type> |
Use list[type] (square brackets) |
sf agent publish authoring-bundle
Publishes the authoring bundle to create or update the agent.
sf agent publish authoring-bundle [flags]
| Flag | Description | Required |
|---|---|---|
-n, --api-name |
API name of authoring bundle | No (prompts if omitted) |
-o, --target-org |
Org username or alias | No (uses default) |
⚠️ No
--source-dir,--async, or--waitflags!
# Publish specific bundle
sf agent publish authoring-bundle --api-name Customer_Support_Agent --target-org myorg
Creates/Updates:
Bot- Top-level chatbotBotVersion- Version configurationAiAuthoringBundle- Agent Script metadataGenAiPlugin- TopicsGenAiFunction- Actions
Testing Commands
sf agent preview
Preview agent behavior before production deployment.
sf agent preview [flags]
| Flag | Description | Required |
|---|---|---|
--api-name |
Agent API name | No |
--target-org |
Org username or alias | No |
--use-live-actions |
Enable live mode (real Apex/Flows) | No |
--client-app |
Connected app name | For live mode |
--output-dir |
Save transcript/response files | No |
--apex-debug |
Generate Apex debug logs | No |
--authoring-bundle |
Specify authoring bundle | No |
# Simulated mode (default)
sf agent preview --api-name Customer_Support_Agent --target-org myorg
# Live mode with connected app
sf agent preview --api-name Customer_Support_Agent --use-live-actions --client-app MyAgentApp --target-org myorg
# With debug output
sf agent preview --api-name Customer_Support_Agent --output-dir ./logs --apex-debug --target-org myorg
Preview Modes
| Mode | Description | Use When |
|---|---|---|
| Simulated (default) | LLM simulates action responses | Apex/Flows not ready, testing logic |
| Live | Uses actual Apex/Flows | Integration testing with real data |
Connected App Setup (Required for Live Preview)
Step 1: Create Connected App
- Setup → App Manager → New Connected App
- Configure:
| Setting | Value |
|---|---|
| Connected App Name | AgentPreviewApp |
| Enable OAuth Settings | ✅ Checked |
| Callback URL | http://localhost:1717/OauthRedirect |
| OAuth Scopes | Manage user data via Web browsers (web) |
- Save and wait for activation
Step 2: Link to CLI User
sf org login web \
--client-app AgentPreviewApp \
--client-id YOUR_CONSUMER_KEY \
--scopes web
Step 3: Run Live Preview
sf agent preview --api-name My_Agent --use-live-actions --client-app AgentPreviewApp --target-org myorg
Preview Output Files
When using --output-dir:
transcript.json - Conversation record:
{
"messages": [
{"role": "user", "content": "What is my order status?"},
{"role": "assistant", "content": "I'd be happy to help..."}
]
}
responses.json - Full API messages with internal details
Preview Troubleshooting
| Issue | Cause | Solution |
|---|---|---|
| "No active agents found" | Agent not activated | Run sf agent activate first |
| "Connected app not found" | Not linked to CLI user | Run sf org login web --client-app |
| "default_agent_user not found" | Invalid user in config | Update config block |
| Preview hangs | Action timeout | Use --apex-debug, check limits |
| Actions not executing | Not deployed | Deploy Apex/Flows first |
Deployment Commands
sf agent activate
Activates a published agent.
sf agent activate --api-name My_Agent --target-org myorg
Requirements:
- Agent must be published first
- Apex classes and Flows deployed
default_agent_usermust be valid org user
sf agent deactivate
Deactivates an agent (required before making changes).
sf agent deactivate --api-name My_Agent --target-org myorg
Required before:
- Adding/removing topics
- Modifying action configurations
- Changing system instructions
- Updating variable definitions
Management Commands
sf org open (with Agent)
Opens agent in Agentforce Builder.
sf org open --source-file force-app/main/default/aiAuthoringBundles/My_Agent/My_Agent.agent --target-org myorg
# Or navigate to Agentforce Studio
sf org open --path /lightning/setup/AgentStudio/home --target-org myorg
Sync Commands
Retrieve Agent from Org
sf project retrieve start --metadata Agent:Customer_Support_Agent --target-org myorg
Retrieves:
- Bot, BotVersion, GenAiPlannerBundle
- GenAiPlugin (topics), GenAiFunction (actions)
- Supporting Apex/Flows (if in same package)
Deploy Agent to Org
sf project deploy start --metadata Agent:Customer_Support_Agent --target-org myorg
Does NOT deploy Apex or Flows - deploy separately first.
Common Workflows
New Agent Development
# 1. Validate syntax
sf agent validate authoring-bundle --api-name My_Agent --target-org myorg
# 2. Deploy dependencies FIRST
sf project deploy start --source-dir force-app/main/default/classes --target-org myorg
sf project deploy start --source-dir force-app/main/default/flows --target-org myorg
# 3. Publish agent
sf agent publish authoring-bundle --api-name My_Agent --target-org myorg
# 4. Preview (simulated)
sf agent preview --api-name My_Agent --target-org myorg
# 5. Activate
sf agent activate --api-name My_Agent --target-org myorg
# 6. Preview (live mode)
sf agent preview --api-name My_Agent --use-live-actions --client-app MyApp --target-org myorg
Modifying Existing Agent
# 1. Deactivate
sf agent deactivate --api-name My_Agent --target-org myorg
# 2. Edit Agent Script file
# 3. Validate
sf agent validate authoring-bundle --api-name My_Agent --target-org myorg
# 4. Re-publish
sf agent publish authoring-bundle --api-name My_Agent --target-org myorg
# 5. Test
sf agent preview --api-name My_Agent --target-org myorg
# 6. Re-activate
sf agent activate --api-name My_Agent --target-org myorg
Syncing Between Orgs
# 1. Retrieve from source
sf project retrieve start --metadata Agent:My_Agent --target-org source-org
# 2. Deploy dependencies to target
sf project deploy start --source-dir force-app/main/default/classes --target-org target-org
sf project deploy start --source-dir force-app/main/default/flows --target-org target-org
# 3. Deploy agent metadata
sf project deploy start --metadata Agent:My_Agent --target-org target-org
# 4. Activate
sf agent activate --api-name My_Agent --target-org target-org
Agent Metadata Types
| Metadata Type | Description |
|---|---|
Bot |
Top-level chatbot definition |
BotVersion |
Version configuration |
GenAiPlannerBundle |
Reasoning engine (LLM config) |
GenAiPlugin |
Topic definition |
GenAiFunction |
Action definition |
# Retrieve specific metadata types
sf project retrieve start --metadata Bot:Customer_Support_Agent --target-org myorg
sf project retrieve start --metadata GenAiPlugin --target-org myorg
Preview Limitations
| Limitation | Details |
|---|---|
| Escalation testing | Not supported - test via actual endpoint |
| Connection endpoints | Preview doesn't strictly adhere to config |
| Script changes | Require validation and preview restart |
| Active agent required | Agent must be active for preview |
Related Documentation
- Agent Script Reference - Complete syntax guide
- Actions Reference - Action configuration
- Patterns & Practices - Best practices