Add browse cdp command for streaming CDP events

[derekmeegan]

Summary

• Adds browse cdp <url|port> command that connects to any CDP WebSocket target and streams DevTools protocol events as NDJSON to stdout
• Supports --domain filtering (defaults to Network, Console, Runtime, Log, Page), --pretty for human-readable output
• Auto-attaches to page targets and enables CDP domains per session, handles multi-tab scenarios
• Output is pipeable to files (browse cdp ws://... > log.jsonl) or jq (browse cdp ws://... | jq '.method')
• Accepts bare port numbers (e.g. browse cdp 9222) via existing resolveWsTarget utility

Test plan

• Tested NDJSON output piped to file against a Browserbase session
• Tested --pretty mode shows human-readable event summaries
• Verified jq compatibility with NDJSON output
• Tested graceful SIGINT shutdown
• Test against local Chrome with --remote-debugging-port=9222
• Test --domain filtering (e.g. --domain Network only)

🤖 Generated with Claude Code

[changeset-bot]

🦋 Changeset detected

Latest commit: 253cf91

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 0 packages

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[cubic-dev-ai]

1 issue found across 2 files

Confidence score: 4/5

• This PR looks safe to merge overall: the reported issue is low-to-moderate severity (4/10) and focused on error visibility rather than core command execution flow.
• In packages/cli/src/index.ts, CDP command failures are currently only surfaced in pretty output, so NDJSON users can miss invalid domains or failed enable calls when piping output.
• Pay close attention to packages/cli/src/index.ts - ensure CDP errors are logged in NDJSON mode to avoid silent operational failures.

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="packages/cli/src/index.ts">

<violation number="1" location="packages/cli/src/index.ts:2962">
P2: Log CDP command errors even in NDJSON mode. Right now errors are only printed in pretty mode, so invalid domains or failed enable calls are silently ignored when piping output.</violation>
</file>

Architecture diagram

sequenceDiagram
    participant User as User / Shell
    participant CLI as Browse CLI
    participant Resolver as resolveWsTarget
    participant Browser as CDP Server (Chrome/Browserbase)

    Note over User,Browser: Initialization Flow
    User->>CLI: browse cdp <url|port> [--pretty] [--domain]
    CLI->>Resolver: resolveWsTarget(target)
    Resolver-->>CLI: ws://... URL
    
    CLI->>Browser: NEW: Establish WebSocket Connection
    
    opt Connection Successful
        Browser-->>CLI: onOpen
        CLI->>Browser: NEW: Target.setAutoAttach (filter: page)
        CLI->>Browser: NEW: Target.setDiscoverTargets (discover: true)
    end

    Note over User,Browser: Session & Event Handling
    
    loop Every Message
        Browser-->>CLI: Protocol Message (NDJSON)
        
        alt Message is response to CLI command
            CLI->>CLI: Match ID & discard
        else NEW: Message is "Target.attachedToTarget"
            CLI->>CLI: Track targetId -> sessionId map
            loop for each requested domain
                CLI->>Browser: NEW: [Domain].enable (with sessionId)
            end
        else NEW: Message is "Target.detachedFromTarget"
            CLI->>CLI: Remove session from tracking
        else NEW: General CDP Event (Network/Console/etc)
            alt --pretty flag set
                CLI->>CLI: Format human-readable string
            else default (NDJSON)
                CLI->>CLI: Stringify original JSON
            end
            
            CLI->>User: Write to stdout (+ \n)
            
            opt Pipe Broken (EPIPE)
                CLI->>CLI: Graceful exit(0)
            end
        end
    end

    Note over User,Browser: Shutdown Flow
    
    alt SIGINT / SIGTERM received
        CLI->>Browser: Close WebSocket
        CLI->>User: Exit process
    else Browser closes connection
        CLI-->>User: "Disconnected" (if --pretty)
    end

Loading

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}