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.
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”:
j