From 82d69ce1206c7cf44b948bb28c2874f1951383d2 Mon Sep 17 00:00:00 2001
From: i-trytoohard <ayetrytoohard@gmail.com>
Date: Tue, 23 Jun 2026 01:28:06 +0530
Subject: [PATCH] feat(cli): add examples to ao preview --help (#388)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* feat(cli): add examples to ao preview --help (#387)

Update the preview command help to include a concise Examples section
covering the four common workflows:

  ao preview
  ao preview file:///home/aoagent/ReverbCode/index.html
  ao preview http://localhost:5173
  ao preview clear

Replace the workspace-relative path (./dist/index.html) in the Long
description with the absolute file:// URL pattern agents actually use.

Command syntax and behavior are unchanged.

Closes #387

* fix(cli): clarify no-arg preview fallback behavior in help text

Address review feedback on #388: the no-argument description now
reflects the daemon's actual behavior — autodetect the workspace
entry point, fall back to the session's existing preview target
when none exists.

---------

Co-authored-by: AO Bot <ao-bot@composio.dev>
---
 backend/internal/cli/preview.go      | 11 ++++++++---
 backend/internal/cli/preview_test.go | 18 ++++++++++++++++++
 2 files changed, 26 insertions(+), 3 deletions(-)

diff --git a/backend/internal/cli/preview.go b/backend/internal/cli/preview.go
index b57dd48a4..4517b7361 100644
--- a/backend/internal/cli/preview.go
+++ b/backend/internal/cli/preview.go
@@ -23,9 +23,14 @@ func newPreviewCommand(ctx *commandContext) *cobra.Command {
 		Use:   "preview [url]",
 		Short: "Open a URL (or the workspace's index.html) in the desktop browser panel for the current session",
 		Long: "Open a URL in the desktop browser panel for the current session.\n\n" +
-			"With no argument it opens the workspace's index.html. A workspace-relative path\n" +
-			"(e.g. ./dist/index.html) is served as a local file. Use `ao preview\n" +
-			"clear` to empty the panel.",
+			"With no argument it opens the workspace's static entry point, falling\n" +
+			"back to this session's existing preview target when no entry point exists.\n" +
+			"A local file can be opened by its absolute file:// URL\n" +
+			"(e.g. file:///home/me/proj/index.html). Use `ao preview clear` to empty the panel.",
+		Example: `  ao preview
+  ao preview file://$(pwd)/index.html
+  ao preview http://localhost:5173
+  ao preview clear`,
 		Args: cobra.MaximumNArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			var target string
diff --git a/backend/internal/cli/preview_test.go b/backend/internal/cli/preview_test.go
index 5da492ba8..ad12e85a2 100644
--- a/backend/internal/cli/preview_test.go
+++ b/backend/internal/cli/preview_test.go
@@ -154,6 +154,24 @@ func TestPreview_MissingSessionIDIsUsageError(t *testing.T) {
 	}
 }
 
+func TestPreview_HelpIncludesExamples(t *testing.T) {
+	out, _, err := executeCLI(t, Deps{}, "preview", "--help")
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	// Examples section present.
+	if !strings.Contains(out, "EXAMPLES") && !strings.Contains(out, "Examples") {
+		t.Errorf("help output missing Examples section:\n%s", out)
+	}
+	// file:// URL example (not a relative path).
+	if !strings.Contains(out, "file://$(pwd)/index.html") {
+		t.Errorf("help output missing file:// example:\n%s", out)
+	}
+	if strings.Contains(out, "./dist/index.html") {
+		t.Errorf("help output still references relative ./dist/index.html:\n%s", out)
+	}
+}
+
 func TestPreview_BlankSessionIDIsUsageError(t *testing.T) {
 	t.Setenv("AO_SESSION_ID", " \t ")
 	cfg := setConfigEnv(t)