Recommendations

A CLI tool to fetch and display GitHub recommendations from a public gist. This package allows you to easily view recommendations (both given and received) stored in a user's GitHub gist.

Installation

You can use this package directly with npx without installing it globally:

npx pub-recs <github-username> [filter] [--json]

Or install it globally:

npm install -g pub-recs
pub-recs <github-username> [filter] [--json]

Usage

Basic Usage

# Show all recommendations for a user
npx pub-recs dalevross

# Show only given recommendations
npx pub-recs dalevross g

# Show only received recommendations
npx pub-recs dalevross r

Parameters

• <github-username>: Required. The GitHub username to fetch recommendations for
• [filter]: Optional. Filter recommendations:
  • g - Show only given recommendations
  • r - Show only received recommendations
  • No filter - Show both given and received recommendations
• [--json]: Optional. Output raw JSON format instead of formatted display

Gist Format

The tool looks for a public gist named recommendations.js in the specified user's GitHub profile. The gist should contain valid JSON with the following structure:

{
  "given": [
    {
      "name": "John Doe",
      "title": "Senior Developer",
      "company": "Tech Corp",
      "recommendation": "Dale is an exceptional developer...",
      "date": "2024-01-15",
      "url": "https://linkedin.com/in/johndoe"
    }
  ],
  "received": [
    {
      "name": "Jane Smith",
      "title": "Product Manager",
      "company": "Innovation Inc",
      "recommendation": "I highly recommend Dale...",
      "date": "2024-02-20",
      "url": "https://linkedin.com/in/janesmith"
    }
  ]
}

Required Fields

• name: Name of the person giving/receiving the recommendation
• recommendation: The recommendation text

Optional Fields

• title: Job title of the person
• company: Company/organization
• date: Date of the recommendation (YYYY-MM-DD format recommended)
• url: URL where the recommendation can be found (LinkedIn, etc.)

Output Format

By default, the tool displays recommendations in a beautiful, color-coded format with:

• 🎨 Colored headers with background highlighting for "GIVEN" and "RECEIVED" sections
• 📋 Structured display showing name, title, company, and recommendation text
• 📅 Formatted dates in human-readable format
• 🔗 Clickable URLs for easy navigation
• 📊 Summary statistics showing total count

Use the --json flag to get raw JSON output for programmatic use.

Error Handling

The tool will display helpful error messages for common issues:

• User not found on GitHub
• No recommendations.js gist found
• Invalid JSON format in the gist
• Network connectivity issues

Examples

# Get all recommendations for dalevross (formatted output)
npx pub-recs dalevross

# Get only recommendations given by dalevross
npx pub-recs dalevross g

# Get only recommendations received by dalevross
npx pub-recs dalevross r

# Get all recommendations in JSON format
npx pub-recs dalevross --json

# Get only given recommendations in JSON format
npx pub-recs dalevross g --json

Sources

Original inspiration and data sources:

https://www.linkedin.com/in/dalevross/

https://www.f6s.com/dalevross