From f8ec48095a2c4c1d2eb3836491c9ffcd625d7911 Mon Sep 17 00:00:00 2001
From: hhang <17309584214@163.com>
Date: Wed, 4 Nov 2026 19:10:35 +0800
Subject: [PATCH] fix(cli): guide delimited analysis view exports (#8730)

Co-authored-by: hhang <169027046+xu91102@users.noreply.github.com>
---
 docs/cli.md                                        |  5 ++++-
 src/cli/analysisViewCommands.ts                    |  2 +-
 .../boundary/cli/delimitedAnalysisViewCli.test.ts  | 14 ++++++++++++++
 3 files changed, 19 insertions(+), 2 deletions(-)

diff --git a/docs/cli.md b/docs/cli.md
index 659bdc635b..bcb344daaf 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -1196,9 +1196,12 @@ treated as malformed.
 exact array path with `--filter-output` and provide comma-separated direct
 scalar columns with `--columns`; column order is the output column order:
 
+For an artifact inventory request that selects the `occurrences` collection
+and includes `logical_path` and `artifact_id` in its view fields:
+
 ```bash
 rea inspect-analysis-view request.json --format csv \
-  --filter-output normalized_result.rows --columns name,address
+  --filter-output normalized_result.items --columns logical_path,artifact_id
 ```
 
 The first line is a REA metadata record,
diff --git a/src/cli/analysisViewCommands.ts b/src/cli/analysisViewCommands.ts
index 427ab6709b..90f8b86947 100644
--- a/src/cli/analysisViewCommands.ts
+++ b/src/cli/analysisViewCommands.ts
@@ -73,7 +73,7 @@ export const registerAnalysisViewCommands = (
   });
   cli.command(CLI_COMMANDS.inspectAnalysisView, {
     description:
-      "Project a selected view of completed Evidence JSON for a supported analysis operation",
+      "Project a selected view of completed Evidence JSON for a supported analysis operation. For inventory rows, use --format csv or --format tsv with --filter-output normalized_result.items and --columns logical_path,artifact_id (if those fields are included in the view).",
     args: z.object({
       inputJson: z.string().describe("Inline workflow JSON or JSON file path"),
     }),
diff --git a/tests/boundary/cli/delimitedAnalysisViewCli.test.ts b/tests/boundary/cli/delimitedAnalysisViewCli.test.ts
index f83202a18a..e2f8e377b6 100644
--- a/tests/boundary/cli/delimitedAnalysisViewCli.test.ts
+++ b/tests/boundary/cli/delimitedAnalysisViewCli.test.ts
@@ -7,6 +7,20 @@ import { ARTIFACT_COMPARISON_EXAMPLE } from "../../../src/contracts/artifactComp
 import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js";
 import { cliTest } from "../../support/cli/cliFixture.js";
 
+cliTest(
+  "shows how to export inventory rows in command help",
+  async ({ cli }) => {
+    const result = await cli.run({
+      arguments: ["inspect-analysis-view", "--help"],
+    });
+    expect(result.exitCode).toBe(0);
+    expect(result.stdout).toContain("--format csv");
+    expect(result.stdout).toContain("--format tsv");
+    expect(result.stdout).toContain("--filter-output normalized_result.items");
+    expect(result.stdout).toContain("--columns logical_path,artifact_id");
+  },
+);
+
 cliTest(
   "exports selected artifact inventory columns through the public CLI",
   async ({ cli }) => {