diff --git a/messages/agent.activate.md b/messages/agent.activate.md
index be4a68f..d03814e 100644
--- a/messages/agent.activate.md
+++ b/messages/agent.activate.md
@@ -4,27 +4,29 @@ Activate an agent in an org.
 
 # description
 
-Activating an agent makes it immediately available to your users. An agent must be active before you can preview it with the "agent preview" CLI command or VS Code.
+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.
 
-You must know the agent's API name to activate it; you can either be prompted for it or you can specify it with the --api-name flag. Find the agent's API name in its Agent Details page of your org's Agentforce Studio UI in Setup.
+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.
 
 # examples
 
-- Activate an agent in your default target org by being prompted:
+- Activate an agent in your default target org by being prompted for both its API name and version:
 
   <%= config.bin %> <%= command.id %>
 
-- Activate an agent with API name Resort_Manager in the org with alias "my-org":
+- Activate version 2 of an agent with API name Resort_Manager in the org with alias "my-org":
 
-  <%= config.bin %> <%= command.id %> --api-name Resort_Manager --target-org my-org
+  <%= config.bin %> <%= command.id %> --api-name Resort_Manager --version 2 --target-org my-org
 
 # flags.api-name.summary
 
-API name of the agent to activate.
+API name of the agent to activate; if not specified, the command provides a list that you choose from.
 
 # flags.version.summary
 
-Version number of the agent to activate.
+Version number of the agent to activate; if not specified, the command provides a list that you choose from.
 
 # error.missingRequiredFlags
 
diff --git a/messages/agent.deactivate.md b/messages/agent.deactivate.md
index 7303405..06f3975 100644
--- a/messages/agent.deactivate.md
+++ b/messages/agent.deactivate.md
@@ -6,7 +6,7 @@ Deactivate an agent in an org.
 
 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.
 
-You must know the agent's API name to deactivate it; you can either be prompted for it or you can specify it with the --api-name flag. Find the agent's API name in its Agent Details page of your org's Agentforce Studio UI in Setup.
+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.
 
 # examples
 
@@ -20,7 +20,7 @@ You must know the agent's API name to deactivate it; you can either be prompted
 
 # flags.api-name.summary
 
-API name of the agent to deactivate.
+API name of the agent to deactivate; if not specified, the command provides a list that you choose from.
 
 # error.missingRequiredFlags