Documentation

Getting Started

Basic Usage

To start gemtracker, navigate to your Ruby project directory and run:

gemtracker will automatically read your Gemfile.lock and display your project's gems.

Requirements

• • A valid Gemfile.lock in your project
• • A POSIX-compatible terminal (macOS, Linux, WSL on Windows)
• • No additional configuration needed

Keyboard Shortcuts

Use these keyboard shortcuts to navigate gemtracker efficiently:

Screens Reference

1. Gem List

The default screen showing all gems in your project. Each entry displays:

• • Name — The gem's name
• • Installed — Currently installed version
• • Latest — Most recent available version
• • Environment — prod, dev, or test
• • CVE Status — Red flag if vulnerabilities found

2. Search

Press / to enter search mode. Use fuzzy matching to quickly find any gem in your project. Results update as you type.

3. CVE Detection

Shows known vulnerabilities in your project's gems. Each CVE displays:

• • CVE ID — Unique identifier
• • Severity — Low, medium, high, or critical
• • Affected Gem — Which gem has the vulnerability
• • Environment — Whether it affects production code

4. Dependency Tree

Interactive view of gem dependencies. Select a gem to see:

• • Forward Dependencies — What this gem requires
• • Reverse Dependencies — What depends on this gem

Export Reports

Generate reports for CI/CD pipelines and compliance in multiple formats:

Text Format

Human-readable report. Perfect for code review, team communication, and build logs.

CSV Format

Spreadsheet-compatible format for compliance managers and audit trails.

JSON Format

Machine-readable output for CI/CD pipelines. Includes full gem details and vulnerability info.

CI/CD Examples

Gem Health Status

Each gem shows a colored health indicator fetched from RubyGems and GitHub APIs.

GitHub Token Setup

For projects with 100+ gems, use a fine-grained personal access token for 5,000 API requests/hour instead of the default 60/hour.

Create Token

GitHub → Settings → Developer settings → Personal access tokens → Fine-grained tokens → Generate new token

Use Token

Claude Code AI Skill

Use /gem-check for interactive gem analysis:

Security-first analysis, smart prioritization, guided upgrade paths, and interactive Q&A.

Performance & Caching

Analysis results cached in ~/.cache/gemtracker/ — instant load on re-run if Gemfile.lock unchanged.

Health data cached for 12 days. Clear manually: rm ~/.cache/gemtracker/Gemfile.lock_*.json

Tips & Tricks

Filtering by Environment

Use the filter feature to show only production, development, or test dependencies. Press f to toggle filters.

Quick Gem Copy

Press c to copy the highlighted gem name to your clipboard—useful for looking up documentation or running commands.

Dependency Analysis

Use the dependency tree to understand bloat in your Gemfile. Large dependency trees can slow down bundle installation. gemtracker helps you visualize and understand these relationships.

Security Audits

Check the CVE screen regularly (especially before deploying to production). Prioritize critical vulnerabilities in production dependencies.

Reporting Issues

Found a bug or have a feature request? We'd love to hear from you! Please open an issue on GitHub with:

• • A clear description of the issue or feature
• • Your operating system and gemtracker version
• • Steps to reproduce (for bugs)
• • Expected vs. actual behavior