screenshot to terminal

Author: rgarcia

cmd/browsers.go

@@ -15,6 +15,7 @@ import (
 	"strconv"
 	"strings"
 
+	"github.com/onkernel/cli/pkg/termimg"
 	"github.com/onkernel/cli/pkg/util"
 	"github.com/onkernel/kernel-go-sdk"
 	"github.com/onkernel/kernel-go-sdk/option"
@@ -595,6 +596,7 @@ type BrowsersComputerScreenshotInput struct {
 	Height     int64
 	To         string
 	HasRegion  bool
+	Display    bool
 }
 
 type BrowsersComputerTypeTextInput struct {
@@ -703,21 +705,43 @@ func (b BrowsersCmd) ComputerScreenshot(ctx context.Context, in BrowsersComputer
 		return util.CleanedUpSdkError{Err: err}
 	}
 	defer res.Body.Close()
-	if in.To == "" {
-		pterm.Error.Println("--to is required to save the screenshot")
-		return nil
-	}
-	f, err := os.Create(in.To)
+
+	// Read the image data into memory (needed for both display and save)
+	imgData, err := io.ReadAll(res.Body)
 	if err != nil {
-		pterm.Error.Printf("Failed to create file: %v\n", err)
+		pterm.Error.Printf("Failed to read screenshot data: %v\n", err)
 		return nil
 	}
-	defer f.Close()
-	if _, err := io.Copy(f, res.Body); err != nil {
-		pterm.Error.Printf("Failed to write file: %v\n", err)
+
+	// Must specify at least one output option
+	if in.To == "" && !in.Display {
+		pterm.Error.Println("specify --to to save to a file, --display to show inline, or both")
 		return nil
 	}
-	pterm.Success.Printf("Saved screenshot to %s\n", in.To)
+
+	// Display inline in terminal if requested
+	if in.Display {
+		if err := termimg.DisplayImage(os.Stdout, imgData); err != nil {
+			pterm.Error.Printf("Failed to display screenshot: %v\n", err)
+			return nil
+		}
+	}
+
+	// Save to file if requested
+	if in.To != "" {
+		f, err := os.Create(in.To)
+		if err != nil {
+			pterm.Error.Printf("Failed to create file: %v\n", err)
+			return nil
+		}
+		defer f.Close()
+		if _, err := f.Write(imgData); err != nil {
+			pterm.Error.Printf("Failed to write file: %v\n", err)
+			return nil
+		}
+		pterm.Success.Printf("Saved screenshot to %s\n", in.To)
+	}
+
 	return nil
 }
 
@@ -1904,7 +1928,7 @@ func init() {
 	computerScreenshot.Flags().Int64("width", 0, "Region width")
 	computerScreenshot.Flags().Int64("height", 0, "Region height")
 	computerScreenshot.Flags().String("to", "", "Output file path for the PNG image")
-	_ = computerScreenshot.MarkFlagRequired("to")
+	computerScreenshot.Flags().Bool("display", false, "Display screenshot inline in terminal (iTerm2/Kitty)")
 
 	computerType := &cobra.Command{Use: "type <id>", Short: "Type text on the browser instance", Args: cobra.ExactArgs(1), RunE: runBrowsersComputerTypeText}
 	computerType.Flags().String("text", "", "Text to type")
@@ -2459,6 +2483,7 @@ func runBrowsersComputerScreenshot(cmd *cobra.Command, args []string) error {
 	w, _ := cmd.Flags().GetInt64("width")
 	h, _ := cmd.Flags().GetInt64("height")
 	to, _ := cmd.Flags().GetString("to")
+	display, _ := cmd.Flags().GetBool("display")
 	bx := cmd.Flags().Changed("x")
 	by := cmd.Flags().Changed("y")
 	bw := cmd.Flags().Changed("width")
@@ -2475,7 +2500,7 @@ func runBrowsersComputerScreenshot(cmd *cobra.Command, args []string) error {
 		}
 	}
 	b := BrowsersCmd{browsers: &svc, computer: &svc.Computer}
-	return b.ComputerScreenshot(cmd.Context(), BrowsersComputerScreenshotInput{Identifier: args[0], X: x, Y: y, Width: w, Height: h, To: to, HasRegion: useRegion})
+	return b.ComputerScreenshot(cmd.Context(), BrowsersComputerScreenshotInput{Identifier: args[0], X: x, Y: y, Width: w, Height: h, To: to, HasRegion: useRegion, Display: display})
 }
 
 func runBrowsersComputerTypeText(cmd *cobra.Command, args []string) error {

cmd/browsers_test.go

@@ -1060,6 +1060,41 @@ func TestBrowsersComputerScreenshot_SavesFile(t *testing.T) {
 	assert.Equal(t, "pngDATA", string(data))
 }
 
+func TestBrowsersComputerScreenshot_RequiresOutputOption(t *testing.T) {
+	setupStdoutCapture(t)
+	fakeBrowsers := newFakeBrowsersServiceWithSimpleGet()
+	fakeComp := &FakeComputerService{CaptureScreenshotFunc: func(ctx context.Context, id string, body kernel.BrowserComputerCaptureScreenshotParams, opts ...option.RequestOption) (*http.Response, error) {
+		return &http.Response{StatusCode: 200, Header: http.Header{"Content-Type": []string{"image/png"}}, Body: io.NopCloser(strings.NewReader("pngDATA"))}, nil
+	}}
+	b := BrowsersCmd{browsers: fakeBrowsers, computer: fakeComp}
+	// Neither --to nor --display specified
+	_ = b.ComputerScreenshot(context.Background(), BrowsersComputerScreenshotInput{Identifier: "id"})
+	out := outBuf.String()
+	assert.Contains(t, out, "specify --to to save to a file, --display to show inline, or both")
+}
+
+func TestBrowsersComputerScreenshot_DisplayAndSave(t *testing.T) {
+	setupStdoutCapture(t)
+	// Set iTerm2 env var to enable display
+	origTermProgram := os.Getenv("TERM_PROGRAM")
+	defer os.Setenv("TERM_PROGRAM", origTermProgram)
+	os.Setenv("TERM_PROGRAM", "iTerm.app")
+
+	dir := t.TempDir()
+	outPath := filepath.Join(dir, "shot.png")
+	fakeBrowsers := newFakeBrowsersServiceWithSimpleGet()
+	fakeComp := &FakeComputerService{CaptureScreenshotFunc: func(ctx context.Context, id string, body kernel.BrowserComputerCaptureScreenshotParams, opts ...option.RequestOption) (*http.Response, error) {
+		return &http.Response{StatusCode: 200, Header: http.Header{"Content-Type": []string{"image/png"}}, Body: io.NopCloser(strings.NewReader("pngDATA"))}, nil
+	}}
+	b := BrowsersCmd{browsers: fakeBrowsers, computer: fakeComp}
+	// Both --display and --to specified
+	_ = b.ComputerScreenshot(context.Background(), BrowsersComputerScreenshotInput{Identifier: "id", To: outPath, Display: true})
+	// File should be saved
+	data, err := os.ReadFile(outPath)
+	assert.NoError(t, err)
+	assert.Equal(t, "pngDATA", string(data))
+}
+
 func TestBrowsersComputerPressKey_PrintsSuccess(t *testing.T) {
 	setupStdoutCapture(t)
 	fakeBrowsers := newFakeBrowsersServiceWithSimpleGet()

go.mod

@@ -6,6 +6,7 @@ require (
 	github.com/Masterminds/semver/v3 v3.4.0
 	github.com/boyter/gocodewalker v1.4.0
 	github.com/charmbracelet/fang v0.2.0
+	github.com/charmbracelet/lipgloss/v2 v2.0.0-beta.1
 	github.com/golang-jwt/jwt/v5 v5.2.2
 	github.com/joho/godotenv v1.5.1
 	github.com/onkernel/kernel-go-sdk v0.21.0
@@ -25,7 +26,6 @@ require (
 	atomicgo.dev/keyboard v0.2.9 // indirect
 	atomicgo.dev/schedule v0.1.0 // indirect
 	github.com/charmbracelet/colorprofile v0.3.0 // indirect
-	github.com/charmbracelet/lipgloss/v2 v2.0.0-beta.1 // indirect
 	github.com/charmbracelet/x/ansi v0.8.0 // indirect
 	github.com/charmbracelet/x/cellbuf v0.0.13 // indirect
 	github.com/charmbracelet/x/exp/charmtone v0.0.0-20250603201427-c31516f43444 // indirect

pkg/termimg/termimg.go

@@ -0,0 +1,149 @@
+// Package termimg provides utilities for displaying images inline in terminal emulators.
+// It supports iTerm2 and Kitty graphics protocols.
+package termimg
+
+import (
+	"encoding/base64"
+	"fmt"
+	"io"
+	"os"
+
+	"golang.org/x/term"
+)
+
+// TerminalType represents the type of terminal emulator.
+type TerminalType int
+
+const (
+	TerminalUnknown TerminalType = iota
+	TerminaliTerm2
+	TerminalKitty
+	TerminalGhostty
+)
+
+func (t TerminalType) String() string {
+	switch t {
+	case TerminaliTerm2:
+		return "iTerm2"
+	case TerminalKitty:
+		return "Kitty"
+	case TerminalGhostty:
+		return "Ghostty"
+	default:
+		return "Unknown"
+	}
+}
+
+// DetectTerminal returns the type of terminal emulator based on environment variables.
+func DetectTerminal() TerminalType {
+	termProgram := os.Getenv("TERM_PROGRAM")
+	// Check for iTerm2
+	if termProgram == "iTerm.app" {
+		return TerminaliTerm2
+	}
+	// Check for Ghostty (uses Kitty graphics protocol)
+	if termProgram == "ghostty" {
+		return TerminalGhostty
+	}
+	// Check for Kitty
+	if os.Getenv("KITTY_WINDOW_ID") != "" {
+		return TerminalKitty
+	}
+	return TerminalUnknown
+}
+
+// IsSupported returns true if the current terminal supports inline image display.
+func IsSupported() bool {
+	return DetectTerminal() != TerminalUnknown
+}
+
+// getTerminalSize returns the terminal width and height in columns and rows.
+// Returns default values if the size cannot be determined.
+func getTerminalSize() (cols, rows int) {
+	// Default to reasonable values if we can't detect
+	cols, rows = 80, 24
+
+	// Try stdout first, then stdin
+	for _, fd := range []int{int(os.Stdout.Fd()), int(os.Stdin.Fd())} {
+		if term.IsTerminal(fd) {
+			if w, h, err := term.GetSize(fd); err == nil {
+				return w, h
+			}
+		}
+	}
+	return cols, rows
+}
+
+// DisplayImage writes escape sequences to display the given image data inline.
+// The image data should be raw PNG/JPEG bytes.
+func DisplayImage(w io.Writer, img []byte) error {
+	term := DetectTerminal()
+	switch term {
+	case TerminaliTerm2:
+		return displayiTerm2(w, img)
+	case TerminalKitty, TerminalGhostty:
+		// Ghostty uses the Kitty graphics protocol
+		return displayKitty(w, img)
+	default:
+		return fmt.Errorf("terminal does not support inline images (detected: %s). Try using iTerm2, Kitty, or Ghostty, or use --to to save to a file", term)
+	}
+}
+
+// displayiTerm2 renders an image using iTerm2's inline images protocol.
+// Protocol: ESC ] 1337 ; File = [args] : base64data BEL
+// https://iterm2.com/documentation-images.html
+func displayiTerm2(w io.Writer, img []byte) error {
+	encoded := base64.StdEncoding.EncodeToString(img)
+	// inline=1 displays the image inline
+	// width=100% fills terminal width, height=auto preserves aspect ratio
+	// preserveAspectRatio=1 maintains aspect ratio
+	_, err := fmt.Fprintf(w, "\033]1337;File=inline=1;width=100%%;height=auto;preserveAspectRatio=1:%s\a", encoded)
+	return err
+}
+
+// displayKitty renders an image using Kitty's graphics protocol.
+// Protocol uses chunked transmission for large images.
+// https://sw.kovidgoyal.net/kitty/graphics-protocol/
+func displayKitty(w io.Writer, img []byte) error {
+	encoded := base64.StdEncoding.EncodeToString(img)
+
+	// Kitty requires chunked transmission for data over 4096 bytes
+	const chunkSize = 4096
+
+	for i := 0; i < len(encoded); i += chunkSize {
+		end := i + chunkSize
+		if end > len(encoded) {
+			end = len(encoded)
+		}
+		chunk := encoded[i:end]
+
+		// m=1 means more chunks coming, m=0 means last chunk
+		// a=T means transmit and display
+		// f=100 means PNG format (also works for JPEG)
+		if i == 0 {
+			// First chunk includes all the parameters
+			more := 1
+			if end >= len(encoded) {
+				more = 0
+			}
+			_, err := fmt.Fprintf(w, "\033_Ga=T,f=100,m=%d;%s\033\\", more, chunk)
+			if err != nil {
+				return err
+			}
+		} else {
+			// Subsequent chunks only need the 'm' parameter
+			more := 1
+			if end >= len(encoded) {
+				more = 0
+			}
+			_, err := fmt.Fprintf(w, "\033_Gm=%d;%s\033\\", more, chunk)
+			if err != nil {
+				return err
+			}
+		}
+	}
+
+	// Print a newline after the image so subsequent output appears below
+	_, err := fmt.Fprintln(w)
+	return err
+}