# developer Salesforcedx - Full Documentation # # Add Trace Flags and Log Levels To generate debug logs in Web Console, you must add user-specific trace flags and log levels in the `traceLogs.json` file. 1. Hover over the **No Tracing** label on the task bar and select **Create trace flags for the current user** to add a trace flag for your user. ![Tracing options on the task bar](https://developer.salesforce.com/docs/platform/media/webconsole/mouse_hover_trace_menu.png) 2. The `traceLogs.json` file opens with an added trace flag block for the current user. To change the log level for the current user, click the **Change** text before the `debugLevelName` property. ![Adding trace flags for the current user](https://developer.salesforce.com/docs/platform/media/webconsole/user_log_level.png) 3. To add trace flags for another user, click the **Add trace for another user** text before the `USER_DEBUG` property and specify a username to add. 4. Add log levels. **note:** For more information about log levels, refer to [Debug Log Levels](https://help.salesforce.com/s/articleView?id=platform.code_setting_debug_log_levels.htm&type=5) 1. Click the **Create Debug level** text. 2. Type a label and press Enter. 3. To accept the default log levels, select **Yes**. To customize log levels, select **No** and select an option for different log types. ![Log levels are added in the traceLogs.json file](https://developer.salesforce.com/docs/platform/media/webconsole/debug_levels2.png) 5. To remove a block, click the **Remove** text before the block. Notice that the **No Tracing** label on the taskbar changes to **Tracing until END-TIME**. ![Tracing status showed on the taskbar](https://developer.salesforce.com/docs/platform/media/webconsole/tracing_started.png '{"class": "image-sm"}') After the tracing starts, whenever you perform a task on the connected org, a log is generated with trace details. Here's an example. ![Logs with trace details](https://developer.salesforce.com/docs/platform/media/webconsole/logs_pulled.png) Logs are pulled by default after every 30 seconds. You can change the log-pull interval in Settings. ![Log-pull interval in settings](https://developer.salesforce.com/docs/platform/media/webconsole/log_pull_time2.png '{"class": "image-lg"}') # Abilities In many environments, an MCP server exposes dozens of tools. Passing all of them into every request increases token usage, degrades reasoning quality, and makes tool selection less reliable. Abilities address these problems by using a RAG-based semantic retrieval approach to activate only the small, domain-relevant subset of tools needed for each task, keeping the model focused. Abilities answer a simple question: _Which tools should the agent activate for the current task?_ In Agentforce Vibes, each Ability represents a domain-specific context, such as Apex, Lightning web components (LWC), DevOps, or Mobile, and automatically activates the right tools. Abilities are enabled by default. You can toggle it on or off using the Abilities setting in VS Code. ## Enable or Disable Abilities To enable or disable the Abilities feature from Settings: 1. Select **File** \> **Preferences** \> **Settings** (Windows or Linux) or **Code** \> **Settings** \> **Settings** (macOS). 2. Under **Agentforce Vibes**, select **Enable Abilities**. Abilities are enabled by default. When you toggle this setting, the DX MCP server configuration is updated automatically, unless you've customized your configuration. ### First-Time Activation When you enable Abilities for the first time, the DX MCP server configuration file is updated or overwritten to use the `--toolsets "all` configuration. ### Toggling the Abilities Setting After the first time, toggling the Abilities setting in the UI updates the configuration file each time, switching between the `--toolsets "all` and the current default configuration. **Exception:** If you've configured the `--toolsets` or `--tools` flags in your DX MCP server configuration file (after the first-time upgrade), the Abilities setting respects your configuration and doesn't overwrite the file. ### Reset to Default or All Tools To return to either the `--toolsets all` configuration or the defaults on your own, disable and then delete the DX MCP server. The configuration is then recreated with either `--toolsets all` or default configuration, depending on the current value of the Abilities setting. ## Key Features Abilities are designed to manage context intelligently by controlling tool activation. This table highlights the core characteristics that make Abilities efficient, composable, and optimized for quality execution. | **Feature** | **Benefit / How It Works** | | ---------------------------- | ------------------------------------------------------------------------------------- | | **Context-Aware Activation** | Only the tools relevant to your request are enabled automatically. | | **Automatic Execution** | Activates on every request without manual setup or configuration. | | **Composable Modules** | Multiple Abilities can be active at the same time (for example, Apex + LWC + DevOps). | | **Token-Efficient** | Minimizes token usage and cost by limiting context to what’s necessary. | | **Quality Optimized** | Models perform better when operating within a focused and coherent execution context. | ## How Abilities Work Each time you start a new task, the Ability Coordinator interprets your intent and automatically activates the relevant Ability (or combination of Abilities) without any manual setup or configuration. It determines which Abilities to activate by using signals from the prompt intent and keywords in the prompt. Depending on the type of request, the Ability Coordinator activates the appropriate domain-specific Ability, for example: **Build a component** – If you ask the agent to create a Lightning web component with tests, the LWC Ability is activated. **Update metadata** – Requests such as adding a new value to a Lead picklist trigger the Platform Ability. **Write triggers** – Requests to create an Apex trigger and handler class activate the Apex Ability. Abilities analyzes your request, selects the minimal set of tools required, and ensures that the agent operates in a focused, relevant execution context. Multiple abilities can be combined to form the final execution context for a single request. ## How Tool Selection Works in Abilities To decide which tools to activate, the Abilities Coordinator: 1. Converts each MCP tool’s definition—including its name, description, and intended usage—into vector representations stored in a database. 2. Converts the user’s prompt into a vector using the same embedding model. 3. Compares the prompt vector with the tool embeddings to identify the most relevant tools. 4. Picks the top K tools (around 10) based on similarity scores. 5. Automatically includes any dependent tools that are required to ensure complete execution. ### Handle Tool Dependencies Some MCP tools function as orchestrators, which means they require more tools to complete a task successfully. To support this, Abilities apply a post-selection expansion step after the initial tool match. This step ensures that the final execution context includes all required dependencies—without exposing unnecessary tools. ### Example of Ability-Constrained Tool Activation **Prompt** : “Deploy the Apex changes and run all relevant tests.” **Activated Ability**: Apex Ability. **Available Tools (DX MCP Server)** The DX MCP server exposes a broad set of tools across multiple domains, including Apex, LWC, Mobile, DevOps, and Platform: ``` [deploy_metadata, run_code_analyzer, apex_test_run, create_lwc_component, create_mobile_lwc_biometrics, list_devops_center_work_items, checkout_devops_center_work_item, assign_permission_set, list_all_orgs, …] ``` **Tools Activated for This Request** Based on detected intent and the active Ability, only the tools required for Apex deployment are included in the execution context: `[deploy_metadata, run_code_analyzer, apex_test_run]` With Abilities enabled, the model reasons only over the tools relevant to Apex deployment, while tools from unrelated domains such as LWC, Mobile, DevOps, and Platform are excluded. This reduces token usage, improves tool selection accuracy, and ensures that execution remains intentional, predictable, and high quality. At the same time, all Salesforce DX MCP server tool definitions are written to a file in the `.sfdx`directory, and the model is explicitly instructed that it can discover other tools there. This lets Agentforce to look up and learn how to use other DX MCP tools when they’re referenced during a task even if they aren’t part of the active tool set, without expanding the initial context unnecessarily. ## Examples of Included Tools Each Agentforce Vibes Ability bundles a curated set of MCP tools for a specific development domain. Here's an example of possible active tools for each of the Abilities, depending on the prompt: | Ability | Includes MCP Tools | | -------------------- | -------------------------------------------------------------------------------------------------------- | | **Apex Ability** | `run_code_analyzer`, `deploy_metadata`, `create_scratch_org` | | **LWC Ability** | `create_lwc_component_from_prd`, `guide_figma_to_lwc_conversion`, `create_lwc_jest_tests` | | **Mobile Ability** | `create_mobile_lwc_biometrics`, `create_mobile_lwc_document_scanner` | | **DevOps Ability** | `create_devops_center_pull_request`, `checkout_devops_center_work_item`, `list_devops_center_work_items` | | **Platform Ability** | `get_username`, `assign_permission_set`, `list_all_orgs` | | ## Abilities and Skills Abilities work together with Skills to enable governed, scalable, and trustworthy agentic development. | Feature | Primary Role | What It Addresses | | ------------- | ------------------- | ----------------------------------- | | **Abilities** | Context activation | "What should the agent use?" | | **Skills** | Procedural guidance | "How should the agent do the work?" | ### How Skills and Abilities Work Together 1. You submit a request. 2. Abilities automatically activates the relevant tools based on intent. 3. The agent plans its approach within this constrained environment. 4. Agentforce invokes as needed to guide execution. 5. The agent executes using the selected tools. ## See Also - [MCP Tools](https://developer.salesforce.com/docs/platform/einstein-for-devs/guide/devagent-mcp.md) - [Salesforce DX MCP Server and Tools (Beta)](https://developer.salesforce.com/docs/atlas.en-us.sfdx_dev.meta/sfdx_dev/sfdx_dev_mcp.htm) # Access Record Data with Data SDK (Beta) While Agentforce Vibes automatically generates code for data access, it's helpful to understand how you can write your own code to access Salesforce data from your React web app via Data SDK. Data SDK provides several advantages for data access, including environment adaptability and type safety. - **Abstraction and consistency:** Data SDK abstracts environment-specific APIs, so you call a simple method and the SDK handles the implementation details for the specific host environment, for example, Lightning Experience or an Experience Builder site. - **Capability detection:** Data SDK includes integrated capability detection to identify the runtime environment, infer its capabilities, and determine the concrete way to implement those capabilities. Given the built-in detection, component authors can code safely across deployment scenarios. - **Modern developer experience:** Data SDK provides full TypeScript definitions to offer IntelliSense and autocomplete functionality, compile-time type safety, and uses Promises for structured error handling (try/catch blocks) instead of loosely-typed events. Learn how you can access and update Salesforce data from your web app. - [Work with Data SDK](https://developer.salesforce.com/docs/platform/einstein-for-devs/guide/reactdev-data-sdk-intro.md) - [GraphQL Query Parameters](https://developer.salesforce.com/docs/platform/einstein-for-devs/guide/reactdev-data-sdk-query.md) - [GraphQL Mutate Parameters](https://developer.salesforce.com/docs/platform/einstein-for-devs/guide/reactdev-data-sdk-mutate.md) - [GraphQL Queries in Data SDK](https://developer.salesforce.com/docs/platform/einstein-for-devs/guide/reactdev-data-sdk-graphql.md) - [GraphQL Mutations in Data SDK](https://developer.salesforce.com/docs/platform/einstein-for-devs/guide/reactdev-data-sdk-graphql-mutation.md) - [Error Handling in Data SDK](https://developer.salesforce.com/docs/platform/einstein-for-devs/guide/reactdev-data-sdk-graphql-error.md) - [Cache Control in Data SDK](https://developer.salesforce.com/docs/platform/einstein-for-devs/guide/reactdev-data-sdk-cache-control.md) # Access Usage Metrics Users with the `DevOps Center Administrator` permission set can enable the Analytics tab of DevOps Center. After it’s enabled, DevOps users can track and analyze detailed Agentforce Vibes usage metrics in the Agentic Development dashboard. Alternatively, admins with the `System Administrator` can download a more limited set of Agentforce Vibes usage data as a CSV file. ## Generate the Agentic Development Dashboard (Developer Preview) The dashboard aggregates Agentforce Vibes activity and provides insights about AI-powered development, developer productivity metrics, and AI models utilization. For more information, see [Salesforce Help: Access Agentforce Vibes Usage with Agentic Development (Developer Preview)](https://help.salesforce.com/s/articleView?id=platform.devops_center_agentic_development.htm). ## Download Agentforce Vibes Usage Data in a CSV File A subset of metrics available in the Agentic Development dashboard are also available to download as CSV file from your production org. To start the download, go to **Setup** > **Agentforce Vibes Extension** and click **Download Usage Data**. The CSV file aggregates usage across all sandboxes and scratch orgs associated with that production org. It downloads locally and includes only the previous 30 days of usage. Use the file in spreadsheets, BI tools, or custom scripts for analysis and reporting. Note that the download includes only the previous 30 days. You can't select a custom time range. **note:** [Digital Wallet](https://help.salesforce.com/s/articleView?id=xcloud.wallet_monitor_usage.htm&type=5) is the only source of truth for tokens consumed under consumption-based pricing and Flex Credit usage. The CSV file provides AI usage data for the org, which may include both metered and unmetered usage, as well as free-tier usage for applicable Agentforce Vibes versions. Don't use the CSV file to track Flex Credit usage or metered token consumption. It provides only an approximation of token usage and may not reflect exact consumption totals. **warning:** CSV usage data is not accurate for activity recorded between Agentforce Vibes 4.0.0 to 4.24.0. For accurate usage metrics, upgrade to 4.25.0 or later and allow one full month of usage before relying on the CSV data. # Access Visualization Capabilities For supported metadata files, use the Metadata Visualizer extension to view a visual representation that helps you interpret raw metadata. You can access visualizations in multiple ways: - **From a file tab in VS Code** 1. In VS Code, open the source file for a metadata component in your DX project that you want to visualize. 2. Click **Visualize** on the upper-right corner of the Tab Editor. - **From the context menu** 1. In the VS Code Explorer pane, right-click on the source file for a metadata component in your DX project and click **Visualize**. A split panel opens by default and displays the metadata visualization. Optionally, you can switch to the full-screen view. To automatically see visualizations of any metadata source files as soon as you open them, click the Settings icon in the file visualization pane. Then select the check box for the **Auto Load Visualization**. If you want to view or hide visualizations for a plugin, click the Settings icon in the file visualization pane. Under **Plugins**, select or clear the corresponding checkbox and then reload the window. - **From Agentforce Vibes** You can use Agentforce Vibes to create or modify a file that contains metadata. The metadata file information appears as a card with a message `Visualization Available`. Click the **Visualize** button on the card to see the metadata visualization for the files. # Actions Actions define tasks in the developer workflow. They act on either a topic or a subtopic. Design actions to be as consistent as possible, even across topics. For example, `sf apex generate class` and `sf lightning generate app` follow the same pattern, even though they generate different things. Another example is `sf project deploy start` and `sf slack-app deploy start`. In these examples, the topic and flags can change, but the command structure is the same. Where appropriate, use these standard action names: [sf command common actions](https://developer.salesforce.com/docs/platform/salesforce-cli-plugin/guide/common-actions.md). ## Guidelines - Actions are verbs. - Keep actions as short and precise as possible. - Every Salesforce CLI command must have a primary action. - Commands can have secondary clarifying actions. - Example: `sf project deploy start` - Example: `sf org alias set` ## Good Examples - `sf apex generate class` - `sf apex run test` - `sf org login web` - `sf project deploy start` - sub-action of `start` clarifies the primary action category - `sf org alias set my-scratch-org=test-sadbiytjsupn@example.com` - sub-action of `set` clarifies the primary action category # Add a Developer User to Your Dev Hub Org Using a Developer license, add a user with the Developer profile and assign them the Developer permission set. The Developer license is a paid license that is designed for users whose role is to build customizations or applications. This license provides access to development tools and environments. It comes with one Developer sandbox, one scratch org, and access to the Dev Hub. In the production org, this license restricts access to standard and custom objects. 1. Create a user in your Dev Hub org. 1. In Setup, enter `Users` in the Quick Find box, then select **Users**. 2. Click **New User**. 3. Fill out the form. 4. Select **Developer** for User License, and then **Developer** for Profile. 5. After filling out the remaining information, click **Save**. 2. Assign the built-in Developer permission set to the user. 1. On the user's detail page, in the Permission Set Assignments related list, click **Edit Assignments**. 2. In the Available Permission Sets, add the Developer permission set and click **Save**. The Developer permission set grants access to Dev Hub features and second-generation packages. For details, see [Create and Assign a Permission Set to Developer Users](https://developer.salesforce.com/docs/platform/sfdx-dev/guide/sfdx-setup-permission-set.md). # Add a Limited Access User to Your Dev Hub Org If your users only require access to the Dev Hub, the Salesforce Limited Access - Free license is a good approach. The Salesforce Limited Access - Free license is available by request. After this license is provisioned add a user with this license and the Limited Access user profile, and then create and assign them a permission set to the required Dev Hub objects. The Salesforce Limited Access - Free is designed for users whose role is to build customizations or applications. This license provides access to the Dev Hub, development tools, and environments. In the production org, this license restricts access to standard and custom objects. 1. Create a user in your Dev Hub org. 1. In Setup, enter `Users` in the Quick Find box, then select **Users**. 2. Click **New User**. 3. Fill out the form. 4. Select **Salesforce Limited Access - Free** for User License, and then **Limited Access User** for Profile. 5. After filling out the remaining information, click **Save**. 2. Create a permission set that provides your developer users with access to the required Dev Hub objects. For details, see [Create and Assign a Permission Set for Developer Users](https://developer.salesforce.com/docs/atlas.en-us.sfdx_dev.meta/sfdx_dev/sfdx_setup_permission_set.htm) or [Assign Second-Generation Managed Packaging User Permissions](https://developer.salesforce.com/docs/atlas.en-us.pkg2_dev.meta/pkg2_dev/sfdx_pkg_user_permission.htm). # Add a System Administrator or Standard User to Your Dev Hub Org Add system administrator users only if their work requires that level of authority. Otherwise, add standard users and create a permission set with the required Salesforce DX permissions. 1. Create a user in your Dev Hub org, if necessary. 1. In Setup, enter `Users` in the Quick Find box, then select **Users**. 2. Click **New User**. 3. Fill out the form, and assign the System Administrator or Standard User profile. 4. Click **Save**. If you’re adding a System Administrator user, you can stop here. 2. If you’re adding a Standard User, create a permission set for Salesforce DX users if you don’t have one. 1. From Setup, enter `Permission Sets` in the Quick Find box, then select **Permission Sets**. 2. Click **New**. 3. Enter a label, API name, and description. The API name is a unique name used by the API and managed packages. 4. Select a user license option. If you plan to assign this permission set to multiple users with different licenses, select **None**. 5. Click **Save**. The permission set overview page appears. From here, you can navigate to the permissions you want to add or change for Salesforce DX. For the required permissions, see [Create and Assign a Permission Set to Developer Users](https://developer.salesforce.com/docs/platform/sfdx-dev/guide/sfdx-setup-permission-set.md). 3. Apply the Salesforce DX permission set to the Standard User. 1. From Setup, enter `Permission Sets` in the Quick Find box, then select **Permission Sets**. 2. Select the Salesforce DX permission set. 3. In the permission set toolbar, click **Manage Assignments**. 4. Click **Add Assignments**. 5. Select the user to assign the permission set to. 6. Click **Assign**. 7. Click **Done**. You can limit a user’s access by modifying the permissions. # Add Agentforce Conversation Client to Your React App with Agentforce Vibes With Agentforce Vibes, you can integrate conversational AI interactions into interal React apps for employee use cases. To add these interactions, you integrate the Agentforce Conversation Client (ACC). The ACC package is built on the Lightning Out 2.0 platform as a Lightning Web Component Interface (LWCI). This approach enables the conversational UI to be seamlessly embedded and rendered within non-LWC tech stacks, such as a React host environment. By embedding an Agentforce Conversation Client in your React app, your users can retrieve complex information, such as high-demand property data or real-time sales metrics, through natural conversation instead of manually researching vast amounts of data. To learn more about Agentforce Conversation Client in React apps, see [Integrate Agentforce Conversation Client in React Apps](https://developer.salesforce.com/docs/platform/multiframework/guide/reactdev-acc.html) the _Salesforce Multi-Framework Developer Guide_. ## 1 Prepare Your VS Code Workspace Agentforce Vibes uses rules and skills to understand your intent, automatically manipulating project files like `index.tsx` and managing necessary npm dependency installations. For the extension to process the necessary agent skills, make sure that you configured your environment and Salesforce org correctly. See [Configure Agentforce Conversation Client](https://developer.salesforce.com/docs/platform/multiframework/guide/mfw-setup.html#optional-configure-agentforce-conversation-client) in the _Salesforce Multi-Framework Developer Guide_. ## 2 Vibe an Agent Panel into an Application With the workspace configured, utilize natural language prompts in the IDE to define the structural placement, dimensions, and docking behavior of the panel within the React DOM. - _Example Prompt:_ _"Create an Agentforce Employee Agent panel that is docked to the right of the main screen."_ ## 3 Vibe Refinements to the Agent Panel Configure visual states and styling, such as floating/expanded transitions or specific header border radiuses, without writing manual CSS. - _Example Prompt:_ _"The Agentforce Employee Agent panel should start as a floating fab icon docked to the lower left side of the page; when a user clicks the icon, it should expand into a full chat panel."_ # Add Context Context tells Agentforce Vibes exactly what to look at when responding to your prompt. Without context, the agent gives general answers. With the right context, it gives answers specific to your code, your org, and your current problem. ## Add Context to a Prompt Click **@** in the chat input to open the context picker. The picker groups available context by type, including files from your project. Select one or more items to attach them to your next prompt. You can also: - Drag and drop image files directly into the chat input. - Right-click a selection in the editor and choose **Agentforce: Add to Context**. ## Context Types ### Workspace Problems Attaches current errors and warnings from the VS Code Problems panel, including file locations. Use this when debugging a compilation error or deployment failure. ### Files Attaches the complete content of one or more files from your project. The agent sees imports and surrounding code, not just the selection. Use this when you want the agent to work with a specific class, component, or configuration file. ### Database Attaches the schema metadata for sObjects in your connected org—object definitions, field names, field types, and relationships. The picker lists the SObjects available in your org (for example, Account, Contact, Case, and custom objects). The agent uses this to generate code that references real API names rather than placeholder values. Use this when building features against specific objects or when you want the agent to understand your org's data model. ### Plans Attaches an existing plan to the conversation. The agent uses the plan's context, goals, and task history when responding. ### Git Attaches Git diffs, commit messages, and change history. Use this when you want the agent to understand what changed recently or to troubleshoot a regression. ### Last Terminal Output Attaches the output from your most recent terminal session. Use this when debugging a failed CLI command or deployment error. ## What the Agent Sees | Context Type | What the Agent Sees | | :------------------- | :-------------------------------------------------------------------------------- | | Workspace Problems | Errors and warnings with file locations | | Files | Complete file content, imports, and surrounding context | | Database | SObject schema metadata—object definitions, field names, types, and relationships | | Plans | Plan document including context, goals, and tasks | | Git | Diffs, commit messages, and change history | | Last terminal output | Terminal output with formatting preserved | ## Combine Context Types Attaching multiple context types gives the agent the complete picture. Some effective combinations: | Scenario | Context to combine | | :-------------------- | :------------------------------------------------ | | Deployment issues | Files + Last terminal output + Workspace Problems | | Test failures | Test class + Main class + Last terminal output | | Component development | Component files + Database + Related Apex | | Integration debugging | Service classes + Last terminal output + Files | ## Considerations - The agent's context window has limits. Very large files or many files attached together may be truncated. Agentforce Vibes manages this automatically, but prefer specific files over entire folders for targeted questions. - Clear attached context when switching between unrelated tasks to avoid the agent carrying forward irrelevant information. - Pin frequently used files and metadata to avoid re-selecting them each session. - Images bypass the Salesforce LLM Gateway trust layer. When you drag an image into the chat input, the image is sent directly to the AI model without passing through the trust layer. Don't include screenshots or images that contain sensitive data, personally identifiable information, or confidential org configuration. ## See Also - [Chat Interface](https://developer.salesforce.com/docs/platform/agentforcevibes/guide/afv-chat-interface.md) - [Debug Logging](https://developer.salesforce.com/docs/platform/agentforcevibes/guide/afv-debug-logging.md) - [MCP Servers](https://developer.salesforce.com/docs/platform/agentforcevibes/guide/afv-mcp-servers.md) # Add Images and Brands to Your React App Using the Content Read-Only MCP Server and Tools (Beta) To add an existing image or brand to your React app, Agentforce Vibes Extension uses the content-readonly MCP server (beta) and tools. To search for and add a brand, it uses get_brand_instructions and search_brands. To search for and add an image, it uses search_electronic_media or search_media_cms_channels. Before Agentforce can use this MCP server, make sure that it’s set up in the right org. See [Set Up the Content Read-Only MCP Server and Tools](https://developer.salesforce.com/docs/platform/einstein-for-devs/guide/reactdev-setup.md) for more information. ## Brand Your React App To add a brand to your React app, Agentforce Vibes uses the get_brand_instructions and search_brands MCP tools from the content-readonly MCP server. Together, these tools enable Agentforce Vibes to find a published brand from Salesforce CMS and apply it. For example, this prompt would trigger the get_brand_instructions and search_brand tools: “Get brand GlobalDesignSystem and apply text fonts, colors and buttons to my React Web App \- across all pages” ## Add an Image to Your React App To add an image to your React app, Agentforce Vibes uses the search_electronic_media or search_media_cms_channels tools from the content-readonly MCP server. These sample prompts can trigger the MCP tools. - “Using media search, show me images of luxury apartments with a swimming pool.” - “Using media search, retrieve images from Salesforce CMS showing exteriors of properties.” - “Using media search, find the images that have palace vibes and a lakeside ceremony.” - “Using media search, search for the official corporate logo and use it for the tenant portal.” After you enter the prompt, Agentforce asks you to choose a method for the search. Both the search_electronic_media and search_media_cms_channels tools search for images that are published only to public CMS channels. - The search_electronic_media tool uses Data 360 hybrid search (vector search and keyword search) to find an image based on your prompt. - The search_media_cms_channels tool uses keywords to find an image based on your prompt. # Add Logging Add logging to your plugin with the [`Logger`](https://forcedotcom.github.io/sfdx-core/classes/logger_logger.Logger.html) class from `@salesforce/core`. ## Add Logging to a Command Let's show how to add logging to the initial `hello world` command that `sf dev generate plugin` generated. 1. Open `src/commands/hello/world.ts` and update the import from `@salesforce/core` to include the `Logger` class: ```typescript import { Messages, Logger } from "@salesforce/core"; ``` 2. Now create child logger instance. The `Logger` class creates a root logger with some defaults. Other code, like a command or library, then creates a child logger using the `Logger.child()` method. To try it out, replace the `run` method with this code: ```typescript public async run(): Promise { const log = await Logger.child(this.ctor.name); const { flags } = await this.parse(World); const time = new Date().toDateString(); const message = `Hello ${flags.name} at ${time}`; log.debug(`Time: ${time} | Name: ${flags.name}`); this.log(message); return { name: flags.name, time, }; } ``` The example shows how you pass the name of the child logger as the first argument of `Logger.child()`. In the example, it's set it to `this.ctor.name` which points to the name of the command class (`World` in our case). But it can be anything you want. 3. Now make the logger print records to the terminal. First set the `DEBUG` environment variable, either to `*` to see all log records or `sf:_LoggerName_` to filter records by logger. For now, let's print logs for only the `hello world` command: For bash/zsh: ```bash export DEBUG='sf:World' ``` For PowerShell: ```bash $Env:DEBUG = 'sf:World' ``` 4. Run the `hello world` command using `bin/dev` as usual: ```bash ./bin/dev hello world --name Astro ``` You see log and command output similar to this: ```bash sf:World DEBUG Time: Wed Sep 7 2022 | Name: Astro +0ms Hello Astro at Wed Sep 7 2022 ``` 5. Remember to unset the `DEBUG` environment variable after you're done: For bash/zsh: ```bash unset DEBUG ``` For PowerShell: ```bash $Env:DEBUG = '' ``` ## Logging Levels The `Logger` class wraps [`pino`](https://github.com/pinojs/pino), which already sets log levels. See [logger.levels](https://getpino.io/#/docs/api?id=levels) for more information. ## Log Storage Salesforce CLI saves logs to a file in the global `.sf` folder; you can turn off this behavior by setting the `SFDX_DISABLE_LOG_FILE` environment variable to `true`. The CLI starts a new log file every day, formatted like `sf-YYYY-MM-DD.log`. The CLI cleans them up if they're more than 7 days old. Salesforce CLI saves log records to a log file only if the log level method used is the **same level or higher** than the level set in the logger instance. Let's see how this works. By default, the root logger sets the log level to `warn`. This example shows calls to `debug`, `warn`, and `error` methods, but only the `warn` and `error` records are saved to the log file: ```typescript log.debug("test1"); // log level: 20, below 40 so don't save it. log.warn("test2"); // log level: 40, same level as the logger instance so record goes to file. log.error("test3"); // log level: 50, above `warn` so it's saved to a file too. ``` The user can set the log level with environment variables (`SF_LOG_LEVEL=debug` or `SF_LOG_LEVEL=trace`) so it's best not to rely on code to manage your child Logger. Rather,let the user control the log level. # Add More Commands to Your Plugin Saying hello to the world is always fun, but you're likely ready to do more. Let's add two more commands to your plugin. ## Call an External Service This section shows how to create a new command called `call external service`. The command makes an HTTP request to an [external service](http://numbersapi.com/random/trivia?json) that returns an interesting fact about a number. The command has no flags other than the ones you get for "free" (`--help`, `-h` and `--json`). When you enter the service's URL in your browser, it displays JSON with the interesting fact and some metadata about it. 1. Install [Got](https://www.npmjs.com/package/got), our recommended npm HTTP library, into your plugin by running this command: ```bash yarn add got ``` Because the new command makes HTTP requests, you need an HTTP library. While you can use any library you want, we recommend Got because it’s simple yet full featured. 2. In a terminal, change to the top-level directory of your plugin and run this command to generate the initial files, or scaffolding: ```bash sf dev generate command --name call:external:service ``` The command prompts if you want to overwrite the existing `package.json` file, enter `y` to update the file with information about the new command. The `--name` flag specifies the full colon-separated name of the command you want to create. For example, if you want to create the command `do awesome stuff`, set `--name` to `do:awesome:stuff`. The command generates these files, similar to the [files associated with the `hello world` command](https://developer.salesforce.com/docs/platform/salesforce-cli-plugin/guide/gs-generate-plugin.md#tour-the-generated-files): - `src/commands/call/external/service.ts` - `messages/call.external.service.md` - `test/command/call/external/service.nut.ts` - `test/command/call/external/service.test.ts` The Typescript files contain `import` statements for the minimum required Salesforce libraries, and scaffold some basic code. The new type names come from the value you passed to the `--name` flag. 3. Open up `src/commands/call/external/service.ts` in your IDE, such as Visual Studio Code. 4. Add this `import` statement to the beginning of the file with the other `import` statements: ```typescript import got from 'got'; ``` 5. Let’s now handle the JSON returned by our new command when a user runs it with the `--json` flag, which all CLI commands have by default. We want our command to return the JSON provided by the external service’s API. The underlying CLI framework uses the return type of the command class’ `run` method, which in this case is `CallExternalServiceResult`. So replace the code for `CallExternalServiceResult` to reflect the service’s JSON: ```typescript export type CallExternalServiceResult = { text: string; number: number; found: boolean; type: string; }; ``` 6. Let’s next work with the command flags. Remember that our command doesn't have any flags beyond the default ones, so remove this code inside the `CallExternalService` class which declares a flag that we no longer need: ```typescript public static readonly flags = { name: Flags.string({ summary: messages.getMessage('flags.name.summary'), description: messages.getMessage('flags.name.description'), char: 'n', required: false, }), } ``` Then remove the `Flags` import from `@salesforce/sf-plugins-core` at the beginning of the file. After removing `Flags` from the import statement, the import looks like this: ```typescript import { SfCommand } from '@salesforce/sf-plugins-core'; ``` 7. The final coding step is to update the `run` method inside the `CallExternalService` class. This method is where you put the logic for your command. In our case, we want our command to make an HTTP GET request to the service API and return the result. Replace the `run` method with this code: ```typescript public async run(): Promise { const result = await got( 'http://numbersapi.com/random/trivia?json' ).json(); this.log(result.text); return result; } ``` In the preceding code, `this.log` logs the interesting fact to the terminal only if the `–json` flag is _not_ provided. In other words, the underlying CLI framework is smart enough to know whether to log non-JSON output, like strings, to the terminal. 8. We're ready to test! Open a Terminal, either in VS Code or outside, and run the command using `bin/dev.js`. ```bash bin/dev.js call external service ``` Hopefully you see an interesting fact like this: `54 is the number of countries in Africa.` Let’s try the freebie flags, the ones that are magically available even though you didn't explicitly add them. First get help for the command: ```bash bin/dev.js call external service --help ``` The help message isn't that useful yet because you haven't updated the boilerplate content in `messages/call.external.service.md`. We show an example of updating the help in the next example. Now run the command again but get JSON output instead of the default human-readable: ```bash bin/dev.js call external service --json ``` Good job adding a new command! Now let’s create something more Salesforce-y. ## Connect to a Salesforce Org Next create a more complex command that connects to a Salesforce org and displays a list of all Account names and IDs. The command has one new flag, `--target-org`, with short name `-o`. Use the flag to specify the username or alias of an org you’ve previously logged into, also known as _authorized_, with the `login org` command. Do you recognize the flag? It's a standard flag that many of the core Salesforce CLI commands use, such as `project deploy start`. You can use the flag too, including its existing code to connect to an org. Let's give it a try. 1. In a terminal, change to the top-level directory of your plugin and run this command to generate the initial command files; answer `y` to overwrite the `package.json` file: ```bash sf dev generate command --name connect:org ``` Here's the list of generated files: - `src/commands/connect/org.ts` - `messages/connect.org.md` - `test/command/connect/org.nut.ts` - `test/command/connect/org.test.ts` 2. Run this interactive command to generate a flag. In this context, "generate" means update the existing command files with the required information for the new `--target-org` flag: ```bash sf dev generate flag ``` Be sure you specify these properties of the new flag when prompted: - Command to add a new flag: `connect org` - Type: `requiredOrg` - Use standard definition: Y - Flag name: `--target-org` (default) The command updates two files: `src/commands/connect/org.ts` with the new flag code and `messages/connect.org.md` with a new entry for the flag's summary, which is displayed when you run the command with the `--help` flag. 3. Open `src/commands/connect/org.ts` in your IDE and review the new generated code for the `--target-org` flag: ```typescript 'target-org': Flags.requiredOrg(), ``` Because we're using _existing_ code for the flag, the single line of code is all you need -- magic! 4. Because `org.ts` still contains code for the `--name` flag, which was added automatically when you originally generated the command, remove it now, just to keep things tidy. This is the code you can remove from `public static readonly flags`: ```typescript name: Flags.string({ summary: messages.getMessage('flags.name.summary'), description: messages.getMessage('flags.name.description'), char: 'n', required: false, }), ``` The new flag is ready! Let's now code the command functionality. 5. Update the command’s return type (`ConnectOrgResult`) with this code: ```typescript export type ConnectOrgResult = Array<{ Name: string; Id: string }>; ``` 6. Update the `run` method with this code: ```typescript public async run(): Promise { // parse the provided flags const { flags } = await this.parse(ConnectOrg); // Get the orgId from the Org instance stored in the `target-org` flag const orgId = flags['target-org'].getOrgId(); // Get the connection from the Org instance stored in the `target-org` flag const connection = flags['target-org'].getConnection(); this.log(`Connected to ${flags['target-org'].getUsername()} (${orgId}) with API version ${connection.version}`); // Use the connection to execute a SOQL query against the org const result = await connection.query<{ Name: string; Id: string }>('SELECT Id, Name FROM Account'); // Log the results if (result.records.length > 0) { this.log('Found the following Accounts:'); for (const record of result.records) { this.log(` • ${record.Name}: ${record.Id}`); } } else { this.log('No Accounts found.'); } return result.records; } ``` Your new command is now ready to test! 7. If you haven't already done so, log in to your test org with the `org login web` command. Run `org list` to see the orgs you've previously logged into and their associated usernames and aliases. We'll use the username or alias to test your new command. Logging into an org before you work with it is standard Salesforce CLI practice. Think about `project deploy start`: it too takes a username (also via the `--target-org` flag) of the org you want to deploy to, and it's assumed that you've previously logged into it. 8. Test your new command with `bin/dev.js`; replace `` with the username or alias of the org you just logged into: ```bash bin/dev.js connect org --target-org ``` Hopefully you see output similar to this (the record IDs have been truncated for security): ```bash Connected to () with API version 64.0 Found the following Accounts:` • Acme: 001B...` • salesforce.com: 001B...` • Global Media: 001B... • TestAccount: 001B... • xyz: 001B... • Test1: 001B... ``` Make sure that the short flag name works too! ```bash bin/dev.js connect org -o ``` Pretty cool, huh. # Add Project to Source Control The Activity Bar enables you to initialize a repository from a project and publish the repository to GitHub. Alternatively, Open the Command Palette (⇧⌘P) and search for "git" to view git commands. **note:** You must have a GitHub account as a prerequisite to adding a project to a GitHub repo. To add a project to a GitHub repo: 1. Click the Source Control icon (![Source Control icon](https://developer.salesforce.com/media/codebuilder/icon_source_control.png)) in the Activity Bar. 2. Click **Initialize Repository**. 3. In the Message field, add a commit message, such as "initialize project repo". 4. Click **Commit**. 5. Click **Yes** in the window asking "Would you like to stage all your changes and commit them directly?" 6. Click **Open Git Log** in the window that says "Make sure you configure your "user.name" and "user.email" in git." 7. Click the Terminal subtab and run the following commands after you substitute values for _you@example.com_ and _Your Name_: ```text git config --global user.email "you@example.com" git config --global user.name "Your Name" ``` 8. In the Activity Bar, enter the commit message again and click **Commit**. 9. Click **Publish Branch**. 10. Click **Allow** in the window that says "The extension 'GitHub' wants to sign in using GitHub." 11. Click **Copy & Continue to GitHub**. 12. Click Open to open GitHub in your browser. 13. Paste the copied code and click **Continue**. 14. If prompted for Single sign-on to your organizations, click **Continue**. 15. If prompted, click **Authorize Visual-Studio-Code**. 16. Complete logging in to GitHub. If two-factor authentication is configured for your GitHub account, you may be asked for a two-factor code. 17. In Agentforce Vibes IDE, choose to "Publish to GitHub private repository". Alternatively, choose "Publish to GitHub public repository" if you want to make the repo available to anyone. If in doubt, choose the private repo. Your project is now saved in GitHub. # Add Project to Source Control The Activity Bar enables you to initialize a repository from a project and publish the repository to GitHub. Alternatively, Open the Command Palette (⇧⌘P) and search for "git" to view git commands. **note:** You must have a GitHub account as a prerequisite to adding a project to a GitHub repo. To add a project to a GitHub repo: 1. Click the Source Control icon (![Source Control icon](https://developer.salesforce.com/docs/media/codebuilder/icon_source_control.png)) in the Activity Bar. 2. Click **Initialize Repository**. 3. In the Message field, add a commit message, such as "initialize project repo". 4. Click **Commit**. 5. Click **Yes** in the window asking "Would you like to stage all your changes and commit them directly?" 6. Click **Open Git Log** in the window that says "Make sure you configure your "user.name" and "user.email" in git." 7. Click the Terminal subtab and run the following commands after you substitute values for _you@example.com_ and _Your Name_: ```text git config --global user.email "you@example.com" git config --global user.name "Your Name" ``` 8. In the Activity Bar, enter the commit message again and click **Commit**. 9. Click **Publish Branch**. 10. Click **Allow** in the window that says "The extension 'GitHub' wants to sign in using GitHub." 11. Click **Copy & Continue to GitHub**. 12. Click Open to open GitHub in your browser. 13. Paste the copied code and click **Continue**. 14. If prompted for Single sign-on to your organizations, click **Continue**. 15. If prompted, click **Authorize Visual-Studio-Code**. 16. Complete logging in to GitHub. If two-factor authentication is configured for your GitHub account, you may be asked for a two-factor code. 17. In VS Code, choose to "Publish to GitHub private repository". Alternatively, choose "Publish to GitHub public repository" if you want to make the repo available to anyone. If in doubt, choose the private repo. Your project is now saved in GitHub. # Add Salesforce DX Users System administrators can access the Dev Hub org by default. You can enable more users to access the Dev Hub org so that they can create scratch orgs and use other developer-specific features. Your developer users can use Salesforce DX with the Salesforce, and Salesforce Platform standard user license, or you can assign them the Developer license, or the Salesforce Limited Access - Free license instead. If your org has Developer licenses, you can add users with the Developer profile and assign them the provided Developer permission set. Alternatively, you can add users with the Standard User or System Administrator profiles. For a standard user, you must create a permission set with the required Dev Hub permissions. We recommend that you avoid adding users as system administrators unless their work requires that level of authority and not just Dev Hub org access. - **[Determine Which License to Assign to Dev Hub Users](https://developer.salesforce.com/docs/platform/sfdx-dev/sfdx-dev/devhub/dev-hub-license.md)** Which license type you assign to developer users depends on how much access they require in the Dev Hub org. If they require full administrative access, you can assign the Salesforce or Salesforce Platform standard user license. If you want to limit access to only specific features, Salesforce provides two developer license options - **[Add a System Administrator or Standard User to Your Dev Hub Org](https://developer.salesforce.com/docs/platform/sfdx-dev/guide/sfdx-setup-add-users-standard.md)** Add system administrator users only if their work requires that level of authority. Otherwise, add standard users and create a permission set with the required Salesforce DX permissions. - **[Add a Developer User to Your Dev Hub Org](https://developer.salesforce.com/docs/platform/sfdx-dev/guide/sfdx-setup-add-users-developer.md)** Using a Developer license, add a user with the Developer profile and assign them the Developer permission set. - **[Add a Limited Access User to Your Dev Hub Org](https://developer.salesforce.com/docs/platform/sfdx-dev/guide/sfdx-setup-add-free-license-users.md)** If your users only require access to the Dev Hub, the Salesforce Limited Access - Free license is a good approach. The Salesforce Limited Access - Free license is available by request. After this license is provisioned add a user with this license and the Limited Access user profile, and then create and assign them a permission set to the required Dev Hub objects. - **[Create and Assign a Permission Set to Developer Users](https://developer.salesforce.com/docs/platform/sfdx-dev/guide/sfdx-setup-permission-set.md)** To give full access to the Dev Hub org, create and assign a custom permission set that grants access to required Dev Hub objects. Or if you have the Developer license, assign the Developer permission set. **See Also** - [Org Shape Permissions](https://developer.salesforce.com/docs/platform/sfdx-dev/sfdx-dev/scratch-orgs/shape/sfdx-dev-shape-permissions.md) # Add Static Outbound IP Addresses **warning:** Enabling this feature can result in slower workspace startup times, because workspaces with static IPs are configured with custom network routing. Agentforce Vibes IDE workspaces can route outbound traffic through a fixed set of static IP addresses. IP allowlisting is an opt-in feature that Salesforce needs to enable for your organization. When active, all outbound traffic from newly created workspaces exits through these IPs. **important:** If your organization enforces IP-based access restrictions, such as login IP ranges, add these IPs to your allowlist. ## Shared Outbound IP Considerations All Agentforce Vibes IDE workspaces share the static outbound IP addresses and don’t uniquely identify a specific customer, organization, or workspace. - **Global IP Sharing**: Adding these addresses to an allowlist permits network-level connection requests from all Agentforce Vibes IDE workspaces, including those outside your organization. - **App-Level Protection Required**: IP allowlisting controls network connectivity only—it doesn’t grant data access. Continue to protect your endpoints with appropriate app-level authentication and valid Salesforce authorization checks. ## Add IP Ranges for an Org Before you add other IPs, you must first add the outbound IP of your IDE. Use `curl ifconfig.me` to retrieve the local IP and add it to the allowlist, as explained in these steps. You can add an IP range for a user profile by: 1. Using the setup option. 2. Editing the `.profile-meta.xml` file for a profile. ### Use the Setup Option 1. Click ![Setup gear icon](https://developer.salesforce.com/media/webconsole/gear_icon.png '{"class": "image-icon-md"}'). 2. In the Quick Find box, enter `Agentforce Vibes IDE`. 3. Verify that the **Enable Static IPs** option is enabled. 4. In the Quick Find box, enter `Profiles`, and select **Profiles** under Users. 5. From the list of user profiles, select an Agentforce-Vibe-IDE-user profile. For example, System Administrator. 6. Scroll down to the **Login IP Ranges** option and click **New**. 7. To add an IP range, enter the same IP address in the **Start IP Address** and **End IP Address** boxes. 8. Enter a description. For example, `AFV IDE Static IP Address`. 9. Save your changes. To add more IP addresses, repeat the process. ### Edit the `.profile-meta.xml` File You can manage login IP ranges as profile metadata, which is useful for automation or for CI (Continuous Integration) and CD (Continuous Deployment) pipelines. Add these IP ranges to your `.profile-meta.xml` file as given in this example. ```XML AFV IDE Static IP Address 3.97.47.150 3.97.47.150 AFV IDE Static IP Address 3.96.231.152 3.96.231.152 AFV IDE Static IP Address 63.176.81.41 63.176.81.41 AFV IDE Static IP Address 35.156.227.229 35.156.227.229 AFV IDE Static IP Address 52.214.167.100 52.214.167.100 AFV IDE Static IP Address 34.255.93.118 34.255.93.118 AFV IDE Static IP Address 35.173.46.159 35.173.46.159 AFV IDE Static IP Address 98.85.15.64 98.85.15.64 AFV IDE Static IP Address 44.255.127.30 44.255.127.30 AFV IDE Static IP Address 32.184.174.148 32.184.174.148 AFV IDE Static IP Address 15.157.244.168 15.157.244.168 AFV IDE Static IP Address 35.183.200.37 35.183.200.37 AFV IDE Static IP Address 3.66.124.229 3.66.124.229 AFV IDE Static IP Address 3.120.64.58 3.120.64.58 AFV IDE Static IP Address 63.35.124.169 63.35.124.169 AFV IDE Static IP Address 52.214.96.158 52.214.96.158 AFV IDE Static IP Address 18.213.38.17 18.213.38.17 AFV IDE Static IP Address 3.217.1.37 3.217.1.37 AFV IDE Static IP Address 44.232.109.242 44.232.109.242 AFV IDE Static IP Address 54.190.205.95 54.190.205.95 ``` After you're done updating the IP ranges, [Deploy the metadata to Your org](https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/cli_reference_project_commands_unified.htm#cli_reference_project_deploy_start_unified) by using the `sf project deploy start` command. ## Frequently Asked Questions ### Will the List of IPs Change, and How Do I Know When They Do? The list of IPs doesn't undergo frequent changes. In the event of a planned change, customers are notified before any changes. ### Do I Add All the IPs? Yes. While your workspace currently uses a single IP, we can reassign it to any IP on our list at any time for maintenance or capacity. We recommend allowlisting the entire IP list rather than just your current one to avoid the risk of an immediate, unannounced loss of connectivity. ### Does the IP List Replace Other Security Controls? IP allowlisting provides an extra layer of defense, but Salesforce still fully enforces all standard authentication methods. The standard authentication methods include usernames, passwords, MFA (multi-factor authentication), and Single Sign-On (SSO), alongside authorization controls like profiles, permission sets, and sharing rules. ### Can I Restrict Access to My Organization's Workspaces Alone? IP allowlisting alone isn't enough because multiple organizations share those IPs. Instead, Salesforce authentication secures your data by making sure that only authorized users can log in, no matter where they connect from. # Add Trace Flags and Log Levels To generate debug logs in Web Console, you must add user-specific trace flags and log levels in the `traceLogs.json` file. 1. Hover over the **No Tracing** label on the task bar and select **Create trace flags for the current user** to add a trace flag for your user. ![Tracing options on the task bar](https://developer.salesforce.com/docs/platform/media/webconsole/mouse_hover_trace_menu.png) 2. The `traceLogs.json` file opens with an added trace flag block for the current user. To change the log level for the current user, click the **Change** text before the `debugLevelName` property. ![Adding trace flags for the current user](https://developer.salesforce.com/docs/platform/media/webconsole/user_log_level.png) 3. To add trace flags for another user, click the **Add trace for another user** text before the `USER_DEBUG` property and specify a username to add. 4. Add log levels. **note:** For more information about log levels, refer to [Debug Log Levels](https://help.salesforce.com/s/articleView?id=platform.code_setting_debug_log_levels.htm&type=5) 1. Click the **Create Debug level** text. 2. Type a label and press Enter. 3. To accept the default log levels, select **Yes**. To customize log levels, select **No** and select an option for different log types. ![Log levels are added in the traceLogs.json file](https://developer.salesforce.com/docs/platform/media/webconsole/debug_levels2.png) 5. To remove a block, click the **Remove** text before the block. Notice that the **No Tracing** label on the taskbar changes to **Tracing until END-TIME**. ![Tracing status showed on the taskbar](https://developer.salesforce.com/docs/platform/media/webconsole/tracing_started.png '{"class": "image-sm"}') After the tracing starts, whenever you perform a task on the connected org, a log is generated with trace details. Here's an example. ![Logs with trace details](https://developer.salesforce.com/docs/platform/media/webconsole/logs_pulled.png) Logs are pulled by default after every 30 seconds. You can change the log-pull interval in Settings. ![Log-pull interval in settings](https://developer.salesforce.com/docs/platform/media/webconsole/log_pull_time2.png '{"class": "image-lg"}') # agent activate Activate an agent in an org. ## Description for agent activate Activating an agent makes it immediately available to your users. A published agent must be active before you can preview it with the "agent preview" CLI command or VS Code. Agents can have multiple versions; only one version can be active at a time. If you run the command without the --api-name or --version flags, the command provides a list of agent API names and versions for you to choose from. Use the flags to specify the exact agent and version without being prompted. If you use the --json flag and not --version, then the latest agent version is automatically activated. The value of the --version flag is always a number, corresponding to the "vX" part of the "BotVersion" metadata in your project. For example, if you have a force-app/main/default/bots/My_Agent/v4.botVersion-meta.xml file in your project, then you activate this version with the "--version 4" flag. ## Flags | Flag Name (Long) | Flag Name (Short) | Description | |------------------|-------------------|-------------| | ‑‑api‑name | ‑n | **Type:** Value

API name of the agent to activate; if not specified, the command provides a list that you choose from. | | ‑‑api‑version | N/A | **Type:** Value

Override the api version used for api requests made by this command | | ‑‑flags‑dir | N/A | **Type:** Value

Import flag values from a directory. | | ‑‑json | N/A | **Type:** Boolean

Format output as json. | | ‑‑target‑org | ‑o | **Type:** Value
**Required**

Username or alias of the target org. Not required if the `target-org` configuration variable is already set. | | ‑‑version | N/A | **Type:** Value

Version number of the agent to activate; if not specified, the command provides a list that you choose from. | ## Examples for agent activate Activate an agent in your default target org by being prompted for both its API name and version: ```shell sf agent activate ``` Activate version 2 of an agent with API name Resort_Manager in the org with alias "my-org": ```shell sf agent activate --api-name Resort_Manager --version 2 --target-org my-org ``` # agent adl create Create an Agentforce Data Library. ## Description for agent adl create Creates a new data library in the target org. The --source-type flag determines the type of library: SFDRIVE (file upload), KNOWLEDGE (Salesforce Knowledge articles), or RETRIEVER (existing active Custom Retriever). For SFDRIVE libraries, creation provisions the full Data Cloud pipeline (DLO → DMO → SearchIndex → Retriever). Upload files with `sf agent adl upload` after creation. ## Flags | Flag Name (Long) | Flag Name (Short) | Description | |------------------|-------------------|-------------| | ‑‑api‑version | N/A | **Type:** Value

Override the api version used for api requests made by this command | | ‑‑content‑fields | N/A | **Type:** Value

Comma-separated list of content fields for KNOWLEDGE libraries (optional, mutable after creation). | | ‑‑data‑category‑ids | N/A | **Type:** Value

Comma-separated list of data category selection IDs for KNOWLEDGE libraries. Mutually exclusive with --data-category-names (provide one or the other, not both). | | ‑‑data‑category‑names | N/A | **Type:** Value

Comma-separated list of data category names in qualified format (e.g., "Group_API_Name.Category"). Mutually exclusive with --data-category-ids (provide one or the other, not both). | | ‑‑description | N/A | **Type:** Value

Description of the data library (max 255 characters). | | ‑‑developer‑name | N/A | **Type:** Value
**Required**

API name for the data library (max 80 characters, alphanumeric and underscores only, must start with a letter). | | ‑‑flags‑dir | N/A | **Type:** Value

Import flag values from a directory. | | ‑‑index‑mode | N/A | **Type:** Value
**Valid Values:** `basic`, `enhanced`

Index mode for SFDRIVE libraries: basic or enhanced. | | ‑‑json | N/A | **Type:** Boolean

Format output as json. | | ‑‑name | ‑n | **Type:** Value
**Required**

Display name for the data library (max 80 characters). | | ‑‑primary‑index‑field1 | N/A | **Type:** Value

Primary index field 1 for KNOWLEDGE libraries (required, immutable after creation). | | ‑‑primary‑index‑field2 | N/A | **Type:** Value

Primary index field 2 for KNOWLEDGE libraries (required, immutable after creation). | | ‑‑retriever‑id | N/A | **Type:** Value

ID of an active Custom Retriever (required for RETRIEVER source type; retriever must be active). | | ‑‑source‑type | N/A | **Type:** Value
**Required**
**Valid Values:** `sfdrive`, `knowledge`, `retriever`

Type of grounding source: sfdrive (file upload), knowledge (Salesforce Knowledge articles), or retriever (existing active Custom Retriever). | | ‑‑target‑org | ‑o | **Type:** Value
**Required**

Username or alias of the target org. Not required if the `target-org` configuration variable is already set. | | ‑‑wait | ‑w | **Type:** Value

Wait N minutes for indexing to complete (KNOWLEDGE libraries). SFDRIVE libraries require upload before indexing; RETRIEVER libraries are ready immediately. | ## Examples for agent adl create Create an SFDRIVE library: ```shell sf agent adl create --target-org myOrg --name "My Docs" --developer-name My_Docs --source-type sfdrive ``` Create a KNOWLEDGE library with index fields: ```shell sf agent adl create --target-org myOrg --name "KB Library" --developer-name KB_Library --source-type knowledge --primary-index-field1 Title --primary-index-field2 Summary ``` Create a RETRIEVER library: ```shell sf agent adl create --target-org myOrg --name "Existing Retriever" --developer-name Existing_Retriever --source-type retriever --retriever-id 0ppXX0000000001 ``` # agent adl delete Delete an Agentforce Data Library. ## Description for agent adl delete Permanently deletes a data library and all associated files and indexing data. ## Flags | Flag Name (Long) | Flag Name (Short) | Description | |------------------|-------------------|-------------| | ‑‑api‑version | N/A | **Type:** Value

Override the api version used for api requests made by this command | | ‑‑flags‑dir | N/A | **Type:** Value

Import flag values from a directory. | | ‑‑json | N/A | **Type:** Boolean

Format output as json. | | ‑‑library‑id | ‑i | **Type:** Value
**Required**

Agentforce Data Library ID (18-char Salesforce ID with prefix 1JD). | | ‑‑target‑org | ‑o | **Type:** Value
**Required**

Username or alias of the target org. Not required if the `target-org` configuration variable is already set. | ## Examples for agent adl delete Delete a data library: ```shell sf agent adl delete --library-id 1JDSG000007IbWX4A0 --target-org myOrg ``` # agent adl file add Add files to an existing Agentforce Data Library. ## Description for agent adl file add Adds one or more files to an existing SFDRIVE data library and triggers SearchIndex re-hydration. This is the day-2 operation for adding files to an already-provisioned library. Adds files to an existing READY library. Unlike `sf agent adl upload`, this does NOT create new downstream Data Cloud assets — it appends files to the existing SearchIndex and triggers re-indexing. Constraints: at least 1 file required, no duplicate file names in a batch, maximum 1000 files per library. ## Flags | Flag Name (Long) | Flag Name (Short) | Description | |------------------|-------------------|-------------| | ‑‑api‑version | N/A | **Type:** Value

Override the api version used for api requests made by this command | | ‑‑flags‑dir | N/A | **Type:** Value

Import flag values from a directory. | | ‑‑json | N/A | **Type:** Boolean

Format output as json. | | ‑‑library‑id | ‑i | **Type:** Value
**Required**

Agentforce Data Library ID (18-char Salesforce ID with prefix 1JD). | | ‑‑path | ‑f | **Type:** Value
**Required**

Path to file(s) to add. Specify multiple times for batch upload. | | ‑‑target‑org | ‑o | **Type:** Value
**Required**

Username or alias of the target org. Not required if the `target-org` configuration variable is already set. | ## Examples for agent adl file add Add a file to an existing library: ```shell sf agent adl file add -i 1JDSG000007IbWX4A0 --path ./docs/new-guide.pdf --target-org myOrg ``` Add multiple files: ```shell sf agent adl file add -i 1JDSG000007IbWX4A0 --path ./docs/guide.pdf --path ./docs/faq.txt --target-org myOrg ``` # agent adl file delete Delete a file from an Agentforce Data Library. ## Description for agent adl file delete Permanently removes a file from an SFDRIVE data library and triggers re-indexing of the search index. ## Flags | Flag Name (Long) | Flag Name (Short) | Description | |------------------|-------------------|-------------| | ‑‑api‑version | N/A | **Type:** Value

Override the api version used for api requests made by this command | | ‑‑file‑id | N/A | **Type:** Value
**Required**

ID of the file to delete (AiGroundingFileRef record ID). | | ‑‑flags‑dir | N/A | **Type:** Value

Import flag values from a directory. | | ‑‑json | N/A | **Type:** Boolean

Format output as json. | | ‑‑library‑id | ‑i | **Type:** Value
**Required**

Agentforce Data Library ID (18-char Salesforce ID with prefix 1JD). | | ‑‑target‑org | ‑o | **Type:** Value
**Required**

Username or alias of the target org. Not required if the `target-org` configuration variable is already set. | ## Examples for agent adl file delete Delete a file from a data library: ```shell sf agent adl file delete --library-id 1JDSG000007IbWX4A0 --file-id a1B2C3D4E5F6G7H8I9 --target-org myOrg ``` # agent adl file list List files in an Agentforce Data Library. ## Description for agent adl file list Returns the list of files in an SFDRIVE library including file name, size, and creation date. ## Flags | Flag Name (Long) | Flag Name (Short) | Description | |------------------|-------------------|-------------| | ‑‑api‑version | N/A | **Type:** Value

Override the api version used for api requests made by this command | | ‑‑flags‑dir | N/A | **Type:** Value

Import flag values from a directory. | | ‑‑json | N/A | **Type:** Boolean

Format output as json. | | ‑‑library‑id | ‑i | **Type:** Value
**Required**

Agentforce Data Library ID (18-char Salesforce ID with prefix 1JD). | | ‑‑offset | N/A | **Type:** Value

Number of files to skip before returning results (for pagination). | | ‑‑page‑size | N/A | **Type:** Value
**Default value:** `50`

Number of files to return per page (1-200, default 50). | | ‑‑status | N/A | **Type:** Value
**Valid Values:** `uploaded`, `indexing`, `indexed`, `index_failed`, `deleting`, `delete_failed`

Filter files by indexing status. | | ‑‑target‑org | ‑o | **Type:** Value
**Required**

Username or alias of the target org. Not required if the `target-org` configuration variable is already set. | ## Examples for agent adl file list List files in a data library: ```shell sf agent adl file list --library-id 1JDSG000007IbWX4A0 --target-org myOrg ``` List files and output as JSON: ```shell sf agent adl file list --library-id 1JDSG000007IbWX4A0 --target-org myOrg --json ``` # agent adl get Get details of an Agentforce Data Library. ## Description for agent adl get Returns the full detail of a data library including its grounding source configuration, status, and retriever ID. ## Flags | Flag Name (Long) | Flag Name (Short) | Description | |------------------|-------------------|-------------| | ‑‑api‑version | N/A | **Type:** Value

Override the api version used for api requests made by this command | | ‑‑flags‑dir | N/A | **Type:** Value

Import flag values from a directory. | | ‑‑json | N/A | **Type:** Boolean

Format output as json. | | ‑‑library‑id | ‑i | **Type:** Value
**Required**

Agentforce Data Library ID (18-char Salesforce ID with prefix 1JD). | | ‑‑target‑org | ‑o | **Type:** Value
**Required**

Username or alias of the target org. Not required if the `target-org` configuration variable is already set. | ## Examples for agent adl get Get details of a data library: ```shell sf agent adl get --library-id 1JDSG000007IbWX4A0 --target-org myOrg ``` # agent adl list List Agentforce Data Libraries in an org. ## Description for agent adl list Returns all data libraries in the target org, including their source type, status, and library ID. ## Flags | Flag Name (Long) | Flag Name (Short) | Description | |------------------|-------------------|-------------| | ‑‑api‑version | N/A | **Type:** Value

Override the api version used for api requests made by this command | | ‑‑flags‑dir | N/A | **Type:** Value

Import flag values from a directory. | | ‑‑json | N/A | **Type:** Boolean

Format output as json. | | ‑‑source‑type | N/A | **Type:** Value
**Valid Values:** `sfdrive`, `knowledge`, `retriever`

Filter by source type: sfdrive, knowledge, or retriever. | | ‑‑target‑org | ‑o | **Type:** Value
**Required**

Username or alias of the target org. Not required if the `target-org` configuration variable is already set. | ## Examples for agent adl list List all data libraries in the default target org: ```shell sf agent adl list --target-org myOrg ``` List data libraries and output as JSON: ```shell sf agent adl list --target-org myOrg --json ``` # agent adl status Get indexing status of an Agentforce Data Library. ## Description for agent adl status Returns the current indexing status including stage details (DATA_STREAM, DATA_LAKE_OBJECT, DATA_MODEL_OBJECT, SEARCH_INDEX, RETRIEVER) and any errors. ## Flags | Flag Name (Long) | Flag Name (Short) | Description | |------------------|-------------------|-------------| | ‑‑api‑version | N/A | **Type:** Value

Override the api version used for api requests made by this command | | ‑‑flags‑dir | N/A | **Type:** Value

Import flag values from a directory. | | ‑‑include‑artifacts | N/A | **Type:** Boolean

Resolve DC asset artifacts (DataStream, DLO, DMO, SearchIndex, Retriever) with entity IDs and names on each stage. Slower — requires additional queries. | | ‑‑json | N/A | **Type:** Boolean

Format output as json. | | ‑‑library‑id | ‑i | **Type:** Value
**Required**

Agentforce Data Library ID (18-char Salesforce ID with prefix 1JD). | | ‑‑target‑org | ‑o | **Type:** Value
**Required**

Username or alias of the target org. Not required if the `target-org` configuration variable is already set. | ## Examples for agent adl status Get status of a data library: ```shell sf agent adl status --library-id 1JDSG000007IbWX4A0 --target-org myOrg ``` # agent adl update Update an Agentforce Data Library. ## Description for agent adl update Updates the label, description, or other mutable properties of an existing data library. ## Flags | Flag Name (Long) | Flag Name (Short) | Description | |------------------|-------------------|-------------| | ‑‑api‑version | N/A | **Type:** Value

Override the api version used for api requests made by this command | | ‑‑content‑fields | N/A | **Type:** Value

Comma-separated list of content fields for KNOWLEDGE libraries (triggers re-indexing). | | ‑‑data‑category‑rule | N/A | **Type:** Boolean

Enable or disable data category filtering for KNOWLEDGE libraries. Use --no-data-category-rule to disable. | | ‑‑description | N/A | **Type:** Value

New description for the data library (max 255 characters). | | ‑‑flags‑dir | N/A | **Type:** Value

Import flag values from a directory. | | ‑‑json | N/A | **Type:** Boolean

Format output as json. | | ‑‑library‑id | ‑i | **Type:** Value
**Required**

Agentforce Data Library ID (18-char Salesforce ID with prefix 1JD). | | ‑‑name | ‑n | **Type:** Value

New display name for the data library (max 80 characters). | | ‑‑restrict‑to‑public‑articles | N/A | **Type:** Boolean

Restrict to public Knowledge articles only (KNOWLEDGE libraries, triggers re-indexing). | | ‑‑retriever‑id | N/A | **Type:** Value

Swap the retriever for a RETRIEVER library (must be an active Custom Retriever ID). | | ‑‑target‑org | ‑o | **Type:** Value
**Required**

Username or alias of the target org. Not required if the `target-org` configuration variable is already set. | ## Examples for agent adl update Update the label of a data library: ```shell sf agent adl update --library-id 1JDSG000007IbWX4A0 --name "New Name" --target-org myOrg ``` Update the description: ```shell sf agent adl update --library-id 1JDSG000007IbWX4A0 --description "Updated description" --target-org myOrg ``` Update Knowledge library content fields (triggers re-indexing): ```shell sf agent adl update --library-id 1JDSG000007IbWX4A0 --content-fields "Answer**c,Summary**c" --target-org myOrg ``` Restrict Knowledge library to public articles: ```shell sf agent adl update --library-id 1JDSG000007IbWX4A0 --restrict-to-public-articles --target-org myOrg ``` # agent adl upload Upload a file to an SFDRIVE Agentforce Data Library. ## Description for agent adl upload Performs the multi-step upload workflow: checks upload readiness, obtains a pre-signed S3 URL, uploads the file, triggers indexing, and optionally polls until the library is ready (retrieverId is populated). Upload triggers the full Data Cloud provisioning pipeline, creating all downstream assets (DLO, DMO, SearchIndex, Retriever). Use `sf agent adl status` to monitor progress. For adding files to an already-provisioned library, use `sf agent adl file add` instead. This command only works with SFDRIVE libraries. KNOWLEDGE libraries index automatically after creation, and RETRIEVER libraries require no file upload. ## Flags | Flag Name (Long) | Flag Name (Short) | Description | |------------------|-------------------|-------------| | ‑‑api‑version | N/A | **Type:** Value

Override the api version used for api requests made by this command | | ‑‑file | ‑f | **Type:** Value
**Required**

Path to the file to upload. | | ‑‑flags‑dir | N/A | **Type:** Value

Import flag values from a directory. | | ‑‑json | N/A | **Type:** Boolean

Format output as json. | | ‑‑library‑id | ‑i | **Type:** Value
**Required**

Agentforce Data Library ID (18-char Salesforce ID with prefix 1JD). | | ‑‑target‑org | ‑o | **Type:** Value
**Required**

Username or alias of the target org. Not required if the `target-org` configuration variable is already set. | | ‑‑wait | ‑w | **Type:** Value

Number of minutes to wait for indexing to complete. If not specified, returns after triggering indexing. | ## Examples for agent adl upload Upload a file and wait for indexing to complete: ```shell sf agent adl upload --library-id 1JDSG000007IbWX4A0 --file ./docs/guide.pdf --target-org myOrg --wait 10 ``` Upload a file without waiting: ```shell sf agent adl upload --library-id 1JDSG000007IbWX4A0 --file ./docs/guide.pdf --target-org myOrg ``` # agent Commands Commands to work with agents. - **[agent activate](https://developer.salesforce.com/docs/platform/salesforce-cli-reference/guide/cli_reference_agent_activate.md)**
Activate an agent in an org. - **[agent adl create](https://developer.salesforce.com/docs/platform/salesforce-cli-reference/guide/cli_reference_agent_adl_create.md)**
Create an Agentforce Data Library. - **[agent adl delete](https://developer.salesforce.com/docs/platform/salesforce-cli-reference/guide/cli_reference_agent_adl_delete.md)**
Delete an Agentforce Data Library. - **[agent adl file add](https://developer.salesforce.com/docs/platform/salesforce-cli-reference/guide/cli_reference_agent_adl_file_add.md)**
Add files to an existing Agentforce Data Library. - **[agent adl file delete](https://developer.salesforce.com/docs/platform/salesforce-cli-reference/guide/cli_reference_agent_adl_file_delete.md)**
Delete a file from an Agentforce Data Library. - **[agent adl file list](https://developer.salesforce.com/docs/platform/salesforce-cli-reference/guide/cli_reference_agent_adl_file_list.md)**
List files in an Agentforce Data Library. - **[agent adl get](https://developer.salesforce.com/docs/platform/salesforce-cli-reference/guide/cli_reference_agent_adl_get.md)**
Get details of an Agentforce Data Library. - **[agent adl list](https://developer.salesforce.com/docs/platform/salesforce-cli-reference/guide/cli_reference_agent_adl_list.md)**
List Agentforce Data Libraries in an org. - **[agent adl status](https://developer.salesforce.com/docs/platform/salesforce-cli-reference/guide/cli_reference_agent_adl_status.md)**
Get indexing status of an Agentforce Data Library. - **[agent adl update](https://developer.salesforce.com/docs/platform/salesforce-cli-reference/guide/cli_reference_agent_adl_update.md)**
Update an Agentforce Data Library. - **[agent adl upload](https://developer.salesforce.com/docs/platform/salesforce-cli-reference/guide/cli_reference_agent_adl_upload.md)**
Upload a file to an SFDRIVE Agentforce Data Library. - **[agent create](https://developer.salesforce.com/docs/platform/salesforce-cli-reference/guide/cli_reference_agent_create.md)**
Create an agent in your org using a local agent spec file. - **[agent deactivate](https://developer.salesforce.com/docs/platform/salesforce-cli-reference/guide/cli_reference_agent_deactivate.md)**
Deactivate an agent in an org. - **[agent generate agent-spec](https://developer.salesforce.com/docs/platform/salesforce-cli-reference/guide/cli_reference_agent_generate_agent-spec.md)**
Generate an agent spec, which is a YAML file that captures what an agent can do. - **[agent generate authoring-bundle](https://developer.salesforce.com/docs/platform/salesforce-cli-reference/guide/cli_reference_agent_generate_authoring-bundle.md)**
Generate an authoring bundle from an existing agent spec YAML file. - **[agent generate template](https://developer.salesforce.com/docs/platform/salesforce-cli-reference/guide/cli_reference_agent_generate_template.md)**
Generate an agent template from an existing agent in your DX project so you can then package the template in a second-generation managed package. - **[agent generate test-spec](https://developer.salesforce.com/docs/platform/salesforce-cli-reference/guide/cli_reference_agent_generate_test-spec.md)**
Generate an agent test spec, which is a YAML file that lists the test cases for testing a specific agent. - **[agent mcp asset list (Developer Preview)](https://developer.salesforce.com/docs/platform/salesforce-cli-reference/guide/cli_reference_agent_mcp_asset_list.md)**
List the assets (tools, prompts, and resources) for an MCP server in the catalog. - **[agent mcp asset replace (Developer Preview)](https://developer.salesforce.com/docs/platform/salesforce-cli-reference/guide/cli_reference_agent_mcp_asset_replace.md)**
Replace the asset set of an MCP server in the API Catalog. - **[agent mcp create (Developer Preview)](https://developer.salesforce.com/docs/platform/salesforce-cli-reference/guide/cli_reference_agent_mcp_create.md)**
Create an MCP server in the API Catalog. - **[agent mcp delete (Developer Preview)](https://developer.salesforce.com/docs/platform/salesforce-cli-reference/guide/cli_reference_agent_mcp_delete.md)**
Delete an MCP server from the API Catalog. - **[agent mcp fetch (Developer Preview)](https://developer.salesforce.com/docs/platform/salesforce-cli-reference/guide/cli_reference_agent_mcp_fetch.md)**
Fetch the live assets (tools, prompts, resources) advertised by an MCP server. - **[agent mcp get (Developer Preview)](https://developer.salesforce.com/docs/platform/salesforce-cli-reference/guide/cli_reference_agent_mcp_get.md)**
Get a single MCP server registered in the API Catalog. - **[agent mcp list (Developer Preview)](https://developer.salesforce.com/docs/platform/salesforce-cli-reference/guide/cli_reference_agent_mcp_list.md)**
List the MCP servers registered in the API Catalog. - **[agent mcp update (Developer Preview)](https://developer.salesforce.com/docs/platform/salesforce-cli-reference/guide/cli_reference_agent_mcp_update.md)**
Update an MCP server registered in the API Catalog. - **[agent preview](https://developer.salesforce.com/docs/platform/salesforce-cli-reference/guide/cli_reference_agent_preview.md)**
Interact with an agent to preview how it responds to your statements, questions, and commands (utterances). - **[agent preview end](https://developer.salesforce.com/docs/platform/salesforce-cli-reference/guide/cli_reference_agent_preview_end.md)**
End an existing programmatic agent preview session and get trace location. - **[agent preview send](https://developer.salesforce.com/docs/platform/salesforce-cli-reference/guide/cli_reference_agent_preview_send.md)**
Send a message to an existing agent preview session. - **[agent preview sessions](https://developer.salesforce.com/docs/platform/salesforce-cli-reference/guide/cli_reference_agent_preview_sessions.md)**
List all known programmatic agent preview sessions. - **[agent preview start](https://developer.salesforce.com/docs/platform/salesforce-cli-reference/guide/cli_reference_agent_preview_start.md)**
Start a programmatic agent preview session. - **[agent publish authoring-bundle](https://developer.salesforce.com/docs/platform/salesforce-cli-reference/guide/cli_reference_agent_publish_authoring-bundle.md)**
Publish an authoring bundle to your org, which results in a new agent or a new version of an existing agent. - **[agent test create](https://developer.salesforce.com/docs/platform/salesforce-cli-reference/guide/cli_reference_agent_test_create.md)**
Create an agent test in your org using a local test spec YAML file. - **[agent test list](https://developer.salesforce.com/docs/platform/salesforce-cli-reference/guide/cli_reference_agent_test_list.md)**
List the available agent tests in your org. - **[agent test results](https://developer.salesforce.com/docs/platform/salesforce-cli-reference/guide/cli_reference_agent_test_results.md)**
Get the results of a completed agent test run. - **[agent test resume](https://developer.salesforce.com/docs/platform/salesforce-cli-reference/guide/cli_reference_agent_test_resume.md)**
Resume an agent test that you previously started in your org so you can view the test results. - **[agent test run](https://developer.salesforce.com/docs/platform/salesforce-cli-reference/guide/cli_reference_agent_test_run.md)**
Start an agent test in your org. - **[agent test run-eval (Beta)](https://developer.salesforce.com/docs/platform/salesforce-cli-reference/guide/cli_reference_agent_test_run-eval.md)**
Run rich evaluation tests against an Agentforce agent. - **[agent trace delete](https://developer.salesforce.com/docs/platform/salesforce-cli-reference/guide/cli_reference_agent_trace_delete.md)**
Delete trace files from an agent preview session. - **[agent trace list](https://developer.salesforce.com/docs/platform/salesforce-cli-reference/guide/cli_reference_agent_trace_list.md)**
List the available trace files that were recorded during all agent preview sessions. - **[agent trace read](https://developer.salesforce.com/docs/platform/salesforce-cli-reference/guide/cli_reference_agent_trace_read.md)**
Read trace files from an agent preview session. - **[agent validate authoring-bundle](https://developer.salesforce.com/docs/platform/salesforce-cli-reference/guide/cli_reference_agent_validate_authoring-bundle.md)**
Validate an authoring bundle to ensure its Agent Script file compiles successfully and can be used to publish an agent. # agent create Create an agent in your org using a local agent spec file. ## Description for agent create NOTE: This command creates an agent that doesn't use Agent Script as its blueprint. We generally don't recommend you use this workflow to create an agent. Rather, use the "agent generate|validate|publish authoring-bundle" commands to author agents that use the Agent Script language. See "Author an Agent" (https://developer.salesforce.com/docs/einstein/genai/guide/agent-dx-nga-author-agent.html) for details. To run this command, you must have an agent spec file, which is a YAML file that define the agent properties and contains a list of AI-generated topics. Topics define the range of jobs the agent can handle. Use the "agent generate agent-spec" CLI command to generate an agent spec file. Then specify the file to this command using the --spec flag, along with the name (label) of the new agent with the --name flag. If you don't specify any of the required flags, the command prompts you. When this command completes, your org contains the new agent, which you can then edit and customize in the Agent Builder UI. The new agent's topics are the same as the ones listed in the agent spec file. The agent might also have some AI-generated actions, or you can add them. This command also retrieves all the metadata files associated with the new agent to your local Salesforce DX project. Use the --preview flag to review what the agent looks like without actually saving it in your org. When previewing, the command creates a JSON file in the current directory with all the agent details. The name of the JSON file is the agent's API name and a timestamp. To open the new agent in your org's Agent Builder UI, run this command: "sf org open agent --api-name <api-name>". ## Flags | Flag Name (Long) | Flag Name (Short) | Description | |------------------|-------------------|-------------| | ‑‑api‑name | N/A | **Type:** Value

API name of the new agent; if not specified, the API name is derived from the agent name (label); the API name must not exist in the org. | | ‑‑api‑version | N/A | **Type:** Value

Override the api version used for api requests made by this command | | ‑‑flags‑dir | N/A | **Type:** Value

Import flag values from a directory. | | ‑‑json | N/A | **Type:** Boolean

Format output as json. | | ‑‑name | N/A | **Type:** Value

Name (label) of the new agent. | | ‑‑preview | N/A | **Type:** Boolean

Preview the agent without saving it in your org. | | ‑‑spec | N/A | **Type:** Value

Path to an agent spec file. | | ‑‑target‑org | ‑o | **Type:** Value
**Required**

Username or alias of the target org. Not required if the `target-org` configuration variable is already set. | ## Examples for agent create Create an agent by being prompted for the required information, such as the agent spec file and agent name, and then create it in your default org: ```shell sf agent create ``` Create an agent by specifying the agent name, API name, and spec file with flags; use the org with alias "my-org"; the command fails if the API name is already being used in your org: ```shell sf agent create --name "Resort Manager" --api-name Resort_Manager --spec specs/resortManagerAgent.yaml --target-org my-org ``` Preview the creation of an agent named "Resort Manager" and use your default org: ```shell sf agent create --name "Resort Manager" --spec specs/resortManagerAgent.yaml --preview ``` # agent deactivate Deactivate an agent in an org. ## Description for agent deactivate Deactivating an agent makes it unavailable to your users. To make changes to an agent, such as adding or removing topics or actions, you must deactivate it. You can't preview an agent with the "agent preview" CLI command or VS Code if it's deactivated. If you run the command without the --api-name flag, the command provides a list of agent API names for you to choose from. Use the flag to specify the exact agent without being prompted. ## Flags | Flag Name (Long) | Flag Name (Short) | Description | |------------------|-------------------|-------------| | ‑‑api‑name | ‑n | **Type:** Value

API name of the agent to deactivate; if not specified, the command provides a list that you choose from. | | ‑‑api‑version | N/A | **Type:** Value

Override the api version used for api requests made by this command | | ‑‑flags‑dir | N/A | **Type:** Value

Import flag values from a directory. | | ‑‑json | N/A | **Type:** Boolean

Format output as json. | | ‑‑target‑org | ‑o | **Type:** Value
**Required**

Username or alias of the target org. Not required if the `target-org` configuration variable is already set. | ## Examples for agent deactivate Deactivate an agent in your default target org by being prompted: ```shell sf agent deactivate ``` Deactivate the agent Resort_Manager in the org with alias "my_org": ```shell sf agent deactivate --api-name Resort_Manager --target-org my-org ``` # agent generate agent-spec Generate an agent spec, which is a YAML file that captures what an agent can do. ## Description for agent generate agent-spec An agent spec is a YAML-formatted file that contains basic information about the agent, such as its role, company description, and an AI-generated list of topics based on this information. Topics define the range of jobs your agent can handle. Use flags, such as --role and --company-description, to provide details about your company and the role that the agent plays in your company. If you prefer, you can also be prompted for the basic information; use --full-interview to be prompted for all required and optional properties. Upon command execution, the large language model (LLM) associated with your org uses the provided information to generate a list of topics for the agent. Because the LLM uses the company and role information to generate the topics, we recommend that you provide accurate, complete, and specific details so the LLM generates the best and most relevant topics. Once generated, you can edit the spec file; for example, you can remove topics that don't apply or change a topic's description. You can also iterate the spec generation process by using the --spec flag to pass an existing agent spec file to this command, and then using the --role, --company-description, etc, flags to refine your agent properties. Iteratively improving the description of your agent allows the LLM to generate progressively better topics. You can also specify other agent properties, such as a custom prompt template, how to ground the prompt template to add context to the agent's prompts, the tone of the prompts, and the username of a user in the org to assign to the agent. When your agent spec is ready, generate an authoring bundle from it by passing the spec file to the --spec flag of the "agent generate authoring-bundle" CLI command. An authoring bundle is a metadata type that contains an Agent Script file, which is the blueprint for an agent. (While not recommended, you can also use the agent spec file to immediately create an agent with the "agent create" command. We don't recommend this workflow because these types of agents don't use Agent Script, and are thus less flexible and more difficult to maintain.) ## Flags | Flag Name (Long) | Flag Name (Short) | Description | |------------------|-------------------|-------------| | ‑‑agent‑user | N/A | **Type:** Value

Username of a user in your org to assign to your agent; determines what your agent can access and do. | | ‑‑api‑version | N/A | **Type:** Value

Override the api version used for api requests made by this command | | ‑‑company‑description | N/A | **Type:** Value

Description of your company. | | ‑‑company‑name | N/A | **Type:** Value

Name of your company. | | ‑‑company‑website | N/A | **Type:** Value

Website URL of your company. | | ‑‑enrich‑logs | N/A | **Type:** Value
**Valid Values:** `true`, `false`

Adds agent conversation data to event logs so you can view all agent session activity in one place. | | ‑‑flags‑dir | N/A | **Type:** Value

Import flag values from a directory. | | ‑‑force‑overwrite | N/A | **Type:** Boolean

Don't prompt the user to confirm that an existing spec file will be overwritten. | | ‑‑full‑interview | N/A | **Type:** Boolean

Prompt for both required and optional flags. | | ‑‑grounding‑context | N/A | **Type:** Value

Context information and personalization that's added to your prompts when using a custom prompt template. | | ‑‑json | N/A | **Type:** Boolean

Format output as json. | | ‑‑max‑topics | N/A | **Type:** Value

Maximum number of topics to generate in the agent spec; default is 5. | | ‑‑output‑file | N/A | **Type:** Value
**Default value:** `specs/agentSpec.yaml`

Path for the generated YAML agent spec file; can be an absolute or relative path. | | ‑‑prompt‑template | N/A | **Type:** Value

API name of a customized prompt template to use instead of the default prompt template. | | ‑‑role | N/A | **Type:** Value

Role of the agent. | | ‑‑spec | N/A | **Type:** Value

Agent spec file, in YAML format, to use as input to the command. | | ‑‑target‑org | ‑o | **Type:** Value
**Required**

Username or alias of the target org. Not required if the `target-org` configuration variable is already set. | | ‑‑tone | N/A | **Type:** Value
**Valid Values:** `formal`, `casual`, `neutral`

Conversational style of the agent, such as how it expresses your brand personality in its messages through word choice, punctuation, and sentence structure. | | ‑‑type | N/A | **Type:** Value
**Valid Values:** `customer`, `internal`

Type of agent to create. Internal types are copilots used internally by your company and customer types are the agents you create for your customers. | ## Examples for agent generate agent-spec Generate an agent spec in the default location and use flags to specify the agent properties, such as its role and your company details; use your default org: ```shell sf agent generate agent-spec --type customer --role "Field customer complaints and manage employee schedules." --company-name "Coral Cloud Resorts" --company-description "Provide customers with exceptional destination activities, unforgettable experiences, and reservation services." ``` Generate an agent spec by being prompted for the required agent properties and generate a maxiumum of 5 topics; write the generated file to the "specs/resortManagerSpec.yaml" file and use the org with alias "my-org": ```shell sf agent generate agent-spec --max-topics 5 --output-file specs/resortManagerAgent.yaml --target-org my-org ``` Be prompted for all required and optional agent properties; use your default org: ```shell sf agent generate agent-spec --full-interview ``` Specify an existing agent spec file called "specs/resortManagerAgent.yaml", and then overwrite it with a new version that contains newly AI-generated topics based on the updated role information passed in with the --role flag: ```shell sf agent generate agent-spec --spec specs/resortManagerAgent.yaml --output-file specs/resortManagerAgent.yaml --role "Field customer complaints, manage employee schedules, and ensure all resort operations are running smoothly" ``` Specify that the conversational tone of the agent is formal and to attach the "resortmanager@myorg.com" username to it; be prompted for the required properties and use your default org: ```shell sf agent generate agent-spec --tone formal --agent-user resortmanager@myorg.com ``` # agent generate authoring-bundle Generate an authoring bundle from an existing agent spec YAML file. ## Description for agent generate authoring-bundle Authoring bundles are metadata components that contain an agent's Agent Script file. The Agent Script file is the agent's blueprint; it fully describes what the agent can do using the Agent Script language. Use this command to generate a new authoring bundle based on an agent spec YAML file, which you create with the "agent generate agent-spec" command. The agent spec YAML file is a high-level description of the agent; it describes its essence rather than exactly what it can do. The resulting Agent Script file is customized to reflect what's in the agent spec file. You can also create an authoring bundle without an agent spec file by specifying the "--no-spec" flag; in this case, the resulting Agent Script file is just the default boilerplate. The metadata type for authoring bundles is aiAuthoringBundle, which consist of a standard "<bundle-api-name>.bundle-meta.xml" metadata file and the Agent Script file (with extension ".agent"). When you run this command, the new authoring bundle is generated in the force-app/main/default/aiAuthoringBundles/<bundle-api-name> directory. Use the --output-dir flag to generate them elsewhere. After you generate the initial authoring bundle, code the Agent Script file so your agent behaves exactly as you want. The Agent Script file generated by this command is just a first draft of your agent! Interactively test the agent by conversing with it using the "agent preview" command. Then publish the agent to your org with the "agent publish authoring-bundle" command. This command requires an org because it uses it to access an LLM for generating the Agent Script file. ## Flags | Flag Name (Long) | Flag Name (Short) | Description | |------------------|-------------------|-------------| | ‑‑api‑name | N/A | **Type:** Value

API name of the new authoring bundle; if not specified, the API name is derived from the authoring bundle name (label); the API name can't exist in the org. | | ‑‑api‑version | N/A | **Type:** Value

Override the api version used for api requests made by this command | | ‑‑flags‑dir | N/A | **Type:** Value

Import flag values from a directory. | | ‑‑force‑overwrite | N/A | **Type:** Boolean

Overwrite the existing authoring bundle if one with the same API name already exists locally. | | ‑‑json | N/A | **Type:** Boolean

Format output as json. | | ‑‑name | ‑n | **Type:** Value

Name (label) of the authoring bundle; if not specified, you're prompted for the name. | | ‑‑no‑spec | N/A | **Type:** Boolean

Skip prompting for an agent spec and use the default Agent Script boilerplate in the generated authoring bundle. | | ‑‑output‑dir | ‑d | **Type:** Value

Directory where the authoring bundle files are generated. | | ‑‑spec | ‑f | **Type:** Value

Path to the agent spec YAML file. If you don't specify the flag, the command provides a list that you can choose from. Use the --no-spec flag to skip using an agent spec entirely. | | ‑‑target‑org | ‑o | **Type:** Value
**Required**

Username or alias of the target org. Not required if the `target-org` configuration variable is already set. | ## Examples for agent generate authoring-bundle Generate an authoring bundle by being prompted for all required values, such as the agent spec YAML file, the bundle name, and the API name; use your default org: ```shell sf agent generate authoring-bundle ``` Generate an authoring bundle without using an agent spec file; give the bundle the label "My Authoring Bundle" and use your default org: ```shell sf agent generate authoring-bundle --no-spec --name "My Authoring Bundle" ``` Generate an authoring bundle from the "specs/agentSpec.yaml" agent spec YAML file and give it the label "My Authoring Bundle"; use your default org: ```shell sf agent generate authoring-bundle --spec specs/agentSpec.yaml --name "My Authoring Bundle" ``` Similar to previous example, but generate the authoring bundle files in the "other-package-dir/main/default" package directory; use the org with alias "my-dev-org": ```shell sf agent generate authoring-bundle --spec specs/agentSpec.yaml --name "My Authoring Bundle" --output-dir other-package-dir/main/default --target-org my-dev-org ``` # agent generate template Generate an agent template from an existing agent in your DX project so you can then package the template in a second-generation managed package. ## Description for agent generate template WARNING: This command doesn't work for agents that were created from an Agent Script file. In other words, you can't currently package an agent template for agents that use Agent Script. At a high-level, agents are defined by the Bot, BotVersion, and GenAiPlannerBundle metadata types. The GenAiPlannerBundle type in turn defines the agent's topics and actions. This command uses the metadata files for these three types, located in your local DX project, to generate a BotTemplate metadata file for a specific agent (Bot). You then use the BotTemplate metadata file, along with the GenAiPlannerBundle metadata file that references the BotTemplate, to package the template in a managed package that you can share between orgs or on AppExchange. Use the --agent-file flag to specify the relative or full pathname of the Bot metadata file, such as force-app/main/default/bots/My_Awesome_Agent/My_Awesome_Agent.bot-meta.xml. A single Bot can have multiple BotVersions, so use the --agent-version flag to specify the version. The corresponding BotVersion metadata file must exist locally. For example, if you specify "--agent-version 4", then the file force-app/main/default/bots/My_Awesome_Agent/v4.botVersion-meta.xml must exist. The new BotTemplate metadata file is generated in the "botTemplates" directory in the output directory specified with the --output-dir flag, and has the name <Agent_API_name>\_v<Version>\_Template.botTemplate-meta.xml, such as my-package/botTemplates/My_Awesome_Agent_v4_Template.botTemplate-meta.xml. The command displays the full pathname of the generated files when it completes. See "Develop and Package Agent Templates Using Scratch Orgs" (https://developer.salesforce.com/docs/atlas.en-us.pkg2_dev.meta/pkg2_dev/dev2gp_package_agent_templates.htm) for details about the complete process, which includes using a scratch org to create and test the agent, retrieving the agent metadata to your DX project, running this command to create the agent template, and then packaging the template. ## Flags | Flag Name (Long) | Flag Name (Short) | Description | |------------------|-------------------|-------------| | ‑‑agent‑file | ‑f | **Type:** Value
**Required**

Path to an agent (Bot) metadata file. | | ‑‑agent‑version | N/A | **Type:** Value
**Required**

Version of the agent (BotVersion). | | ‑‑api‑version | N/A | **Type:** Value

Override the api version used for api requests made by this command | | ‑‑flags‑dir | N/A | **Type:** Value

Import flag values from a directory. | | ‑‑json | N/A | **Type:** Boolean

Format output as json. | | ‑‑output‑dir | ‑r | **Type:** Value

Directory where the generated BotTemplate and GenAiPlannerBundle files are saved. | | ‑‑source‑org | ‑s | **Type:** Value
**Required**

Username or alias of the namespaced scratch org that contains the agent which this template is based on. | ## Examples for agent generate template Generate an agent template from the My_Awesome_Agent Bot metadata file in your DX project and save the BotTemplate and GenAiPlannerBundle to the specified directory; use version 1 of the agent. The agent that the template is based on is in the org with alias "my-scratch-org": ```shell sf agent generate template --agent-file force-app/main/default/bots/My_Awesome_Agent/My_Awesome_Agent.bot-meta.xml --agent-version 1 --output-dir my-package --source-org my-scratch-org ``` # agent generate test-spec Generate an agent test spec, which is a YAML file that lists the test cases for testing a specific agent. ## Description for agent generate test-spec The first step when using Salesforce CLI to create an agent test in your org is to use this interactive command to generate a local YAML-formatted test spec file. The test spec YAML file contains information about the agent being tested, such as its API name, and then one or more test cases. This command uses the metadata components in your DX project when prompting for information, such as the agent API name; it doesn't look in your org. To generate a specific agent test case, this command prompts you for this information; when possible, the command provides a list of options for you to choose from:
  • Utterance: Natural language statement, question, or command used to test the agent.
  • Expected topic: API name of the topic you expect the agent to use when responding to the utterance.
  • Expected actions: One or more API names of the expection actions the agent takes.
  • Expected outcome: Natural language description of the outcome you expect.
  • (Optional) Custom evaluation: Test an agent's response for specific strings or numbers.
  • (Optional) Conversation history: Boilerplate for additional context you can add to the test in the form of a conversation history.
You can manually add contextVariables to test cases in the generated YAML file to inject contextual data (such as CaseId or RoutableId) into agent sessions. This is useful for testing agent behavior with different contextual information. When your test spec is ready, you then run the "agent test create" command to actually create the test in your org and synchronize the metadata with your DX project. The metadata type for an agent test is `AiEvaluationDefinition` (legacy testing-center) or `AiTestingDefinition` (Agentforce Studio / NGT), selected via --test-runner. If you have an existing AiEvaluationDefinition or AiTestingDefinition metadata XML file in your DX project, you can generate its equivalent YAML test spec file with the --from-definition flag. The runner is inferred from the file extension; pass --test-runner to override. ## Flags | Flag Name (Long) | Flag Name (Short) | Description | |------------------|-------------------|-------------| | ‑‑flags‑dir | N/A | **Type:** Value

Import flag values from a directory. | | ‑‑force‑overwrite | N/A | **Type:** Boolean

Don't prompt for confirmation when overwriting an existing test spec YAML file. | | ‑‑from‑definition | ‑d | **Type:** Value

Filepath to an AiEvaluationDefinition or AiTestingDefinition metadata XML file in your DX project that you want to convert to a test spec YAML file. | | ‑‑output‑file | ‑f | **Type:** Value

Name of the generated test spec YAML file. Default value is "specs/<AGENT_API_NAME>-testSpec.yaml" (legacy) or "specs/<AGENT_API_NAME>-ngtTestSpec.yaml" (Agentforce Studio). | | ‑‑test‑runner | N/A | **Type:** Value
**Valid Values:** `agentforce-studio`, `testing-center`

Explicitly specify which test runner to use (agentforce-studio or testing-center).

By default, the command automatically detects which test runner to use based on the test definition metadata type in your org. Use this flag to explicitly specify the runner type. 'agentforce-studio' uses AiTestingDefinition metadata. 'testing-center' uses AiEvaluationDefinition metadata. | ## Examples for agent generate test-spec Generate an agent test spec YAML file interactively: ```shell sf agent generate test-spec ``` Generate an Agentforce Studio (NGT) test spec YAML file interactively: ```shell sf agent generate test-spec --test-runner agentforce-studio ``` Generate an agent test spec YAML file and specify a name for the new file; if the file exists, overwrite it without confirmation: ```shell sf agent generate test-spec --output-file specs/Resort_Manager-new-version-testSpec.yaml --force-overwrite ``` Generate an agent test spec YAML file from an existing AiEvaluationDefinition metadata XML file in your DX project: ```shell sf agent generate test-spec --from-definition force-app/main/default/aiEvaluationDefinitions/Resort_Manager_Tests.aiEvaluationDefinition-meta.xml ``` Generate an Agentforce Studio (NGT) test spec YAML file from an existing AiTestingDefinition metadata XML file: ```shell sf agent generate test-spec --from-definition force-app/main/default/aiTestingDefinitions/Returns_Checkout_Tests.aiTestingDefinition-meta.xml ``` # agent mcp asset list (Developer Preview) List the assets (tools, prompts, and resources) for an MCP server in the catalog. **note:** This command is available as a developer preview. The command isn't generally available unless or until Salesforce announces its general availability in documentation or in press releases or public statements. All commands, parameters, and other features are subject to change or deprecation at any time, with or without notice. Don't implement functionality developed with these commands or tools. ## Description for agent mcp asset list Returns the assets discovered for the specified MCP server, including each asset's kind (MCP_TOOL, MCP_PROMPT, or MCP_RESOURCE), whether it is active, and whether it is available as an agent action. ## Flags | Flag Name (Long) | Flag Name (Short) | Description | |------------------|-------------------|-------------| | ‑‑api‑version | N/A | **Type:** Value

Override the api version used for api requests made by this command | | ‑‑flags‑dir | N/A | **Type:** Value

Import flag values from a directory. | | ‑‑json | N/A | **Type:** Boolean

Format output as json. | | ‑‑mcp‑server‑id | ‑i | **Type:** Value
**Required**

The ID of the MCP server whose assets you want to list. | | ‑‑target‑org | ‑o | **Type:** Value
**Required**

Username or alias of the target org. Not required if the `target-org` configuration variable is already set. | ## Examples for agent mcp asset list List the assets for an MCP server in the default target org: ```shell sf agent mcp asset list --target-org myOrg --mcp-server-id 0XSxx0000000001 ``` List the assets for an MCP server and output as JSON: ```shell sf agent mcp asset list --target-org myOrg --mcp-server-id 0XSxx0000000001 --json ``` # agent mcp asset replace (Developer Preview) Replace the asset set of an MCP server in the API Catalog. **note:** This command is available as a developer preview. The command isn't generally available unless or until Salesforce announces its general availability in documentation or in press releases or public statements. All commands, parameters, and other features are subject to change or deprecation at any time, with or without notice. Don't implement functionality developed with these commands or tools. ## Description for agent mcp asset replace Replaces the full set of assets (tools, prompts, resources) for an MCP server with the asset items you supply. Provide the assets either inline with `--assets` (a JSON string, or `-` to read from stdin) or from a file with `--assets-file`. The JSON must be either an array of asset items or an object of the form `{ "assets": [...] }`. Each asset item may include `id`, `name`, `label`, `description`, `active`, and `kind`. This is a full replacement: existing assets not present in the supplied set are removed, so provide the complete desired asset set (read the current set first with `agent mcp asset list` or `agent mcp fetch`). ## Flags | Flag Name (Long) | Flag Name (Short) | Description | |------------------|-------------------|-------------| | ‑‑api‑version | N/A | **Type:** Value

Override the api version used for api requests made by this command | | ‑‑assets | N/A | **Type:** Value

The desired asset allowlist as a JSON string (or "-" to read from stdin). Mutually exclusive with --assets-file. | | ‑‑assets‑file | N/A | **Type:** Value

Path to a JSON file containing the desired asset allowlist. Mutually exclusive with --assets. | | ‑‑flags‑dir | N/A | **Type:** Value

Import flag values from a directory. | | ‑‑json | N/A | **Type:** Boolean

Format output as json. | | ‑‑mcp‑server‑id | ‑i | **Type:** Value
**Required**

ID of the MCP server whose assets you want to replace. | | ‑‑target‑org | ‑o | **Type:** Value
**Required**

Username or alias of the target org. Not required if the `target-org` configuration variable is already set. | ## Examples for agent mcp asset replace Replace the assets inline with a JSON string: ```shell sf agent mcp asset replace --mcp-server-id 0XSxx0000000001 --assets '{"assets":[{"name":"McpTool__add","active":true}]}' --target-org myOrg ``` Replace the assets from a JSON file: ```shell sf agent mcp asset replace --mcp-server-id 0XSxx0000000001 --assets-file ./assets.json --target-org myOrg ``` Pipe the assets from stdin: ```shell cat assets.json | sf agent mcp asset replace --mcp-server-id 0XSxx0000000001 --assets - --target-org myOrg ``` # agent mcp create (Developer Preview) Create an MCP server in the API Catalog. **note:** This command is available as a developer preview. The command isn't generally available unless or until Salesforce announces its general availability in documentation or in press releases or public statements. All commands, parameters, and other features are subject to change or deprecation at any time, with or without notice. Don't implement functionality developed with these commands or tools. ## Description for agent mcp create Registers an external Model Context Protocol (MCP) server with the API Catalog and discovers its assets (tools, prompts, and resources). Provide the server URL and, when the server requires it, OAuth authorization details. When the authorization type is OAUTH you must supply the identity provider, client ID, client secret, and scope. ## Flags | Flag Name (Long) | Flag Name (Short) | Description | |------------------|-------------------|-------------| | ‑‑api‑version | N/A | **Type:** Value

Override the api version used for api requests made by this command | | ‑‑auth‑type | N/A | **Type:** Value
**Valid Values:** `OAUTH`, `NO_AUTH`
**Default value:** `NO_AUTH`

Authorization type to use when connecting to the MCP server. | | ‑‑client‑id | N/A | **Type:** Value

OAuth client ID. Required when auth-type is OAUTH. | | ‑‑client‑secret | N/A | **Type:** Value

OAuth client secret. Required when auth-type is OAUTH. Pass "-" to read it from stdin (piped) and keep it out of shell history. | | ‑‑description | N/A | **Type:** Value

Description of the MCP server. | | ‑‑flags‑dir | N/A | **Type:** Value

Import flag values from a directory. | | ‑‑identity‑provider | N/A | **Type:** Value

Identity provider to use for OAuth authorization. Required when auth-type is OAUTH. | | ‑‑json | N/A | **Type:** Boolean

Format output as json. | | ‑‑label | N/A | **Type:** Value

Human-readable label for the MCP server. | | ‑‑name | ‑n | **Type:** Value
**Required**

Unique name of the MCP server. | | ‑‑scope | N/A | **Type:** Value

OAuth scope to request. Required when auth-type is OAUTH. | | ‑‑server‑url | N/A | **Type:** Value
**Required**

URL of the external MCP server. | | ‑‑target‑org | ‑o | **Type:** Value
**Required**

Username or alias of the target org. Not required if the `target-org` configuration variable is already set. | ## Examples for agent mcp create Create an MCP server with no authentication: ```shell sf agent mcp create --name myServer --server-url https://mcp.example.com --target-org myOrg ``` Create an MCP server that uses OAuth authentication, piping the client secret from stdin to keep it out of shell history: ```shell cat secret.txt | sf agent mcp create --name myServer --server-url https://mcp.example.com --auth-type OAUTH --identity-provider myIdp --client-id abc123 --client-secret - --scope "read write" --target-org myOrg ``` # agent mcp delete (Developer Preview) Delete an MCP server from the API Catalog. **note:** This command is available as a developer preview. The command isn't generally available unless or until Salesforce announces its general availability in documentation or in press releases or public statements. All commands, parameters, and other features are subject to change or deprecation at any time, with or without notice. Don't implement functionality developed with these commands or tools. ## Description for agent mcp delete Permanently removes an MCP (Model Context Protocol) server registration from the API Catalog, identified by its ID. By default you are prompted to confirm the deletion; pass --no-prompt to skip the confirmation (for example in scripts and CI). ## Flags | Flag Name (Long) | Flag Name (Short) | Description | |------------------|-------------------|-------------| | ‑‑api‑version | N/A | **Type:** Value

Override the api version used for api requests made by this command | | ‑‑flags‑dir | N/A | **Type:** Value

Import flag values from a directory. | | ‑‑json | N/A | **Type:** Boolean

Format output as json. | | ‑‑mcp‑server‑id | ‑i | **Type:** Value
**Required**

ID of the MCP server to delete. | | ‑‑no‑prompt | N/A | **Type:** Boolean

Skip the confirmation prompt and delete the MCP server immediately. | | ‑‑target‑org | ‑o | **Type:** Value
**Required**

Username or alias of the target org. Not required if the `target-org` configuration variable is already set. | ## Examples for agent mcp delete Delete an MCP server, confirming interactively: ```shell sf agent mcp delete --mcp-server-id 0XSxx0000000001 --target-org myOrg ``` Delete an MCP server without a confirmation prompt: ```shell sf agent mcp delete --mcp-server-id 0XSxx0000000001 --target-org myOrg --no-prompt ``` # agent mcp fetch (Developer Preview) Fetch the live assets (tools, prompts, resources) advertised by an MCP server. **note:** This command is available as a developer preview. The command isn't generally available unless or until Salesforce announces its general availability in documentation or in press releases or public statements. All commands, parameters, and other features are subject to change or deprecation at any time, with or without notice. Don't implement functionality developed with these commands or tools. ## Description for agent mcp fetch Performs a live fetch against the configured MCP server identified by its ID, returning the assets (MCP tools, prompts, and resources) it currently advertises along with their status and activation state. Use this to refresh the view of what an MCP server exposes before activating its assets as agent actions. ## Flags | Flag Name (Long) | Flag Name (Short) | Description | |------------------|-------------------|-------------| | ‑‑api‑version | N/A | **Type:** Value

Override the api version used for api requests made by this command | | ‑‑flags‑dir | N/A | **Type:** Value

Import flag values from a directory. | | ‑‑json | N/A | **Type:** Boolean

Format output as json. | | ‑‑mcp‑server‑id | ‑i | **Type:** Value
**Required**

ID of the MCP server to fetch assets from. | | ‑‑target‑org | ‑o | **Type:** Value
**Required**

Username or alias of the target org. Not required if the `target-org` configuration variable is already set. | ## Examples for agent mcp fetch Fetch the assets advertised by an MCP server in the default target org: ```shell sf agent mcp fetch --target-org myOrg --mcp-server-id 0XSxx0000000001 ``` Fetch MCP server assets and output as JSON: ```shell sf agent mcp fetch --target-org myOrg --mcp-server-id 0XSxx0000000001 --json ``` # agent mcp get (Developer Preview) Get a single MCP server registered in the API Catalog. **note:** This command is available as a developer preview. The command isn't generally available unless or until Salesforce announces its general availability in documentation or in press releases or public statements. All commands, parameters, and other features are subject to change or deprecation at any time, with or without notice. Don't implement functionality developed with these commands or tools. ## Description for agent mcp get Retrieves the details of an MCP (Model Context Protocol) server by its identifier, including its name, label, type, status, and server URL. ## Flags | Flag Name (Long) | Flag Name (Short) | Description | |------------------|-------------------|-------------| | ‑‑api‑version | N/A | **Type:** Value

Override the api version used for api requests made by this command | | ‑‑flags‑dir | N/A | **Type:** Value

Import flag values from a directory. | | ‑‑json | N/A | **Type:** Boolean

Format output as json. | | ‑‑mcp‑server‑id | ‑i | **Type:** Value
**Required**

The identifier of the MCP server to retrieve. | | ‑‑target‑org | ‑o | **Type:** Value
**Required**

Username or alias of the target org. Not required if the `target-org` configuration variable is already set. | ## Examples for agent mcp get Get an MCP server by id in the default target org: ```shell sf agent mcp get --target-org myOrg --mcp-server-id 0Mx000000000001 ``` Get an MCP server and output as JSON: ```shell sf agent mcp get --target-org myOrg --mcp-server-id 0Mx000000000001 --json ``` # agent mcp list (Developer Preview) List the MCP servers registered in the API Catalog. **note:** This command is available as a developer preview. The command isn't generally available unless or until Salesforce announces its general availability in documentation or in press releases or public statements. All commands, parameters, and other features are subject to change or deprecation at any time, with or without notice. Don't implement functionality developed with these commands or tools. ## Description for agent mcp list Returns the Model Context Protocol (MCP) servers registered in the API Catalog, optionally filtered by label, type, or status. Use this to discover which MCP servers are available and inspect their server URLs and current status. ## Flags | Flag Name (Long) | Flag Name (Short) | Description | |------------------|-------------------|-------------| | ‑‑api‑version | N/A | **Type:** Value

Override the api version used for api requests made by this command | | ‑‑flags‑dir | N/A | **Type:** Value

Import flag values from a directory. | | ‑‑json | N/A | **Type:** Boolean

Format output as json. | | ‑‑label | N/A | **Type:** Value

Filter the MCP servers by label. | | ‑‑status | N/A | **Type:** Value
**Valid Values:** `ACTIVE`, `DISCONNECTED`

Filter the MCP servers by connection status. Only ACTIVE and DISCONNECTED are supported as filters. | | ‑‑target‑org | ‑o | **Type:** Value
**Required**

Username or alias of the target org. Not required if the `target-org` configuration variable is already set. | | ‑‑type | N/A | **Type:** Value
**Valid Values:** `EXTERNAL`

Filter the MCP servers by type. | ## Examples for agent mcp list List all MCP servers in the default target org: ```shell sf agent mcp list --target-org myOrg ``` List external MCP servers filtered by status and output as JSON: ```shell sf agent mcp list --target-org myOrg --type EXTERNAL --status ACTIVE --json ``` # agent mcp update (Developer Preview) Update an MCP server registered in the API Catalog. **note:** This command is available as a developer preview. The command isn't generally available unless or until Salesforce announces its general availability in documentation or in press releases or public statements. All commands, parameters, and other features are subject to change or deprecation at any time, with or without notice. Don't implement functionality developed with these commands or tools. ## Description for agent mcp update Updates an existing MCP server in the API Catalog. Only the fields you provide are changed; omitted fields are left untouched. You can update the label, description, and server URL, and replace the authorization configuration. When setting `--auth-type OAUTH`, you must also provide `--identity-provider`, `--client-id`, `--client-secret`, and `--scope`. When setting `--auth-type NO_AUTH`, no authorization credentials are required. At least one updatable field must be supplied. ## Flags | Flag Name (Long) | Flag Name (Short) | Description | |------------------|-------------------|-------------| | ‑‑api‑version | N/A | **Type:** Value

Override the api version used for api requests made by this command | | ‑‑auth‑type | N/A | **Type:** Value
**Valid Values:** `OAUTH`, `NO_AUTH`

Authorization type to apply to the MCP server (OAUTH or NO_AUTH). | | ‑‑client‑id | N/A | **Type:** Value

OAuth client ID (required when --auth-type is OAUTH). | | ‑‑client‑secret | N/A | **Type:** Value

OAuth client secret (required when --auth-type is OAUTH). Pass "-" to read it from stdin (piped) and keep it out of shell history. | | ‑‑description | N/A | **Type:** Value

New description for the MCP server. | | ‑‑flags‑dir | N/A | **Type:** Value

Import flag values from a directory. | | ‑‑identity‑provider | N/A | **Type:** Value

Identity provider name for OAuth authorization (required when --auth-type is OAUTH). | | ‑‑json | N/A | **Type:** Boolean

Format output as json. | | ‑‑label | N/A | **Type:** Value

New display label for the MCP server. | | ‑‑mcp‑server‑id | ‑i | **Type:** Value
**Required**

ID of the MCP server to update. | | ‑‑scope | N/A | **Type:** Value

OAuth scope (required when --auth-type is OAUTH). | | ‑‑server‑url | N/A | **Type:** Value

New endpoint URL of the MCP server. | | ‑‑target‑org | ‑o | **Type:** Value
**Required**

Username or alias of the target org. Not required if the `target-org` configuration variable is already set. | ## Examples for agent mcp update Update the label and description of an MCP server in the default target org: ```shell sf agent mcp update --mcp-server-id 0XSxx0000000001 --label "Orders MCP" --description "Order tooling" --target-org myOrg ``` Update the server URL and switch the authorization to OAuth, piping the client secret from stdin and outputting as JSON: ```shell cat secret.txt | sf agent mcp update --mcp-server-id 0XSxx0000000001 --server-url https://mcp.example.com --auth-type OAUTH --identity-provider MyIdp --client-id abc --client-secret - --scope "read write" --target-org myOrg --json ``` # agent preview Interact with an agent to preview how it responds to your statements, questions, and commands (utterances). ## Description for agent preview Use this command to have a natural language conversation with an agent, either while you code its local Agent Script file or when it's published to an org. Previewing an agent acts like an initial test to make sure it responds to your utterances as you expect. For example, you can test that the agent uses a particular topic when asked a question, and then whether it invokes the correct action associated with that topic. This command is the CLI-equivalent of the Preview panel in your org's Agentforce Builder UI. Run without flags, this command provides a list of agents to preview, divided into two categories: "Agent Script", which are agents that have a local authoring bundle in your DX project, or "Published", which are agents that are published and activated in your org. Authoring bundles contain an agent's Agent Script file. You then choose the agent you want to preview from the list. Or you can use the --authoring-bundle flag to specify a local authoring bundle's API name or --api-name to specify an activated published agent. When previewing an agent from its Agent Script file, you can use these two modes:
  • Simulated mode (Default): Uses only the Agent Script file to converse, and it simulates (mocks) all the actions. Use this mode if none of the Apex classes, flows, or prompt templates that implement your actions are available yet. The LLM uses the information about topics in the Agent Script file to simulate what the action does or how it responds.
  • Live mode: Uses the actual Apex classes, flows, and prompt templates in your development org in the agent preview. If you've changed the Apex classe, flows, or prompt templates in your local DX project, then you must deploy them to your development org if you want to use them in your live preview.
You can use the Apex Replay Debugger to debug your Apex classes when using live mode for Agent Script files and for activated published agents; specify the --apex-debug flag. Once connected to your agent, the preview interface is simple: in the "Start typing..." prompt, enter a statement, question, or command; when you're done, enter Return. Your utterance is posted on the right along with a timestamp. The agent then responds on the left. To exit the conversation, hit ESC or Control+C. When the session concludes, the command asks if you want to save the API responses and chat transcripts. By default, the files are saved to the "./temp/agent-preview" directory. Specify a new default directory with the --output-dir flag. ## Flags | Flag Name (Long) | Flag Name (Short) | Description | |------------------|-------------------|-------------| | ‑‑apex‑debug | ‑x | **Type:** Boolean

Enable Apex debug logging during the agent preview conversation. | | ‑‑api‑name | ‑n | **Type:** Value

API name of the activated published agent you want to interact with. | | ‑‑api‑version | N/A | **Type:** Value

Override the api version used for api requests made by this command | | ‑‑authoring‑bundle | N/A | **Type:** Value

API name of the authoring bundle metadata component that contains the agent's Agent Script file. | | ‑‑context‑variables | N/A | **Type:** Value

Session variables for the agent preview session, in the form Name=Value.

Sets variables on the agent preview session, mirroring what the in-org Agentforce Builder UI does when you override variables before sending a message. Specify this flag multiple times or use comma-separated values. Two namespaces are supported, distinguished by the name shape. Names pass through to the runtime verbatim — the CLI doesn't transform them.

Linked context variables use the "$Context." prefix. These map to externally-provided fields that the runtime resolves (declared in the bundle's globalConfiguration.contextVariables) and are read by live actions and topic-routing expressions via $Context.Name. Example: $Context.MyLinkedVar=some-value.

State variables use the bare developerName, no prefix. These seed mutable agent state declared in agentVersion.stateVariables. Example: MyStateVar=some-value.

Both namespaces can be mixed in one value. Example: --context-variables '$Context.MyLinkedVar=foo,MyStateVar=bar'.

Tips: (1) Quote the whole value in single quotes so $Context isn't shell-expanded. (2) Names are sent verbatim — a bare name is treated as a state variable, not a linked context variable, so live actions that bind via $Context.Name will see null. (3) Type is always Text; to send a typed variable, use --context-variables-json. | | ‑‑context‑variables‑json | N/A | **Type:** Value

Typed session variables for the agent preview session, as a JSON array.

Sets typed variables on the agent preview session. Use this instead of --context-variables when a variable is not Text, for example a boolean-gated route (available when @variables.myFlag == True) that needs a real Boolean, or a Number, Object, List, or Json value.

The value is a JSON array of objects, each with a "name", a "type", and an optional "value". The "type" is one of Text, Date, DateTime, Money, Ref, Boolean, Number, Object, List, or Json. The JSON type of "value" must match "type": Boolean takes a boolean, Number takes a number, the string types take a string, Object and List take an array, and Json takes an object.

Example: --context-variables-json '[{"name":"probeGate","type":"Boolean","value":true},{"name":"retryCount","type":"Number","value":3}]'.

You can pass both --context-variables and --context-variables-json in the same command. When the same variable name appears in both, the --context-variables-json value wins.

Tip: names follow the same rules as --context-variables. Use the "$Context." prefix for linked context variables, and a bare name for state variables. | | ‑‑flags‑dir | N/A | **Type:** Value

Import flag values from a directory. | | ‑‑output‑dir | ‑d | **Type:** Value

Directory where conversation transcripts are saved. | | ‑‑target‑org | ‑o | **Type:** Value
**Required**

Username or alias of the target org. Not required if the `target-org` configuration variable is already set. | | ‑‑use‑live‑actions | N/A | **Type:** Boolean

Use real actions in the org; if not specified, preview uses AI to simulate (mock) actions. | ## Examples for agent preview Preview an agent by choosing from the list of available local Agent Script or published agents. If previewing a local Agent Script agent, use simulated mode. Use the org with alias "my-dev-org". ```shell sf agent preview --target-org my-dev-org ``` Preview an agent in live mode by choosing from a list of authoring bundles. Save the conversation transcripts to the "./transcripts/my-preview" directory, enable the Apex debug logs, and use your default org: ```shell sf agent preview --use-live-actions --apex-debug --output-dir transcripts/my-preview ``` # agent preview end End an existing programmatic agent preview session and get trace location. ## Description for agent preview end You must have previously started a programmatic agent preview session with the "agent preview start" command to then use this command to end it. This command also displays the local directory where the session trace files are stored. The original "agent preview start" command outputs a session ID which you then use with the --session-id flag of this command to end the session. You don't have to specify the --session-id flag if an agent has only one active preview session. You must also use either the --authoring-bundle or --api-name flag to specify the API name of the authoring bundle or the published agent, respectively. To find either API name, navigate to your package directory in your DX project. The API name of an authoring bundle is the same as its directory name under the "aiAuthoringBundles" metadata directory. Similarly, the published agent's API name is the same as its directory name under the "Bots" metadata directory. Use the --all flag to end all active preview sessions at once. You can combine --all with --api-name or --authoring-bundle to end only sessions for a specific agent, or use --all on its own to end every session across all agents in the project. ## Flags | Flag Name (Long) | Flag Name (Short) | Description | |------------------|-------------------|-------------| | ‑‑all | N/A | **Type:** Boolean

End all active preview sessions. Combine with --api-name or --authoring-bundle to limit to a specific agent, or use with only --target-org to end sessions for all agents found in the local session cache. Requires --target-org. | | ‑‑api‑name | ‑n | **Type:** Value

API name of the activated published agent you want to preview. | | ‑‑api‑version | N/A | **Type:** Value

Override the api version used for api requests made by this command | | ‑‑authoring‑bundle | N/A | **Type:** Value

API name of the authoring bundle metadata component that contains the agent's Agent Script file. | | ‑‑flags‑dir | N/A | **Type:** Value

Import flag values from a directory. | | ‑‑json | N/A | **Type:** Boolean

Format output as json. | | ‑‑no‑prompt | ‑p | **Type:** Boolean

Don't prompt for confirmation before ending sessions. Has an effect only when used with --all. | | ‑‑session‑id | N/A | **Type:** Value

Session ID outputted by "agent preview start". Not required when the agent has exactly one active session. Run "agent preview sessions" to see the list of all sessions. | | ‑‑target‑org | ‑o | **Type:** Value
**Required**

Username or alias of the target org. Not required if the `target-org` configuration variable is already set. | ## Examples for agent preview end End a preview session of a published agent by specifying its session ID and API name; use the default org: ```shell sf agent preview end --session-id --api-name My_Published_Agent ``` Similar to previous example, but don't specify a session ID; you get an error if the published agent has more than one active session. Use the org with alias "my-dev-org": ```shell sf agent preview end --api-name My_Published_Agent --target-org my-dev-org ``` End a preview session of an agent using its authoring bundle API name; you get an error if the agent has more than one active session. ```shell sf agent preview end --authoring-bundle My_Local_Agent ``` End all active preview sessions for a specific agent without prompting: ```shell sf agent preview end --all --authoring-bundle My_Local_Agent --target-org --no-prompt ``` End all active preview sessions across every agent in the local session cache for an org: ```shell sf agent preview end --all --target-org ``` # agent preview send Send a message to an existing agent preview session. ## Description for agent preview send You must have previously started a programmatic agent preview session with the "agent preview start" command to then use this command to send the agent a message (utterance). This command then displays the agent's response. The original "agent preview start" command outputs a session ID which you then use with the --session-id flag of this command to send a message. You don't have to specify the --session-id flag if an agent has only one active preview session. You must also use either the --authoring-bundle or --api-name flag to specify the API name of the authoring bundle or the published agent, respecitvely. To find either API name, navigate to your package directory in your DX project. The API name of an authoring bundle is the same as its directory name under the "aiAuthoringBundles" metadata directory. Similarly, the published agent's API name is the same as its directory name under the "Bots" metadata directory. ## Flags | Flag Name (Long) | Flag Name (Short) | Description | |------------------|-------------------|-------------| | ‑‑api‑name | ‑n | **Type:** Value

API name of the activated published agent you want to preview. | | ‑‑api‑version | N/A | **Type:** Value

Override the api version used for api requests made by this command | | ‑‑authoring‑bundle | N/A | **Type:** Value

API name of the authoring bundle metadata component that contains the agent's Agent Script file. | | ‑‑flags‑dir | N/A | **Type:** Value

Import flag values from a directory. | | ‑‑json | N/A | **Type:** Boolean

Format output as json. | | ‑‑session‑id | N/A | **Type:** Value

Session ID outputted by "agent preview start". Not required when the agent has exactly one active session. Run "agent preview sessions" to see list of all sessions. | | ‑‑target‑org | ‑o | **Type:** Value
**Required**

Username or alias of the target org. Not required if the `target-org` configuration variable is already set. | | ‑‑utterance | ‑u | **Type:** Value
**Required**

Utterance to send to the agent, enclosed in double quotes. | ## Examples for agent preview send Send a message to an activated published agent using its API name and session ID; use the default org: ```shell sf agent preview send --utterance "What can you help me with?" --api-name My_Published_Agent --session-id ``` Similar to previous example, but don't specify a session ID; you get an error if the agent has more than one active session. Use the org with alias "my-dev-org": ```shell sf agent preview send --utterance "What can you help me with?" --api-name My_Published_Agent --target-org my-dev-org ``` Send a message to an agent using its authoring bundle API name; you get an error if the agent has more than one active session: ```shell sf agent preview send --utterance "what can you help me with?" --authoring-bundle My_Local_Agent ``` # agent preview sessions List all known programmatic agent preview sessions. ## Description for agent preview sessions This command lists the agent preview sessions that were started with the "agent preview start" command and are still in the local cache. Use this command to discover specific session IDs that you can pass to the "agent preview send" or "agent preview end" commands with the --session-id flag. Programmatic agent preview sessions can be started for both published activated agents and by using an agent's local authoring bundle, which contains its Agent Script file. In this command's output table, the Agent column contains either the API name of the authoring bundle or the published agent, whichever was used when starting the session. In the table, if the same API name has multiple rows with different session IDs, then it means that you previously started multiple preview sessions with the associated agent. ## Flags | Flag Name (Long) | Flag Name (Short) | Description | |------------------|-------------------|-------------| | ‑‑flags‑dir | N/A | **Type:** Value

Import flag values from a directory. | | ‑‑json | N/A | **Type:** Boolean

Format output as json. | ## Examples for agent preview sessions List all cached agent preview sessions: ```shell sf agent preview sessions ``` # agent preview start Start a programmatic agent preview session. ## Description for agent preview start This command outputs a session ID that you then use with the "agent preview send" command to send an utterance to the agent. Use the "agent preview sessions" command to list all active sessions and the "agent preview end" command to end a specific session. Identify the agent you want to start previewing with either the --authoring-bundle flag to specify a local authoring bundle's API name or --api-name to specify an activated published agent's API name. To find either API name, navigate to your package directory in your DX project. The API name of an authoring bundle is the same as its directory name under the "aiAuthoringBundles" metadata directory. Similarly, the published agent's API name is the same as its directory name under the "Bots" metadata directory. When starting a preview session with --authoring-bundle, you must explicitly specify the execution mode using one of these flags:
  • --use-live-actions: Executes real Apex classes, flows, and other actions in the org. This surfaces compile and validation errors during preview.
  • --simulate-actions: Uses AI to simulate action execution without calling real implementations.
Published agents (--api-name) always use live actions. The mode flags are optional and have no effect for published agents. ## Flags | Flag Name (Long) | Flag Name (Short) | Description | |------------------|-------------------|-------------| | ‑‑api‑name | ‑n | **Type:** Value

API name of the activated published agent you want to preview. | | ‑‑api‑version | N/A | **Type:** Value

Override the api version used for api requests made by this command | | ‑‑authoring‑bundle | N/A | **Type:** Value

API name of the authoring bundle metadata component that contains the agent's Agent Script file. | | ‑‑context‑variables | N/A | **Type:** Value

Session variables for the agent preview session, in the form Name=Value.

Sets variables on the agent preview session, mirroring what the in-org Agentforce Builder UI does when you override variables before sending a message. Specify this flag multiple times or use comma-separated values. Two namespaces are supported, distinguished by the name shape. Names pass through to the runtime verbatim — the CLI doesn't transform them.

Linked context variables use the "$Context." prefix. These map to externally-provided fields that the runtime resolves (declared in the bundle's globalConfiguration.contextVariables) and are read by live actions and topic-routing expressions via $Context.Name. Example: $Context.MyLinkedVar=some-value.

State variables use the bare developerName, no prefix. These seed mutable agent state declared in agentVersion.stateVariables. Example: MyStateVar=some-value.

Both namespaces can be mixed in one value. Example: --context-variables '$Context.MyLinkedVar=foo,MyStateVar=bar'.

Tips: (1) Quote the whole value in single quotes so $Context isn't shell-expanded. (2) Names are sent verbatim — a bare name is treated as a state variable, not a linked context variable, so live actions that bind via $Context.Name will see null. (3) Type is always Text; to send a typed variable, use --context-variables-json. | | ‑‑context‑variables‑json | N/A | **Type:** Value

Typed session variables for the agent preview session, as a JSON array.

Sets typed variables on the agent preview session. Use this instead of --context-variables when a variable is not Text, for example a boolean-gated route (available when @variables.myFlag == True) that needs a real Boolean, or a Number, Object, List, or Json value.

The value is a JSON array of objects, each with a "name", a "type", and an optional "value". The "type" is one of Text, Date, DateTime, Money, Ref, Boolean, Number, Object, List, or Json. The JSON type of "value" must match "type": Boolean takes a boolean, Number takes a number, the string types take a string, Object and List take an array, and Json takes an object.

Example: --context-variables-json '[{"name":"probeGate","type":"Boolean","value":true},{"name":"retryCount","type":"Number","value":3}]'.

You can pass both --context-variables and --context-variables-json in the same command. When the same variable name appears in both, the --context-variables-json value wins.

Tip: names follow the same rules as --context-variables. Use the "$Context." prefix for linked context variables, and a bare name for state variables. | | ‑‑flags‑dir | N/A | **Type:** Value

Import flag values from a directory. | | ‑‑json | N/A | **Type:** Boolean

Format output as json. | | ‑‑simulate‑actions | N/A | **Type:** Boolean

Use AI to simulate action execution instead of calling real actions. Required with --authoring-bundle. | | ‑‑target‑org | ‑o | **Type:** Value
**Required**

Username or alias of the target org. Not required if the `target-org` configuration variable is already set. | | ‑‑use‑live‑actions | N/A | **Type:** Boolean

Execute real actions in the org (Apex classes, flows, etc.). Required with --authoring-bundle. | ## Examples for agent preview start Start a programmatic agent preview session by specifying an authoring bundle; use simulated actions. Use the org with alias "my-dev-org": ```shell sf agent preview start --authoring-bundle My_Agent_Bundle --target-org my-dev-org --simulate-actions ``` Similar to previous example but use live actions and the default org: ```shell sf agent preview start --authoring-bundle My_Agent_Bundle --use-live-actions ``` Start a preview session with an activated published agent (always uses live actions): ```shell sf agent preview start --api-name My_Published_Agent ``` # agent publish authoring-bundle Publish an authoring bundle to your org, which results in a new agent or a new version of an existing agent. ## Description for agent publish authoring-bundle An authoring bundle is a metadata type (named aiAuthoringBundle) that provides the blueprint for an agent. The metadata type contains two files: the standard metatada XML file and an Agent Script file (extension ".agent") that fully describes the agent using the Agent Script language. When you publish an authoring bundle to your org, a number of things happen. First, this command validates that the Agent Script file successfully compiles. If there are compilation errors, the command exits and you must fix the Agent Script file to continue. Once the Agent Script file compiles, then it's published to the org, which in turn creates new associated metadata (Bot, BotVersion, GenAiX), or new versions of the metadata if the agent already exists. The new or updated metadata is retrieved back to your DX project; specify the --skip-retrieve flag to skip this step. Finally, the authoring bundle metadata (AiAuthoringBundle) is deployed to your org. This command uses the API name of the authoring bundle. ## Flags | Flag Name (Long) | Flag Name (Short) | Description | |------------------|-------------------|-------------| | ‑‑api‑name | ‑n | **Type:** Value

API name of the authoring bundle you want to publish; if not specified, the command provides a list that you can choose from. | | ‑‑api‑version | N/A | **Type:** Value

Override the api version used for api requests made by this command | | ‑‑concise | N/A | **Type:** Boolean

Display minimal output with only essential information about the publish operation. | | ‑‑flags‑dir | N/A | **Type:** Value

Import flag values from a directory. | | ‑‑json | N/A | **Type:** Boolean

Format output as json. | | ‑‑skip‑retrieve | N/A | **Type:** Boolean

Don't retrieve the metadata associated with the agent to your DX project. | | ‑‑target‑org | ‑o | **Type:** Value
**Required**

Username or alias of the target org. Not required if the `target-org` configuration variable is already set. | | ‑‑verbose | ‑v | **Type:** Boolean

Display detailed output showing all metadata components retrieved and deployed during the publish process. | ## Examples for agent publish authoring-bundle Publish an authoring bundle by being prompted for its API name; use your default org: ```shell sf agent publish authoring-bundle ``` Publish an authoring bundle with API name MyAuthoringBundle to the org with alias "my-dev-org": ```shell sf agent publish authoring-bundle --api-name MyAuthoringbundle --target-org my-dev-org ``` Publish with verbose output to see all retrieved and deployed metadata components: ```shell sf agent publish authoring-bundle --api-name MyAuthoringbundle --verbose ``` Publish with concise output showing only essential information: ```shell sf agent publish authoring-bundle --api-name MyAuthoringbundle --concise ``` # agent test create Create an agent test in your org using a local test spec YAML file. ## Description for agent test create To run this command, you must have an agent test spec file, which is a YAML file that lists the test cases for testing a specific agent. Use the "agent generate test-spec" CLI command to generate a test spec file. Then specify the file to this command with the --spec flag, or run this command with no flags to be prompted. When this command completes, your org contains the new agent test, which you can view and edit using the Testing Center UI (legacy) or Agentforce Studio (NGT). This command also retrieves the metadata component associated with the new test to your local Salesforce DX project and displays its filename. By default, the legacy AiEvaluationDefinition is created; use --test-runner agentforce-studio to author an AiTestingDefinition (NGT) instead. After you've created the test in the org, use the "agent test run" command to run it. ## Flags | Flag Name (Long) | Flag Name (Short) | Description | |------------------|-------------------|-------------| | ‑‑api‑name | N/A | **Type:** Value

API name of the new test; the API name must not exist in the org. | | ‑‑api‑version | N/A | **Type:** Value

Override the api version used for api requests made by this command | | ‑‑flags‑dir | N/A | **Type:** Value

Import flag values from a directory. | | ‑‑force‑overwrite | N/A | **Type:** Boolean

Don't prompt for confirmation when overwriting an existing test (based on API name) in your org. | | ‑‑json | N/A | **Type:** Boolean

Format output as json. | | ‑‑preview | N/A | **Type:** Boolean

Preview the test metadata file without deploying to your org. | | ‑‑spec | N/A | **Type:** Value

Path to the test spec YAML file. | | ‑‑target‑org | ‑o | **Type:** Value
**Required**

Username or alias of the target org. Not required if the `target-org` configuration variable is already set. | | ‑‑test‑runner | N/A | **Type:** Value
**Valid Values:** `agentforce-studio`, `testing-center`

Explicitly specify which test runner to use (agentforce-studio or testing-center).

By default, the command automatically detects which test runner to use based on the test definition metadata type in your org. Use this flag to explicitly specify the runner type. 'agentforce-studio' uses AiTestingDefinition metadata. 'testing-center' uses AiEvaluationDefinition metadata. | ## Examples for agent test create Create an agent test interactively and be prompted for the test spec and API name of the test in the org; use the default org: ```shell sf agent test create ``` Create an agent test and use flags to specify all required information; if a test with same API name already exists in the org, overwrite it without confirmation. Use the org with alias "my-org": ```shell sf agent test create --spec specs/Resort_Manager-testSpec.yaml --api-name Resort_Manager_Test --force-overwrite --target-org my-org ``` Preview what the agent test metadata (AiEvaluationDefinition) looks like without deploying it to your default org: ```shell sf agent test create --spec specs/Resort_Manager-testSpec.yaml --api-name Resort_Manager_Test --preview ``` Author an Agentforce Studio (NGT) test from an NGT-shaped YAML; writes an AiTestingDefinition metadata file: ```shell sf agent test create --spec specs/ReturnsCheckout.ngt.yaml --api-name Returns_Checkout --test-runner agentforce-studio --target-org my-org ``` # agent test list List the available agent tests in your org. ## Description for agent test list The command outputs a table with the name (API name) of each test along with its unique ID, type ('agentforce-studio' or 'testing-center'), and the date it was created in the org. ## Flags | Flag Name (Long) | Flag Name (Short) | Description | |------------------|-------------------|-------------| | ‑‑api‑version | N/A | **Type:** Value

Override the api version used for api requests made by this command | | ‑‑flags‑dir | N/A | **Type:** Value

Import flag values from a directory. | | ‑‑json | N/A | **Type:** Boolean

Format output as json. | | ‑‑target‑org | ‑o | **Type:** Value
**Required**

Username or alias of the target org. Not required if the `target-org` configuration variable is already set. | ## Examples for agent test list List the agent tests in your default org: ```shell sf agent test list ``` List the agent tests in an org with alias "my-org"" ```shell sf agent test list --target-org my-org ``` # agent test results Get the results of a completed agent test run. ## Description for agent test results This command requires a job ID, which the original "agent test run" command displays when it completes. You can also use the --use-most-recent flag to see results for the most recently run agent test. By default, this command outputs test results in human-readable tables for each test case. The tables show whether the test case passed, the expected and actual values, the test score, how long the test took, and more. Use the --result-format to display the test results in JSON or Junit format. Use the --output-dir flag to write the results to a file rather than to the terminal. ## Flags | Flag Name (Long) | Flag Name (Short) | Description | |------------------|-------------------|-------------| | ‑‑api‑version | N/A | **Type:** Value

Override the api version used for api requests made by this command | | ‑‑flags‑dir | N/A | **Type:** Value

Import flag values from a directory. | | ‑‑job‑id | ‑i | **Type:** Value
**Required**

Job ID of the completed agent test run. | | ‑‑json | N/A | **Type:** Boolean

Format output as json. | | ‑‑output‑dir | ‑d | **Type:** Value

Directory to write the agent test results into.

If the agent test run completes, write the results to the specified directory. If the test is still running, the test results aren't written. | | ‑‑result‑format | N/A | **Type:** Value
**Valid Values:** `json`, `human`, `junit`, `tap`
**Default value:** `human`

Format of the agent test run results. | | ‑‑target‑org | ‑o | **Type:** Value
**Required**

Username or alias of the target org. Not required if the `target-org` configuration variable is already set. | | ‑‑test‑runner | N/A | **Type:** Value
**Valid Values:** `agentforce-studio`, `testing-center`

Explicitly specify which test runner to use (agentforce-studio or testing-center).

By default, the command automatically detects which test runner to use based on the test definition metadata type in your org. Use this flag to explicitly specify the runner type. 'agentforce-studio' uses AiTestingDefinition metadata. 'testing-center' uses AiEvaluationDefinition metadata. | | ‑‑verbose | N/A | **Type:** Boolean

Show generated data in the test results output.

When enabled, includes detailed generated data (such as invoked actions) in the human-readable test results output. This is useful for debugging test failures and understanding what actions were actually invoked during the test run.

The generated data is in JSON format and includes the Apex classes or Flows that were invoked, the Salesforce objects that were touched, and so on. Use the JSON structure of this information to build the test case JSONPath expression when using custom evaluations. | ## Examples for agent test results Get the results of an agent test run in your default org using its job ID: ```shell sf agent test results --job-id 4KBfake0000003F4AQ ``` Get the results of the most recently run agent test in an org with alias "my-org": ```shell sf agent test results --use-most-recent --target-org my-org ``` Get the results of the most recently run agent test in your default org, and write the JSON-formatted results into a directory called "test-results": ```shell sf agent test results --use-most-recent --output-dir ./test-results --result-format json ``` # agent test resume Resume an agent test that you previously started in your org so you can view the test results. ## Description for agent test resume This command requires a job ID, which the original "agent test run" command displays when it completes. You can also use the --use-most-recent flag to see results for the most recently run agent test. Use the --wait flag to specify the number of minutes for this command to wait for the agent test to complete; if the test completes by the end of the wait time, the command displays the test results. If not, the CLI returns control of the terminal to you, and you must run "agent test resume" again. By default, this command outputs test results in human-readable tables for each test case. The tables show whether the test case passed, the expected and actual values, the test score, how long the test took, and more. Use the --result-format to display the test results in JSON or Junit format. Use the --output-dir flag to write the results to a file rather than to the terminal. ## Flags | Flag Name (Long) | Flag Name (Short) | Description | |------------------|-------------------|-------------| | ‑‑api‑version | N/A | **Type:** Value

Override the api version used for api requests made by this command | | ‑‑flags‑dir | N/A | **Type:** Value

Import flag values from a directory. | | ‑‑job‑id | ‑i | **Type:** Value

Job ID of the original agent test run. | | ‑‑json | N/A | **Type:** Boolean

Format output as json. | | ‑‑output‑dir | ‑d | **Type:** Value

Directory to write the agent test results into.

If the agent test run completes, write the results to the specified directory. If the test is still running, the test results aren't written. | | ‑‑result‑format | N/A | **Type:** Value
**Valid Values:** `json`, `human`, `junit`, `tap`
**Default value:** `human`

Format of the agent test run results. | | ‑‑target‑org | ‑o | **Type:** Value
**Required**

Username or alias of the target org. Not required if the `target-org` configuration variable is already set. | | ‑‑test‑runner | N/A | **Type:** Value
**Valid Values:** `agentforce-studio`, `testing-center`

Explicitly specify which test runner to use (agentforce-studio or testing-center).

By default, the command automatically detects which test runner to use based on the test definition metadata type in your org. Use this flag to explicitly specify the runner type. 'agentforce-studio' uses AiTestingDefinition metadata. 'testing-center' uses AiEvaluationDefinition metadata. | | ‑‑use‑most‑recent | ‑r | **Type:** Boolean

Use the job ID of the most recent agent test run. | | ‑‑verbose | N/A | **Type:** Boolean

Show generated data in the test results output.

When enabled, includes detailed generated data (such as invoked actions) in the human-readable test results output. This is useful for debugging test failures and understanding what actions were actually invoked during the test run.

The generated data is in JSON format and includes the Apex classes or Flows that were invoked, the Salesforce objects that were touched, and so on. Use the JSON structure of this information to build the test case JSONPath expression when using custom evaluations. | | ‑‑wait | ‑w | **Type:** Value

Number of minutes to wait for the command to complete and display results to the terminal window. | ## Examples for agent test resume Resume an agent test in your default org using a job ID: ```shell sf agent test resume --job-id 4KBfake0000003F4AQ ``` Resume the most recently-run agent test in an org with alias "my-org" org; wait 10 minutes for the tests to finish: ```shell sf agent test resume --use-most-recent --wait 10 --target-org my-org ``` Resume the most recent agent test in your default org, and write the JSON-formatted results into a directory called "test-results": ```shell sf agent test resume --use-most-recent --output-dir ./test-results --result-format json ``` # agent test run Start an agent test in your org. ## Description for agent test run Use the --api-name flag to specify the name of the agent test you want to run. Use the output of the "agent test list" command to get the names of all the available agent tests in your org. By default, this command starts the agent test in your org, but it doesn't wait for the test to finish. Instead, it displays the "agent test resume" command, with a job ID, that you execute to see the results of the test run, and then returns control of the terminal window to you. Use the --wait flag to specify the number of minutes for the command to wait for the agent test to complete; if the test completes by the end of the wait time, the command displays the test results. If not, run "agent test resume". By default, this command outputs test results in human-readable tables for each test case, if the test completes in time. The tables show whether the test case passed, the expected and actual values, the test score, how long the test took, and more. Use the --result-format to display the test results in JSON or Junit format. Use the --output-dir flag to write the results to a file rather than to the terminal. ## Flags | Flag Name (Long) | Flag Name (Short) | Description | |------------------|-------------------|-------------| | ‑‑api‑name | ‑n | **Type:** Value

API name of the agent test to run; corresponds to the name of the AiEvaluationDefinition metadata component that implements the agent test. | | ‑‑api‑version | N/A | **Type:** Value

Override the api version used for api requests made by this command | | ‑‑flags‑dir | N/A | **Type:** Value

Import flag values from a directory. | | ‑‑json | N/A | **Type:** Boolean

Format output as json. | | ‑‑output‑dir | ‑d | **Type:** Value

Directory to write the agent test results into.

If the agent test run completes, write the results to the specified directory. If the test is still running, the test results aren't written. | | ‑‑result‑format | N/A | **Type:** Value
**Valid Values:** `json`, `human`, `junit`, `tap`
**Default value:** `human`

Format of the agent test run results. | | ‑‑target‑org | ‑o | **Type:** Value
**Required**

Username or alias of the target org. Not required if the `target-org` configuration variable is already set. | | ‑‑test‑runner | N/A | **Type:** Value
**Valid Values:** `agentforce-studio`, `testing-center`

Explicitly specify which test runner to use (agentforce-studio or testing-center).

By default, the command automatically detects which test runner to use based on the test definition metadata type in your org. Use this flag to explicitly specify the runner type. 'agentforce-studio' uses AiTestingDefinition metadata. 'testing-center' uses AiEvaluationDefinition metadata. | | ‑‑verbose | N/A | **Type:** Boolean

Show generated data in the test results output.

When enabled, includes detailed generated data (such as invoked actions) in the human-readable test results output. This is useful for debugging test failures and understanding what actions were actually invoked during the test run.

The generated data is in JSON format and includes the Apex classes or Flows that were invoked, the Salesforce objects that were touched, and so on. Use the JSON structure of this information to build the test case JSONPath expression when using custom evaluations. | | ‑‑wait | ‑w | **Type:** Value

Number of minutes to wait for the command to complete and display results to the terminal window. | ## Examples for agent test run Start an agent test called Resort_Manager_Test for an agent in your default org, don't wait for the test to finish: ```shell sf agent test run --api-name Resort_Manager_Test ``` Start an agent test for an agent in an org with alias "my-org" and wait for 10 minutes for the test to finish: ```shell sf agent test run --api-name Resort_Manager_Test --wait 10 --target-org my-org ``` Start an agent test and write the JSON-formatted results into a directory called "test-results": ```shell sf agent test run --api-name Resort_Manager_Test --wait 10 --output-dir ./test-results --result-format json ``` # agent test run-eval (Beta) Run rich evaluation tests against an Agentforce agent. **note:** This feature is a Beta Service. Customers may opt to try such Beta Service in its sole discretion. Any use of the Beta Service is subject to the applicable Beta Services Terms provided at [Agreements and Terms](https://www.salesforce.com/company/legal/agreements/). ## Description for agent test run-eval Specify the tests you want to run with one of these inputs to the --spec flag:
  • YAML test spec generated by the `agent generate test-spec` CLI command
  • JSON payload
When you provide a YAML test spec, this command automatically translates test cases into internal state-based evaluation framework calls and infers the agent name from the test spec's `subjectName` field. As a result, you can use the same test spec with both the `agent test run` and `agent test run-eval` commands. YAML test specs also support context variables, which allow you to inject contextual data (such as CaseId or RoutableId) into agent sessions for testing with different contexts. When you provide a JSON payload, it's sent directly to the evaluation framework with optional normalization. The normalizer auto-corrects common field name mistakes, converts shorthand references to JSONPath, and injects defaults. Use `--no-normalize` to disable this auto-normalization. JSON payloads can also include context_variables on agent.create_session steps for the same contextual testing capabilities as when you use a YAML test spec. This command supports more than 8 evaluator types, including subagent routing assertions, action invocation checks, string/numeric assertions, semantic similarity scoring, and LLM-based quality ratings. ## Flags | Flag Name (Long) | Flag Name (Short) | Description | |------------------|-------------------|-------------| | ‑‑api‑name | ‑n | **Type:** Value

Agent API name (also called DeveloperName) used to resolve agent_id and agent_version_id. Auto-inferred from the YAML spec's subjectName. | | ‑‑api‑version | N/A | **Type:** Value

Override the api version used for api requests made by this command | | ‑‑batch‑size | N/A | **Type:** Value
**Default value:** `5`

Number of tests per API request (max 5). | | ‑‑flags‑dir | N/A | **Type:** Value

Import flag values from a directory. | | ‑‑json | N/A | **Type:** Boolean

Format output as json. | | ‑‑no‑normalize | N/A | **Type:** Boolean

Disable auto-normalization of field names and shorthand references. | | ‑‑result‑format | N/A | **Type:** Value
**Valid Values:** `json`, `human`, `junit`, `tap`
**Default value:** `human`

Format of the agent test run results. | | ‑‑spec | ‑s | **Type:** Value
**Required**

Path to test spec file (YAML or JSON). Supports reading from stdin when piping content. | | ‑‑target‑org | ‑o | **Type:** Value
**Required**

Username or alias of the target org. Not required if the `target-org` configuration variable is already set. | ## Examples for agent test run-eval Run tests using a YAML test spec on the org with alias "my-org": ```shell sf agent test run-eval --spec specs/my-agent-testSpec.yaml --target-org my-org ``` Run tests using a YAML spec with explicit agent name override; use your default org: ```shell sf agent test run-eval --spec specs/my-agent-testSpec.yaml --api-name My_Agent ``` Run tests using a JSON payload: ```shell sf agent test run-eval --spec specs/eval-payload.json --target-org my-org ``` Run tests and output results in JUnit format; useful for continuous integration and deployment (CI/CD): ```shell sf agent test run-eval --spec specs/my-agent-testSpec.yaml --target-org my-org --result-format junit ``` Run tests with contextVariables to inject contextual data into agent sessions (add contextVariables to test cases in your YAML spec): ```shell sf agent test run-eval --spec specs/agent-with-context.yaml --target-org my-org ``` Pipe JSON payload from stdin (--spec flag is automatically populated from stdin): ```shell echo '{"tests":[...]}' | sf agent test run-eval --spec --target-org my-org ``` # agent trace delete Delete trace files from an agent preview session. ## Description for agent trace delete When you run an agent preview conversation (either interactive or programmatic), trace files are automatically recorded and saved in your local DX project. Use this command to delete some or all of the trace files. By default, this command shows a preview of what will be deleted and prompts for confirmation. Use --no-prompt to skip confirmation. Without filters, this comamnd deletes all trace files for all agents and sessions. Use flags to narrow the scope: filter by agent API name (--agent), by session (--session-id), or by age (--older-than). ## Flags | Flag Name (Long) | Flag Name (Short) | Description | |------------------|-------------------|-------------| | ‑‑agent | ‑a | **Type:** Value

API name of the agent used to filter the list of trace files you want to delete. Matches against the API name used when starting the session, either an authoring bundle or a published agent API name. | | ‑‑flags‑dir | N/A | **Type:** Value

Import flag values from a directory. | | ‑‑json | N/A | **Type:** Boolean

Format output as json. | | ‑‑no‑prompt | N/A | **Type:** Boolean

Skip the confirmation prompt and delete immediately. | | ‑‑older‑than | N/A | **Type:** Value

Duration used to filter the list of trace files; only files older than the duration are deleted. Accepts a number followed by a unit: m/minutes, h/hours, d/days, w/weeks. Examples: 7d, 24h, 2w. | | ‑‑session‑id | N/A | **Type:** Value

Session ID used to filter the list of trace files you want to delete. Use the "agent preview sessions" CLI command to list all known agent preview sessions along with their session IDs. | ## Examples for agent trace delete Delete all traces for all agents and sessions; prompt for confirmation: ```shell sf agent trace delete ``` Delete all traces for a specific agent: ```shell sf agent trace delete --agent My_Agent ``` Delete traces from a specific session: ```shell sf agent trace delete --session-id ``` Delete traces older than 7 days: ```shell sf agent trace delete --older-than 7d ``` Delete traces older than 24 hours for a specific agent; don't prompt for confirmation: ```shell sf agent trace delete --agent My_Agent --older-than 24h --no-prompt ``` Delete all traces for all agents and sessions; don't prompt for confirmation: ```shell sf agent trace delete --no-prompt ``` # agent trace list List the available trace files that were recorded during all agent preview sessions. ## Description for agent trace list When you run an agent preview conversation (either interactive or programmatic), trace files are automatically recorded and saved in your local DX project. By default, this command lists all trace files for all agents and all of their sessions. Use flags to narrow results: filter by agent name (--agent), by session (--session-id), or by date (--since). Each row in the output corresponds to one trace file, which in turn corresponds to one agent session. The Agent column shows the authoring bundle or API name used when starting the session. ## Flags | Flag Name (Long) | Flag Name (Short) | Description | |------------------|-------------------|-------------| | ‑‑agent | ‑a | **Type:** Value

API name of the agent used to filter the list of available trace files. Matches against the API name used when starting the session, either an authoring bundle or a published agent API name. | | ‑‑flags‑dir | N/A | **Type:** Value

Import flag values from a directory. | | ‑‑json | N/A | **Type:** Boolean

Format output as json. | | ‑‑session‑id | N/A | **Type:** Value

Session ID used to filter the list of trace files. Use the "agent preview sessions" CLI command to list all known agent preview sessions along with their session IDs. | | ‑‑since | N/A | **Type:** Value

Date used to filter the list of trace files; only those recorded on or after the date are listed.

Accepts ISO 8601 format: date-only (2026-04-20), date-time (2026-04-20T14:00:00Z), or date-time with milliseconds (2026-04-20T14:00:00.000Z). The "Recorded At" values shown in the table output are valid inputs. | ## Examples for agent trace list List all trace files for all agents and sessions: ```shell sf agent trace list ``` List all trace files for a specific agent: ```shell sf agent trace list --agent My_Agent ``` List trace files for a specific session: ```shell sf agent trace list --session-id ``` List trace files recorded on or after April 20, 2026 (date-only, interpreted as UTC midnight): ```shell sf agent trace list --since 2026-04-20 ``` List trace files recorded on or after a specific UTC time: ```shell sf agent trace list --since 2026-04-20T14:00:00Z ``` Filter by agent and date together: ```shell sf agent trace list --agent My_Agent --since 2026-04-20 ``` Return results as JSON: ```shell sf agent trace list --json ``` # agent trace read Read trace files from an agent preview session. ## Description for agent trace read When you run an agent preview conversation (either interactive or programmatic), trace files are automatically recorded and saved in your local DX project. Each turn (utterance or response) of a conversation creates trace data. Use this command to view trace data for a specific preview session, so you can then analyze the trace data to observe, monitor, investigate, and troubleshoot agent events and behavior. Use the --format flag to specify one of these formats of the outputted trace data:
  • summary (Default): A per-turn narrative showing topic routing, actions executed, and the agent's response. Use this to quickly understand what happened in a preview session.
  • detail: Diagnostic drill-down into a specific dimension. Filters output to only the trace steps relevant to that dimension, minimizing noise.
  • raw: Unprocessed trace JSON. Use this as a fallback when the trace schema has changed or you need to perform custom analysis.
If you specify "--format detail", you must also specify a dimension with the --dimension flag. Dimensions are a way to slice and analyze the agent execution trace from a specific angle or concern. Instead of looking at the raw sequence of everything that happened, each dimension filters and organizes the trace data to answer a specific type of question. These are the available dimensions and the information they provide:
  • actions: The actions the agent executed. Includes action name, input parameters, output, and latency. Use this dimension to understand what the agent actually did when answering an utterance in the preview session.
  • grounding: The reasoning steps used by the LLM. Use this dimension to see how the agent "thought" about the problem - the AI reasoning that determined which actions to take.
  • routing: How the agent navigated between subagents. Use this dimension to understand conversation flow - when and why the agent switched between different subagents or contexts during the conversation.
  • errors: Aggregates all errors during the session. Use this dimension to quickly identify and debug issues across all steps.
## Flags | Flag Name (Long) | Flag Name (Short) | Description | |------------------|-------------------|-------------| | ‑‑dimension | ‑d | **Type:** Value
**Valid Values:** `actions`, `grounding`, `routing`, `errors`

Dimension to drill into when using "--format detail"; used to filter and organize the trace data to answer a specific type of question. | | ‑‑flags‑dir | N/A | **Type:** Value

Import flag values from a directory. | | ‑‑format | ‑f | **Type:** Value
**Valid Values:** `summary`, `detail`, `raw`
**Default value:** `summary`

Output format of the trace data; specifies the level of detail you want in the trace files. | | ‑‑json | N/A | **Type:** Boolean

Format output as json. | | ‑‑session‑id | ‑s | **Type:** Value
**Required**

Session ID to read traces for. Use the "agent preview sessions" CLI command to list all known agent preview sessions along with their session IDs | | ‑‑turn | ‑t | **Type:** Value

Turn number for which you want trace data. A turn is a single utterance or response in a conversation, starting with 1. | ## Examples for agent trace read Show a session trace summary for all turns in the session with the specified ID: ```shell sf agent trace read --session-id ``` Show a trace summary for the second turn (utterance or response) of the conversation: ```shell sf agent trace read --session-id --turn 2 ``` Drill into action execution across all turns: ```shell sf agent trace read --session-id --format detail --dimension actions ``` Drill into routing decisions for the first turn of the conversation: ```shell sf agent trace read --session-id --format detail --dimension routing --turn 1 ``` Show all errors across the session: ```shell sf agent trace read --session-id --format detail --dimension errors ``` Output raw trace JSON for custom parsing: ```shell sf agent trace read --session-id --format raw ``` Return results as JSON: ```shell sf agent trace read --session-id --json ``` # agent validate authoring-bundle Validate an authoring bundle to ensure its Agent Script file compiles successfully and can be used to publish an agent. ## Description for agent validate authoring-bundle An authoring bundle is a metadata type (named aiAuthoringBundle) that provides the blueprint for an agent. The metadata type contains two files: the standard metatada XML file and an Agent Script file (extension ".agent") that fully describes the agent using the Agent Script language. This command validates that the Agent Script file in the authoring bundle compiles without errors so that you can later publish the bundle to your org. Use this command while you code the Agent Script file to ensure that it's valid. If the validation fails, the command outputs the list of syntax errors, a brief description of the error, and the location in the Agent Script file where the error occurred. This command uses the API name of the authoring bundle. If you don't provide an API name with the --api-name flag, the command searches the current DX project and outputs a list of authoring bundles that it found for you to choose from. ## Flags | Flag Name (Long) | Flag Name (Short) | Description | |------------------|-------------------|-------------| | ‑‑api‑name | ‑n | **Type:** Value

API name of the authoring bundle you want to validate; if not specified, the command provides a list that you can choose from. | | ‑‑api‑version | N/A | **Type:** Value

Override the api version used for api requests made by this command | | ‑‑flags‑dir | N/A | **Type:** Value

Import flag values from a directory. | | ‑‑json | N/A | **Type:** Boolean

Format output as json. | | ‑‑target‑org | ‑o | **Type:** Value
**Required**

Username or alias of the target org. Not required if the `target-org` configuration variable is already set. | ## Examples for agent validate authoring-bundle Validate an authoring bundle by being prompted for its API name; use your default org: ```shell sf agent validate authoring-bundle ``` Validate an authoring bundle with API name MyAuthoringBundle; use the org with alias "my-dev-org": ```shell sf agent validate authoring-bundle --api-name MyAuthoringBundle --target-org my-dev-org ``` # Agentforce Deep Planning Agentforce Deep Planning transforms how you build complex Salesforce features by investigating your codebase, understanding your architecture, and creating comprehensive implementation plans before writing a single line of code. **note:** Deep Planning requires models with strong reasoning capabilities. It works best with the latest generation of models, like GPT-5, Claude 4, Gemini 2.5, or Grok 4. Smaller models may struggle with the comprehensive analysis required. ## The Four-Step Process When you use Deep Planning with Agentforce, you follow a four-step process that mirrors how experienced Salesforce developers approach complex features: thorough investigation, discussion and clarification of requirements, detailed planning, and structured task creation with progress tracking. ### Step 1: Silent Investigation Agentforce becomes a detective, silently exploring your Salesforce codebase to understand its structure, patterns, and constraints. The investigation is methodical and thorough—Agentforce reads files and executes commands without commentary or narration. This silent research continues until the codebase is fully understood. During investigation, Agentforce: - Examines Apex classes, triggers, and their methods. - Analyzes Lightning Web Component files and dependencies. - Discovers custom objects, fields, and relationships. - Reviews validation rules, workflows, and automation patterns. - Identifies test coverage patterns and technical debt markers. - Explores configuration files and deployment structures. The quality of this investigation directly impacts the success of your implementation. Agentforce speaks up only when specific questions arise that require your input. ### Step 2: Discussion and Questions Once Agentforce understands your codebase, it asks brief, targeted questions that shape the implementation. These questions are conversational and specific to your Salesforce org and the feature you're building. Agentforce asks only when necessary—when the answer will directly influence the implementation plan. Questions arise for: - Clarifying ambiguous requirements or specifications. - Choosing between multiple equally valid implementation approaches. - Confirming assumptions about existing system behavior or constraints. - Understanding preferences for specific technical decisions. Your responses help Agentforce create an accurate, tailored implementation plan for your org. ### Step 3: Implementation Plan Document Agentforce creates a structured implementation plan document that serves as your development blueprint. This isn't a vague outline—it's a detailed specification with exact file paths, method signatures, and implementation order. ### Step 4: Implementation Task Creation Agentforce creates a task that references the plan document and includes trackable implementation steps. The task is self-contained—it doesn't require additional codebase investigation because all necessary information is in the plan document. Your implementation steps become a progress-tracked list with real-time updates, keeping complex projects organized and on track. ## Use Deep Planning Start Deep Planning by using the `/deep-planning` slash command. You can start in Plan or Act modes, but you must move to Act mode to create the implementation file. After initiating Deep Planning, describe your feature requirements. Agentforce begins investigation immediately, examining your Salesforce configuration and existing patterns. After gathering context, Agentforce engages you in discussion before creating the implementation plan. ## Example Workflow: Contact Favorites List Here's how Deep Planning works for a real Lightning Web Component implementation: **1. Initiate Planning** Request: "Build a Lightning Web Component that displays contacts with inline favorite toggling" **2. Silent Investigation** Agentforce explores your codebase and examines: - Existing Contact object schema and custom fields. - Current Apex controller patterns for Contact queries. - Lightning Web Component structure and naming conventions. - Jest test setup and ESLint configuration. - Field-level security patterns in existing code. **3. Targeted Discussion** Agentforce asks: - "Should the favorite field be `Favorite__c` or do you have an existing field name?". - "Do you need cross-component synchronization when favorites change?". - "Should this component be available on Contact record pages, app pages, or both?". - "What contact fields should display in the list: Email, Phone, or others?". **4. Plan Creation** Agentforce generates an implementation plan document with: **[Overview]**: Deliver a Lightning Web Component displaying Contacts with inline favorite toggling using the custom `Favorite__c` field. Leverages existing `ContactController` Apex class with new methods for data access and mutation. Implements optimistic UI updates, field-level security enforcement, and accessibility standards. **[Types]**: - ContactRow interface: Id, Name, Email, Phone, Favorite\_\_c - ToggleResult interface: success, message, updatedRecord - Validation: Favorite\_\_c is boolean, graceful handling of null Email/Phone **[Files]**: - New: `force-app/main/default/lwc/contactFavorites/` (html, js, css, meta.xml) - New: `force-app/main/default/lwc/contactFavorites/__tests__/contactFavorites.test.js` - Modify: `force-app/main/default/classes/ContactController.cls` - Modify: `force-app/main/default/classes/ContactController.cls-meta.xml` **[Functions]**: - LWC: `wiredGetContacts` (wire adapter), `handleToggleFavorite` (event handler), `showToast` (utility) - Apex: `getContacts()` (cacheable query), `toggleContactFavorite(Id, Boolean)` (imperative update) **[Classes]**: - Modify ContactController: Add FLS checks with `Schema.sObjectType.Contact.fields.Favorite__c.isUpdateable()`, implement try/catch for DML operations, return updated record or throw `AuraHandledException` **[Dependencies]**: - Continue using `@salesforce/sfdx-lwc-jest` for unit tests - Import `lightning/platformShowToastEvent` for user notifications - No new npm packages required **[Testing]**: - LWC Jest: Mock wire adapter, test toggle optimistic UI, verify rollback on error, check accessibility attributes - Apex: Test getContacts returns required fields, test toggle happy path, test FLS denial handling, test invalid Id exception **[Implementation Order]**: 1. Update ContactController with getContacts and toggleContactFavorite methods. 2. Scaffold contactFavorites LWC with wire and imperative Apex calls. 3. Write Jest and Apex unit tests. 4. Run ESLint and Prettier. 5. Deploy to sandbox and validate on Lightning App Page and Contact Record Page. **5. Task Generation** Agentforce creates a task with: - Reference to the implementation plan. - Commands to read specific sections. - Trackable items for each implementation step. - Clear success criteria for validation. ## Best Practices ### When to Use Deep Planning Use Deep Planning for: - Features touching multiple parts of your codebase. - Architectural changes requiring careful coordination. - Complex integrations with external services. - Refactoring efforts that need systematic execution. - Any feature where you'd normally spend time whiteboarding. ### Making the Most of Investigation Let Agentforce complete its investigation thoroughly. The quality of the plan directly correlates with how well it understands your codebase. If you have specific areas you want examined, mention them in your initial request. ### Reviewing the Plan Always review the implementation plan before starting development. The plan is comprehensive but not immutable, so you can edit it directly if needed. Think of it as a collaborative document between you and Agentforce. The plan uses precise technical language with exact file paths, function names, and class names. It considers real-world constraints like governor limits, field-level security, and deployment dependencies. This level of detail ensures successful execution without requiring additional investigation. ### Track Progress Your implementation progress displays with real-time tracking. Agentforce automatically checks off each completed step as you work through the plan, giving you visibility into complex implementations. ## Understand the Plan Sections ### Overview and Types The **Overview** sets implementation context, while **Types** defines data contracts. Together, these sections ensure everyone understands what's being built and how data flows through the system. ### Files and Functions Files maps the file system changes, while Functions details the methods within those files. These sections provide the concrete implementation specification developers need. ### Classes and Dependencies Classes focuses on Apex-specific patterns like field-level security (FLS) checks and exception handling. Dependencies ensures all required packages and modules are available before implementation begins. ### Testing and Implementation Order Testing defines validation criteria, while Implementation Order sequences execution. Following this order respects metadata dependencies and includes checkpoints for catching issues early. # Agentforce for Vibes Releases We release updates to the Agentforce Vibes VS Code extension multiple times a month, often on a weekly cadence. Prereleases let you try upcoming Agentforce Vibes capabilities before they roll into the stable release the following week. Use prereleases to explore what’s new, experiment with emerging features, and provide feedback ahead of the stable release. ## Release Versioning **Prerelease**: Odd-numbered weekly releases (for example, v1.11). **Stable Release**: Even-numbered weekly releases (for example, v1.10). Features first appear in prerelease and roll into the stable release the following week. ## Install a Prerelease To switch to the prerelease version: 1. Open VS Code. 2. Go to the Extensions view in the Activity Bar. 3. Search for Agentforce Vibes. 4. Open the extension details page. 5. Select **Switch to prerelease Version**. 6. Restart VS Code when prompted. ## 🚀 Announcing the Agentforce Vibes Version 4.xx Pre-Release We're excited to introduce the first public pre-release of **Agentforce Vibes version 4.xx**, a major evolution of the Agentforce Vibes experience. This release delivers a dramatically more capable agentic development environment with advanced planning workflows, improved tool orchestration, deeper MCP integration, and a redesigned chat experience. With this version of Agentforce Vibes, you can do more than generate code. Agents can reason through complex tasks, create implementation plans, ask clarifying questions, manage context intelligently, and take multi-step actions while keeping you in control through approvals, permissions, and native VS Code diff reviews. Highlights include: - 💬 A redesigned chat experience with multi-tab conversations, conversation history, reasoning visibility, tool execution details, and automatic context management. - 🧠 New **Plan Mode** for breaking down complex work into structured plans and manageable tasks. - 🛠️ Improved tool execution with approvals, security controls, and native VS Code diff-based review. - 🔌 Expanded MCP support, including platform-hosted MCP servers, improved configuration, and more reliable connections. - 📚 Built-in support for Skills and Rules to help guide agent behavior and package reusable expertise. - 👀 Live previews for Lightning Web Components, metadata visualizations, and React-based user interfaces. - 🤖 Access to the latest Claude and GPT models through a unified model picker. Agentforce Vibes represents a significant step forward in agentic development and lays the foundation for powerful new capabilities coming in future releases. As this is a prerelease, we're eager to hear your feedback. Try out Agentforce Vibes version 4.xx and let us know what you think! _June 06, 2026_ # Agentforce for Vibes Releases We release updates to the Agentforce Vibes VS Code extension multiple times a month, often on a weekly cadence. Prereleases let you try upcoming Agentforce Vibes capabilities before they roll into the stable release the following week. Use prereleases to explore what’s new, experiment with emerging features, and provide feedback ahead of the stable release. ## Release Versioning **Prerelease**: Odd-numbered weekly releases (for example, v1.11). **Stable Release**: Even-numbered weekly releases (for example, v1.10). Features first appear in prerelease and roll into the stable release the following week. ## Install a Prerelease To switch to the prerelease version: 1. Open VS Code. 2. Go to the Extensions view in the Activity Bar. 3. Search for Agentforce Vibes. 4. Open the extension details page. 5. Select **Switch to prerelease Version**. 6. Restart VS Code when prompted. Read the release notes to learn about [recent updates](https://marketplace.visualstudio.com/items/salesforce.salesforcedx-einstein-gpt/changelog). # Agentforce Plan and Act Modes Agentforce has two distinct interaction modes that optimize your Salesforce development workflow: Plan mode for strategic thinking, and Act mode for implementation. This dual-mode approach helps you create more maintainable, accurate solutions while reducing development iterations and ensuring thoughtful architecture decisions. Plan and Act modes separate strategic thinking from execution, helping you tackle complex Salesforce projects more effectively. The toggle on the bottom right of the chat lets you switch between these two modes. In Act mode, Focus Chain provides an automatic todo list management with real-time progress tracking throughout your tasks. **Plan Mode** - Think first: - Analyze your project without making changes. - Identify risks and plan architecture. - Build comprehensive context about your org. **Act Mode** - Build it: - Execute planned solutions with full tool access. - Remember all planning decisions. - Take direct action on your codebase. **Use Plan Mode for**: New features, complex debugging, architectural decisions. **Use Act Mode for**: Implementing solutions, routine changes, established patterns. ## Understanding Plan Mode Plan mode focuses on analysis and strategy without making changes to your files or org: - **Analyze**: Project structure, custom objects, Apex classes, Lightning components. - **Plan**: Implementation strategies, deployment sequences, testing approaches. - **Identify Risks**: Governor limits, security considerations, integration challenges. ### Example Plan Mode Session ``` "I need to add a customer portal feature. Help me understand what's involved." → Agentforce analyzes org setup, customer objects, security. "What's the best approach for customer self-service?" → Agentforce proposes architecture, authentication strategy, security model. "Create a detailed implementation plan." → Agentforce provides step-by-step sequence, components, testing strategy. ``` ## Understanding Act Mode Act mode provides full tool access to implement solutions: - **Create and Modify**: Apex classes, triggers, Lightning components, metadata. - **Execute**: Salesforce CLI commands, tests, deployments. - **Implement**: Follow established plans with real-time validation and error handling. ### Example Act Mode Session ``` "Implement the customer portal solution, starting with the data model." → Agentforce creates objects, fields, security rules, deploys to org. "Create the Lightning components for the portal interface." → Agentforce generates LWC components, Jest tests, integrates with data model. "Run all tests and validate functionality." → Agentforce executes tests, reports coverage, validates deployment. ``` ## Common Workflows ### New Feature Development - **Plan Mode**: Analyze requirements, design architecture, identify risks. - **Act Mode**: Implement components, deploy metadata, run tests. ### Bug Investigation - **Plan Mode**: Analyze code patterns, identify root causes, plan optimization. - **Act Mode**: Refactor code, implement fixes, validate with tests. ### Architecture Review - **Plan Mode**: Review existing code, identify improvements, plan refactoring. - **Act Mode**: Implement modern patterns, update dependencies, ensure coverage. ## Best Practices ### Planning Phase - Share complete business context and constraints. - Let Agentforce explore your codebase structure. - Ask for multiple solution approaches. - Document plans for team reference. ### Implementation Phase - Follow the established plan consistently. - Monitor code quality and test coverage. - Return to Plan mode for unexpected complexity. - Validate each step against requirements. # Agentforce Rules Rules let you establish consistent coding standards, architectural patterns, and project-specific preferences that Agentforce follows across all development sessions. Unlike one-time prompts, rules persistently shape how Agentforce works, keeping outputs aligned with your team’s practices. Agentforce rules honor the [agents.md](https://agents.md/) standard, providing a portable, tooling-agnostic way to define persistent AI guidance that travels with your code. Agentforce also includes a set of out-of-the-box (OOTB) rules to help you get started with Salesforce development best practices. To view them, click Rules & Workflows (⚖️ icon). You can turn global rules on or off, with `a4d-general-rules-no-edit.md`, `a4d-apex-rules-no-edit.md` and `a4d-lwc-rules-no-edit.md` enabled by default. You can edit these rules if needed, but keep in mind that changes to OOTB rules are overwritten when the extension is updated. **Key Benefits** - Enforce coding patterns and architectural decisions. - Maintain Salesforce org structure and business requirements. - Share practices across development teams. - Ensure adherence to security, testing, and documentation standards. **Rule Types** - **Global Rules**: Apply to all Agentforce sessions across projects. - **Workspace Rules**: Specific to individual Salesforce projects or orgs. ## Create Rules Quickly create rules through Agentforce's built-in interface: 1. **Access Rules Tab**: Click Rules & Workflows (⚖️ icon) in the Agentforce chat interface. 2. **Select Rule Type**: Select either Global Rule or Workspace Rule. 3. **Create a Rule**: Click `+` to create a rule. You can also have Agentforce create a rule for you by using the `/newrule` slash command in the chat. Workspace rules are stored in your project's `.a4drules` folder. The location of global rules varies based on your operating system. ### How Rules Work Rules are loaded when Agentforce starts a task. Here’s what happens: Agentforce checks for rules in this sequence: 1. `.a4drules`/ folder (all .md files inside) 2. Single `.a4drules` file 3. `agents.md`file - Workspace rules override global rules when both define the same guidance. - When using a `.a4drules/` folder, all Markdown files are combined into one ruleset. Numeric prefixes (like 01-, 02-) control the order. ### Managing Rules with the Interface Agentforce provides a convenient popover interface that allows you to: - See which global and workspace rules are currently active. - Turn specific rules on or off with a single click. - Quickly create or delete rules. ## Customization Rules Format Use this simple rules format to create your custom rules: ``` # Rule: [Rule Name] **Description:** [Brief description of the rule's purpose] **Guidelines:** - [Guideline 1] - [Guideline 2] ``` ## Examples of Customization Rules Here are some sample customization rules that you can use as guidelines to create your own rules. Applying these rules ensures uniform code quality, easier maintenance, and improved collaboration. Agentforce applies these best practices automatically whenever it generates code, reducing the need for manual reviews and refactoring. ### Apex Naming Convention and Best Practices Rules This example Apex best practices rule defines a comprehensive set of coding conventions and best practices for all Apex classes (`_.cls`) and triggers (`_.trigger`). It ensures consistency, readability, and maintainability across your Salesforce codebase by enforcing naming conventions, code structure, and key Salesforce coding guidelines. ``` # Rule: Apex Best Practices **Description:** Enforce some best practices and naming and formatting standards for Apex code **Guidelines** - Class names must be PascalCase (For example: `AccountService`) - Method names must be camelCase - Constants must be UPPER_SNAKE_CASE - Use `@isTest` and `seeAllData=false` for all test classes - Variable names must be camelCase and descriptive (For example: `accountList` or `isClosed`) - Boolean variable names should start with 'is', 'has' ', or 'can' (For example: `isActive` or `hasAccess` ) - Use plural names for collections (For example: `contacts` or `accountsMap` ) - Avoid abbreviations and single-letter variables (For example: `account`, not `acc`) - Avoid SOQL or DML inside 'for' loops. Use Maps and Sets to bulkify logic. - DML should be in the user mode. For example: `insert as user` or `update as user`. - Use `WITH USER_MODE` explicitly for SOQL queries - Test classes must use PascalCase and end with 'Test' (For example: `AccountServiceTest`) - Test method names should describe the test scenario clearly (For example: `testCalculateTax_WithValidInput`) - When writing Asserts always use the `System.Assert `class instead of `System assert` ``` ### LWC Template Structure Rules This LWC Template Structure rule defines guidelines to ensure consistent structure and readability in Lightning web component (LWC) HTML templates. By enforcing these conventions, you make sure that your LWC templates follow best practices and remain easy to understand and maintain across your team. ``` # Rule: LWC Template Structure **Description:** Maintain consistent structure in LWC HTML files. **Guidelines:** - Wrap all content in a root `