<div align="center">
</div>
# 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
```bash
# 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.):
```bash
# 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:
```bash
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:
```bash
npm install -g chromium-helper
# Now available as 'chromium-helper' and 'ch'
```
### Option 3: From Source
```bash
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.
```bash
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:**
```bash
# 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.
```bash
ch symbol <symbol> [options]
# Aliases: sym
Options:
-f, --file <path> File path context for symbol resolution
```
**Examples:**
```bash
# 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.
```bash
ch file <path> [options]
# Aliases: f
Options:
-s, --start <line> Starting line number
-e, --end <line> Ending line number
```
**Examples:**
```bash
# 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.
```bash
ch owners <path>
# Aliases: own
```
**Examples:**
```bash
# 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.
```bash
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:**
```bash
# 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.
```bash
ch blame <file> [options]
Options:
-l, --line <number> Show blame for specific line number
```
**Examples:**
```bash
# 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.
```bash
ch history <file> [options]
# Aliases: log
Options:
-l, --limit <number> Maximum number of commits to show (default: 20)
```
**Examples:**
```bash
# 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.
```bash
ch contributors <path> [options]
Options:
-l, --limit <number> Maximum number of commits to analyze (default: 50)
```
**Examples:**
```bash
# 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.
```bash
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:**
```bash
# 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.
```bash
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:**
```bash
# 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.
```bash
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:**
```bash
# 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:**
```bash
# 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.
```bash
ch issue <id>
# Aliases: bug
```
**Examples:**
```bash
# 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)
```bash
ch search "LOG(INFO)" --format plain
```
Human-readable format with colors and formatting.
### JSON
```bash
ch search "LOG(INFO)" --format json
```
Structured JSON for programmatic processing and AI systems.
### Table
```bash
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) 🚀
```bash
# 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
```bash
# 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:
```bash
# 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
```bash
# 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:
```json
{
"apiKey": "your_api_key_here",
"outputFormat": "json",
"defaultLimit": 50
}
```
### Configuration Commands
```bash
# 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:
```bash
#!/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:
```bash
# 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
```bash
# 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
```bash
# 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](LICENSE) file for details.
## 🔗 Related
- [Chromium Code Search](https://source.chromium.org) - Official web interface
- [Chromium Development](https://www.chromium.org/developers/) - Developer documentation
- [Gerrit Code Review](https://chromium-review.googlesource.com/) - Code review system
## 📞 Support
- [GitHub Issues](https://github.com/hjanuschka/ch-cli/issues) - Bug reports and feature requests
- [GitHub Discussions](https://github.com/hjanuschka/ch-cli/discussions) - Questions and community
---
**Made with ❤️ for the Chromium developer community**
