docs: bring Juliet's suggestions, change to --api-name

Author: WillieRuemmele

command-snapshot.json

@@ -219,7 +219,7 @@
     "flagAliases": [],
     "flagChars": ["n", "o", "s", "w"],
     "flags": [
-      "agent-api-name",
+      "api-name",
       "api-version",
       "batch-size",
       "flags-dir",

messages/agent.test.run-eval.md

@@ -8,25 +8,25 @@ Execute rich evaluation tests against an Agentforce agent using the Einstein Eva
 
 When you provide a YAML test spec, the command automatically translates test cases into Evaluation API calls and infers the agent name from the spec's `subjectName` field. This means you can use the same test spec with both `sf agent test run` and `sf agent test run-eval`.
 
-When you provide a JSON payload, it's sent directly to the API with optional normalization. The normalizer auto-corrects common field name mistakes, converts shorthand references to JSONPath, and injects defaults. Use `--no-normalize` to disable.
+When you provide a JSON payload, it's sent directly to the API 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.
 
-Supports 8+ evaluator types including topic routing assertions, action invocation checks, string/numeric assertions, semantic similarity scoring, and LLM-based quality ratings.
+Supports 8+ evaluator types, including topic routing assertions, action invocation checks, string/numeric assertions, semantic similarity scoring, and LLM-based quality ratings.
 
 # flags.spec.summary
 
 Path to test spec file (YAML or JSON). Use `-` for stdin.
 
-# flags.agent-api-name.summary
+# flags.api-name.summary
 
-Agent DeveloperName to resolve agent_id and agent_version_id. Auto-inferred from YAML spec's subjectName.
+Agent DeveloperName (also called API name) to resolve agent_id and agent_version_id. Auto-inferred from the YAML spec's subjectName.
 
 # flags.wait.summary
 
 Number of minutes to wait for results.
 
 # flags.result-format.summary
 
-Output format: human, json, junit, or tap.
+Format of the agent test results.
 
 # flags.batch-size.summary
 
@@ -38,54 +38,54 @@ Disable auto-normalization of field names and shorthand references.
 
 # examples
 
-- Run tests from a YAML test spec:
+- Run tests using a YAML test spec on the org with alias "my-org":
 
   <%= config.bin %> <%= command.id %> --spec tests/my-agent-testSpec.yaml --target-org my-org
 
-- Run tests from a YAML spec with explicit agent name override:
+- Run tests using a YAML spec with explicit agent name override; use your default org:
 
-  <%= config.bin %> <%= command.id %> --spec tests/my-agent-testSpec.yaml --agent-api-name My_Agent --target-org my-org
+  <%= config.bin %> <%= command.id %> --spec tests/my-agent-testSpec.yaml --api-name My_Agent --target-org my-org
 
-- Run tests from a JSON payload:
+- Run tests using a JSON payload:
 
   <%= config.bin %> <%= command.id %> --spec tests/eval-payload.json --target-org my-org
 
-- JUnit output for CI/CD:
+- Run tests and output results in JUnit format; useful for continuous integration and deployment (CI/CD):
 
   <%= config.bin %> <%= command.id %> --spec tests/my-agent-testSpec.yaml --target-org my-org --result-format junit
 
 - Pipe JSON payload from stdin:
 
-  echo '{"tests":[...]}' | <%= config.bin %> <%= command.id %> --spec - --target-org my-org
+  $ echo '{"tests":[...]}' | <%= config.bin %> <%= command.id %> --spec - --target-org my-org
 
 # info.batchProgress
 
 Running batch %s of %s (%s tests)...
 
 # info.testComplete
 
-Test %s: %s
+Test %s: %s.
 
 # info.summary
 
-Results: %s passed, %s failed, %s scored, %s errors
+Results: %s passed, %s failed, %s scored, %s errors.
 
 # info.yamlDetected
 
 Detected YAML test spec for agent '%s' with %s test case(s). Translating to Evaluation API format.
 
 # error.invalidPayload
 
-Invalid test payload: %s
+Invalid test payload: %s.
 
 # error.apiError
 
 Einstein Eval API error (HTTP %s): %s
 
 # error.agentNotFound
 
-No agent found with DeveloperName '%s'. Verify the agent exists in the target org.
+No agent found with DeveloperName (also API name) '%s'. Verify that the agent exists in the target org.
 
 # error.agentVersionNotFound
 
-No published version found for agent '%s'. Ensure the agent has been published at least once.
+No published version found for agent '%s'. Make sure the agent has been published at least once.

src/commands/agent/test/run-eval.ts

@@ -148,9 +148,9 @@ export default class AgentTestRunEval extends SfCommand<RunEvalResult> {
       summary: messages.getMessage('flags.spec.summary'),
       allowStdin: true,
     }),
-    'agent-api-name': Flags.string({
+    'api-name': Flags.string({
       char: 'n',
-      summary: messages.getMessage('flags.agent-api-name.summary'),
+      summary: messages.getMessage('flags.api-name.summary'),
     }),
     wait: Flags.integer({
       char: 'w',
@@ -190,14 +190,14 @@ export default class AgentTestRunEval extends SfCommand<RunEvalResult> {
 
     // 2. Detect format and parse
     let payload: EvalPayload;
-    let agentApiName = flags['agent-api-name'];
+    let agentApiName = flags['api-name'];
 
     if (isYamlTestSpec(rawContent)) {
       // YAML TestSpec detected — translate to EvalPayload
       const spec = parseTestSpec(rawContent);
       payload = translateTestSpec(spec);
 
-      // Auto-infer agent-api-name from subjectName if not explicitly provided
+      // Auto-infer api-name from subjectName if not explicitly provided
       if (!agentApiName) {
         agentApiName = spec.subjectName;
         this.log(messages.getMessage('info.yamlDetected', [spec.subjectName, spec.testCases.length.toString()]));
@@ -215,7 +215,7 @@ export default class AgentTestRunEval extends SfCommand<RunEvalResult> {
       throw messages.createError('error.invalidPayload', ['missing or empty "tests" array']);
     }
 
-    // 3. If --agent-api-name (or auto-inferred from YAML), resolve IDs and inject
+    // 3. If --api-name (or auto-inferred from YAML), resolve IDs and inject
     if (agentApiName) {
       const { agentId, versionId } = await resolveAgent(org, agentApiName);
       for (const test of payload.tests) {

test/nuts/agent.test.run-eval.nut.ts

@@ -37,7 +37,7 @@ describe('agent test run-eval', function () {
 
   describe('run-eval with JSON file', () => {
     it('should run evaluation with JSON payload file', async () => {
-      const command = `agent test run-eval --spec ${jsonPayloadPath} --agent-api-name Local_Info_Agent --target-org ${getUsername()} --json`;
+      const command = `agent test run-eval --spec ${jsonPayloadPath} --api-name Local_Info_Agent --target-org ${getUsername()} --json`;
       const output = execCmd<RunEvalResult>(command, {
         ensureExitCode: 0,
       }).jsonOutput;
@@ -53,7 +53,7 @@ describe('agent test run-eval', function () {
     });
 
     it('should run evaluation with normalized payload', async () => {
-      const command = `agent test run-eval --spec ${jsonPayloadPath} --agent-api-name Local_Info_Agent --target-org ${getUsername()} --json`;
+      const command = `agent test run-eval --spec ${jsonPayloadPath} --api-name Local_Info_Agent --target-org ${getUsername()} --json`;
       const output = execCmd<RunEvalResult>(command, {
         ensureExitCode: 0,
       }).jsonOutput;
@@ -84,15 +84,15 @@ describe('agent test run-eval', function () {
         ensureExitCode: 0,
       }).jsonOutput;
 
-      // Should succeed without explicit --agent-api-name flag
+      // Should succeed without explicit --api-name flag
       expect(output?.result).to.be.ok;
       expect(output?.result.tests).to.be.an('array');
     });
   });
 
   describe('run-eval with stdin', () => {
     it('should run evaluation with JSON payload from stdin', async () => {
-      const command = `cat ${jsonPayloadPath} | sf agent test run-eval --spec - --agent-api-name Local_Info_Agent --target-org ${getUsername()} --json`;
+      const command = `cat ${jsonPayloadPath} | sf agent test run-eval --spec - --api-name Local_Info_Agent --target-org ${getUsername()} --json`;
       const output = execCmd<RunEvalResult>(command, {
         ensureExitCode: 0,
         cli: 'sf',
@@ -118,7 +118,7 @@ describe('agent test run-eval', function () {
 
   describe('run-eval with flags', () => {
     it('should respect --no-normalize flag', async () => {
-      const command = `agent test run-eval --spec ${jsonPayloadPath} --agent-api-name Local_Info_Agent --no-normalize --target-org ${getUsername()} --json`;
+      const command = `agent test run-eval --spec ${jsonPayloadPath} --api-name Local_Info_Agent --no-normalize --target-org ${getUsername()} --json`;
       const output = execCmd<RunEvalResult>(command, {
         ensureExitCode: 0,
       }).jsonOutput;
@@ -128,7 +128,7 @@ describe('agent test run-eval', function () {
     });
 
     it('should use custom batch size', async () => {
-      const command = `agent test run-eval --spec ${jsonPayloadPath} --agent-api-name Local_Info_Agent --batch-size 1 --target-org ${getUsername()} --json`;
+      const command = `agent test run-eval --spec ${jsonPayloadPath} --api-name Local_Info_Agent --batch-size 1 --target-org ${getUsername()} --json`;
       const output = execCmd<RunEvalResult>(command, {
         ensureExitCode: 0,
       }).jsonOutput;
@@ -139,7 +139,7 @@ describe('agent test run-eval', function () {
 
     it('should support different result formats', async () => {
       // Test human format (default)
-      const humanCommand = `agent test run-eval --spec ${jsonPayloadPath} --agent-api-name Local_Info_Agent --result-format human --target-org ${getUsername()}`;
+      const humanCommand = `agent test run-eval --spec ${jsonPayloadPath} --api-name Local_Info_Agent --result-format human --target-org ${getUsername()}`;
       const humanOutput = execCmd(humanCommand, {
         ensureExitCode: 0,
       }).shellOutput.stdout;
@@ -148,15 +148,15 @@ describe('agent test run-eval', function () {
       expect(humanOutput).to.be.a('string');
 
       // Test tap format
-      const tapCommand = `agent test run-eval --spec ${jsonPayloadPath} --agent-api-name Local_Info_Agent --result-format tap --target-org ${getUsername()}`;
+      const tapCommand = `agent test run-eval --spec ${jsonPayloadPath} --api-name Local_Info_Agent --result-format tap --target-org ${getUsername()}`;
       const tapOutput = execCmd(tapCommand, {
         ensureExitCode: 0,
       }).shellOutput.stdout;
 
       expect(tapOutput).to.include('TAP version');
 
       // Test junit format
-      const junitCommand = `agent test run-eval --spec ${jsonPayloadPath} --agent-api-name Local_Info_Agent --result-format junit --target-org ${getUsername()}`;
+      const junitCommand = `agent test run-eval --spec ${jsonPayloadPath} --api-name Local_Info_Agent --result-format junit --target-org ${getUsername()}`;
       const junitOutput = execCmd(junitCommand, {
         ensureExitCode: 0,
       }).shellOutput.stdout;
@@ -169,7 +169,7 @@ describe('agent test run-eval', function () {
   describe('run-eval error handling', () => {
     it('should fail with invalid JSON payload', async () => {
       const invalidJson = join(mockProjectDir, 'invalid-payload.json');
-      const command = `agent test run-eval --spec ${invalidJson} --agent-api-name Local_Info_Agent --target-org ${getUsername()} --json`;
+      const command = `agent test run-eval --spec ${invalidJson} --api-name Local_Info_Agent --target-org ${getUsername()} --json`;
 
       try {
         execCmd<RunEvalResult>(command);
@@ -180,7 +180,7 @@ describe('agent test run-eval', function () {
     });
 
     it('should fail when agent not found', async () => {
-      const command = `agent test run-eval --spec ${jsonPayloadPath} --agent-api-name NonExistentAgent --target-org ${getUsername()} --json`;
+      const command = `agent test run-eval --spec ${jsonPayloadPath} --api-name NonExistentAgent --target-org ${getUsername()} --json`;
 
       try {
         execCmd<RunEvalResult>(command);
@@ -191,7 +191,7 @@ describe('agent test run-eval', function () {
     });
 
     it('should require --spec flag', async () => {
-      const command = `agent test run-eval --agent-api-name Local_Info_Agent --target-org ${getUsername()} --json`;
+      const command = `agent test run-eval --api-name Local_Info_Agent --target-org ${getUsername()} --json`;
 
       try {
         execCmd<RunEvalResult>(command);
@@ -204,7 +204,7 @@ describe('agent test run-eval', function () {
 
   describe('run-eval output structure', () => {
     it('should include test summaries with correct structure', async () => {
-      const command = `agent test run-eval --spec ${jsonPayloadPath} --agent-api-name Local_Info_Agent --target-org ${getUsername()} --json`;
+      const command = `agent test run-eval --spec ${jsonPayloadPath} --api-name Local_Info_Agent --target-org ${getUsername()} --json`;
       const output = execCmd<RunEvalResult>(command, {
         ensureExitCode: 0,
       }).jsonOutput;
@@ -218,7 +218,7 @@ describe('agent test run-eval', function () {
     });
 
     it('should include summary with all metrics', async () => {
-      const command = `agent test run-eval --spec ${jsonPayloadPath} --agent-api-name Local_Info_Agent --target-org ${getUsername()} --json`;
+      const command = `agent test run-eval --spec ${jsonPayloadPath} --api-name Local_Info_Agent --target-org ${getUsername()} --json`;
       const output = execCmd<RunEvalResult>(command, {
         ensureExitCode: 0,
       }).jsonOutput;