Chromium Helper CLI

A powerful command-line tool for searching and exploring Chromium and PDFium source code using Google's official APIs. Features comprehensive Gerrit integration, issue tracking, and support for both Chromium and PDFium projects.

✨ Features

• 🔍 Advanced Code Search - Search Chromium and PDFium codebases with powerful syntax
• 📜 Git History & Blame - View file blame, commit history, and top contributors
• 🔧 Complete Gerrit Integration - View CLs, comments, diffs, and file content for both projects
• 🤖 Try-Bot Status - View LUCI try-bot results with detailed error messages and stack traces
• 🐛 Bot Error Analysis - Get detailed test failures with full error output and filtering by bot name
• 🐛 Issue Tracking - Search and view Chromium issues with detailed information
• 📊 PDFium Support - Full support for PDFium Gerrit operations and code search
• 🎨 Multiple Output Formats - JSON, table, and plain text formats for different use cases
• ⚡ Fast & Reliable - Uses official Google APIs for real-time data
• 🌐 Direct Links - Every result includes clickable URLs to view code online
• 🤖 AI-Friendly - Perfect for integration with AI systems, shell scripts, and automation

🚀 Quick Start

# Option 1: Use instantly (no installation needed!)
npx chromium-helper search "LOG(INFO)" --limit 5
npx chromium-helper blame "base/logging.h" --line 100
npx chromium-helper gerrit status 6624568
npx chromium-helper issues search "memory leak" --limit 10

# Option 2: Install globally for short 'ch' alias
npm install -g chromium-helper

# Then use with short commands
ch search "memory leak" --case-sensitive --format json
ch history "chrome/browser/ui/browser.cc" --limit 20
ch contributors "third_party/blink/renderer/"
ch gerrit status 6624568
ch pdfium status 130850

🤖 AI Assistant Integration

Works with any AI coding assistant (Claude, Cursor, Gemini, etc.):

# Tell your AI: "Run npx ch --ai to learn about chromium-helper"
npx ch --ai

The AI will learn all commands and help you explore Chromium's codebase!

📦 Installation

Option 1: Instant Usage with npx (Recommended)

No installation required! Just run any command:

npx chromium-helper search "Browser::Create" --format json
npx chromium-helper gerrit status 6624568
npx chromium-helper issues search "security" --limit 20

Option 2: Global Installation

For faster startup and short 'ch' alias:

npm install -g chromium-helper
# Now available as 'chromium-helper' and 'ch'

Option 3: From Source

git clone https://github.com/hjanuschka/chromium-helper.git
cd chromium-helper/chromium-helper-cli
npm install && npm run build
npm link  # Optional: Make globally available

📖 Commands

search - Search Chromium Source Code

Search for code patterns in the Chromium codebase.

ch search <query> [options]

# Aliases: s

Options:
  -c, --case-sensitive          Case sensitive search
  -l, --language <lang>         Filter by programming language (cpp, javascript, python, etc.)
  -p, --file-pattern <pattern>  File pattern filter (*.cc, *.h, chrome/browser/*, etc.)
  -t, --type <type>             Search type: content|function|class|symbol|comment
  --exclude-comments            Exclude comments from search results
  --limit <number>              Maximum number of results (default: 20)

Examples:

# Basic text search
ch search "LOG(INFO)"

# Function search
ch search "CreateWindow" --type function

# Class search in C++ headers  
ch search "Browser" --type class --file-pattern "*.h"

# Search excluding comments
ch search "TODO" --exclude-comments

# Language-specific search
ch search "addEventListener" --language javascript

symbol - Find Symbol Definitions and Usage

Find where symbols (functions, classes, variables) are defined and used.

ch symbol <symbol> [options]

# Aliases: sym

Options:
  -f, --file <path>  File path context for symbol resolution

Examples:

# Find Browser symbol
ch symbol "Browser"

# Find with file context
ch symbol "CreateWindow" --file "chrome/browser/ui/browser.cc"

file - Get File Content

Fetch the content of any file from Chromium source.

ch file <path> [options]

# Aliases: f

Options:
  -s, --start <line>  Starting line number
  -e, --end <line>    Ending line number

Examples:

# Get entire file
ch file "base/logging.h"

# Get specific line range
ch file "chrome/browser/ui/browser.h" --start 100 --end 200

# Get from line 50 to end
ch file "content/browser/browser_context.h" --start 50

owners - Find OWNERS Files

Find OWNERS files for a given file path to identify code reviewers.

ch owners <path>

# Aliases: own

Examples:

# Find owners for a specific file
ch owners "chrome/browser/ui/browser.cc"

# Find owners for a directory
ch owners "third_party/blink/renderer/"

commits - Search Commit History

Search commit messages and metadata in the Chromium repository.

ch commits <query> [options]

# Aliases: cm

Options:
  -a, --author <author>    Filter by author name or email
  --since <date>           Commits after date (YYYY-MM-DD)
  --until <date>           Commits before date (YYYY-MM-DD)
  --limit <number>         Maximum number of results (default: 20)

Examples:

# Search commit messages
ch commits "password manager"

# Search by author
ch commits "security fix" --author "chrome-security"

# Search in date range
ch commits "memory leak" --since "2023-01-01" --until "2023-12-31"

blame - Git Blame for Files

Show git blame information for a file, including author, commit, and date for each line.

ch blame <file> [options]

Options:
  -l, --line <number>  Show blame for specific line number

Examples:

# Show blame for entire file
ch blame "base/logging.h"

# Show blame for specific line
ch blame "chrome/browser/ui/browser.cc" --line 150

# JSON output for processing
ch blame "content/browser/browser_context.h" --format json

history - File Commit History

Show the commit history for a specific file.

ch history <file> [options]

# Aliases: log

Options:
  -l, --limit <number>  Maximum number of commits to show (default: 20)

Examples:

# Show last 20 commits for a file
ch history "base/logging.h"

# Show last 50 commits
ch history "chrome/browser/ui/browser.cc" --limit 50

# JSON output for processing
ch history "content/browser/browser_context.h" --format json --limit 100

contributors - Top Contributors

Show the top contributors for a file or directory path, ranked by commit count.

ch contributors <path> [options]

Options:
  -l, --limit <number>  Maximum number of commits to analyze (default: 50)

Examples:

# Show top contributors for a file
ch contributors "base/logging.h"

# Show contributors for a directory
ch contributors "chrome/browser/ui/"

# Analyze more commits for better accuracy
ch contributors "third_party/blink/renderer/" --limit 100

# JSON output for processing
ch contributors "content/browser/" --format json

gerrit - Gerrit Code Review Operations

Work with Chromium Gerrit code reviews.

ch gerrit <command> [options]

# Aliases: gr

Commands:
  status <cl>                Get CL status and test results
  comments <cl> [options]    Get CL review comments
  diff <cl> [options]        Get CL diff/changes
  file <cl> <path> [options] Get file content from CL patchset
  bots <cl> [options]        Get try-bot status for CL
  bot-errors <cl> [options]  Get detailed error messages with stack traces from failed try-bots
  list [options]             List Gerrit CLs (requires authentication)

Examples:

# Get CL status
ch gerrit status 6624568

# Get review comments
ch gerrit comments 6624568 --format json

# Get diff for specific file
ch gerrit diff 6624568 --file "base/logging.cc"

# Get file content from patchset
ch gerrit file 6624568 "base/logging.cc" --patchset 3

# Get try-bot status
ch gerrit bots 6624568
ch gerrit bots 6624568 --failed-only

# Get detailed bot errors with stack traces
ch gerrit bot-errors 6624568
ch gerrit bot-errors 6624568 --bot linux  # Filter to linux bots only
ch gerrit bot-errors 6624568 --bot linux-rel  # Specific bot
ch gerrit bot-errors 6624568 --all-bots  # Include all bots, not just failed

# List Gerrit CLs (requires authentication cookie)
ch gerrit list --auth-cookie "SID=...; __Secure-1PSID=..." --limit 10
ch gerrit list --auth-cookie "..." --query "status:open owner:me"
ch gerrit list --auth-cookie "..." --query "change:1234 OR change:5678"

pdfium - PDFium Gerrit Operations

Work with PDFium Gerrit code reviews.

ch pdfium <command> [options]

# Aliases: pdf

Commands:
  status <cl>                Get PDFium CL status and test results
  comments <cl> [options]    Get PDFium CL review comments
  diff <cl> [options]        Get PDFium CL diff/changes
  file <cl> <path> [options] Get file content from PDFium CL patchset
  bots <cl> [options]        Get try-bot status for PDFium CL
  list [options]             List PDFium Gerrit CLs (requires authentication)

Examples:

# Get PDFium CL status
ch pdfium status 130850

# Get PDFium review comments
ch pdfium comments 130850 --format json

# View PDFium file changes
ch pdfium diff 130850 --file "fpdfsdk/fpdf_view.cpp"

# Get PDFium file content
ch pdfium file 130850 "fpdfsdk/fpdf_view.cpp" --patchset 9

# Get PDFium try-bot status
ch pdfium bots 130850
ch pdfium bots 130850 --failed-only

# List PDFium Gerrit CLs (requires authentication cookie)
ch pdfium list --auth-cookie "SID=...; __Secure-1PSID=..." --limit 10
ch pdfium list --auth-cookie "..." --query "status:open owner:me"
ch pdfium list --auth-cookie "..." --query "change:12345 OR change:67890"

issues - Chromium Issue Operations

Search and view Chromium issues and bugs with comprehensive metadata.

ch issues <command> [options]

# Aliases: bugs

Commands:
  get <id>                   Get specific issue details
  search <query> [options]   Search for issues with filters

Search Results Include:

• Issue ID and title
• Issue type (Bug, Feature, Task, etc.)
• Assignee information
• Current status
• 7-day view counts
• Last modified date
• CL (Code Review) availability

Search Query Syntax:

# Use Chromium issue tracker query syntax:
hotlistid:<id>              # Filter by hotlist
status:<value>              # Filter by status (open, fixed, etc.)
owner:<email>               # Filter by owner
assignee:<email>            # Filter by assignee
type:<value>                # Filter by type (Bug, Feature, etc.)
priority:<P0-P4>            # Filter by priority
component:<name>            # Filter by component

Examples:

# Search for open bugs in a hotlist
ch issues search "hotlistid:5483263 status:open" --limit 50

# Search by multiple criteria
ch issues search "status:open owner:me" --format json

# Search with pagination
ch issues search "type:Bug priority:P1" --limit 25 --start 0

# Get specific issue details
ch issues get 1493929

issue - Get Chromium Issue Details

Get information about Chromium bugs and feature requests.

ch issue <id>

# Aliases: bug

Examples:

# Get issue details
ch issue 422768753

# Using full URL
ch issue "https://issues.chromium.org/issues/422768753"

🎨 Output Formats

Control output format with the global --format option:

Plain Text (Default)

ch search "LOG(INFO)" --format plain

Human-readable format with colors and formatting.

JSON

ch search "LOG(INFO)" --format json

Structured JSON for programmatic processing and AI systems.

Table

ch search "LOG(INFO)" --format table

Tabular format for easy reading and comparison.

🔐 Authentication

Gerrit Authentication

The gerrit list and pdfium list commands require authentication. We've made this super easy!

Method 1: Interactive Manual Setup (Recommended) 🚀

# One-time setup - guides you through cookie extraction
ch auth manual

# Check if you're authenticated
ch auth status

# Now you can use gerrit commands without any cookies!
ch gerrit list
ch pdfium list

Method 2: Automated Browser Login

# Alternative method - opens browser automatically
ch auth login
# Note: May be blocked by Google security checks

Method 3: Direct Cookie Parameter

If you prefer to manually provide cookies each time:

# Get help on extracting cookies
ch auth help

# Use with --auth-cookie parameter
ch gerrit list --auth-cookie "SID=...; __Secure-1PSID=...; __Secure-3PSID=..."

# Or save to ~/.gerrit-cookie file
echo "SID=...; __Secure-1PSID=...; __Secure-3PSID=..." > ~/.gerrit-cookie
ch gerrit list  # Will use saved cookies automatically

Authentication Commands

• ch auth login - Sign in via browser (saves cookies)
• ch auth status - Check if authenticated
• ch auth logout - Clear saved authentication
• ch auth help - Show detailed cookie extraction help

⚙️ Configuration

Environment Variables

# Set custom API key
export CHROMIUM_SEARCH_API_KEY=your_api_key_here

# Disable colors
export NO_COLOR=1

Config File

Create ~/.ch.json or .ch.json in your project:

{
  "apiKey": "your_api_key_here",
  "outputFormat": "json",
  "defaultLimit": 50
}

Configuration Commands

# Show current configuration
ch config --show

# Set API key (future feature)
ch config --set-api-key "your_key"

🤖 AI and Shell Script Integration

Perfect for AI systems and shell scripts:

#!/bin/bash

# Search for security-related code
RESULTS=$(ch search "crypto" --language cpp --format json --limit 10)

# Process results with jq
echo "$RESULTS" | jq '.[] | select(.file | contains("security")) | .url'

# Find all Browser class definitions
ch symbol "Browser" --format json | jq '.classResults[].url'

# Get file content for analysis
ch file "base/security/security_context.h" --format json | \
  jq -r '.content' | head -20

📋 Use Cases

For Developers

• Code Discovery: Find examples of how to use specific APIs
• Architecture Understanding: Explore class hierarchies and dependencies
• Code Review: Understand context around changes
• Bug Investigation: Search for related code patterns

For AI Systems

• Code Analysis: Extract structured information about Chromium codebase
• Documentation Generation: Gather examples and usage patterns
• Refactoring Assistance: Find all usages of symbols before changes
• Learning: Understand large codebase patterns and conventions

For Automation

• CI/CD Integration: Validate code patterns and standards
• Monitoring: Track usage of deprecated APIs
• Documentation: Generate up-to-date code examples
• Security Audits: Search for security-sensitive code patterns

🔍 Advanced Search Techniques

Code Search Syntax

The tool supports Google CodeSearch syntax:

# Search specific function definitions
ch search "function:CreateWindow"

# Search class definitions
ch search "class:Browser"

# Search symbols (excludes comments/strings)
ch search "symbol:WebContents"

# Case-sensitive search
ch search "case:yes LOG"

# Language and file filters
ch search "lang:cpp file:*.h virtual"

Complex Queries

# Find all virtual destructors in headers
ch search "virtual ~" --file-pattern "*.h" --language cpp

# Search for TODO comments in browser code
ch search "TODO" --type comment --file-pattern "chrome/browser/*"

# Find memory management patterns
ch search "std::unique_ptr" --language cpp --exclude-comments

🚀 Performance Tips

• Use --limit to control result count for faster responses
• Use --file-pattern to narrow search scope
• Use --language to filter by programming language
• Use --format json for faster parsing in scripts
• Cache results in shell scripts to avoid repeated API calls

🛠️ Development

# Clone and setup
git clone https://github.com/hjanuschka/ch-cli.git
cd ch-cli
npm install

# Development with watch mode
npm run dev

# Build
npm run build

# Test locally
node dist/index.js --help

🤝 Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/new-feature
3. Make your changes and add tests
4. Commit: git commit -am 'Add new feature'
5. Push: git push origin feature/new-feature
6. Create a Pull Request

📄 License

MIT License - see LICENSE file for details.

🔗 Related

• Chromium Code Search - Official web interface
• Chromium Development - Developer documentation
• Gerrit Code Review - Code review system

📞 Support

• GitHub Issues - Bug reports and feature requests
• GitHub Discussions - Questions and community

Made with ❤️ for the Chromium developer community