readme-score-cli

Score any README.md for completeness and quality. Get instant feedback on what's missing and how to improve your project documentation.

A CLI tool that analyzes README files and scores them across 10 key sections, giving you an overall grade (A+ to F) with actionable suggestions for improvement.

Table of Contents

• Installation
• Usage
• Scoring Criteria
• Options
• CI Integration
• Contributing
• License

Installation

npm install -g readme-score-cli

Or use with npx:

npx readme-score-cli .

Usage

Score a local README

# Score README in current directory
readme-score .

# Score a specific file
readme-score ./path/to/README.md

Score a GitHub repo

# Using owner/repo format
readme-score facebook/react

# Using full URL
readme-score https://github.com/expressjs/express

JSON output (for CI)

readme-score . --json

Quiet mode (just the number)

readme-score . --quiet
# Output: 73

Scoring Criteria

Each section is scored 0-10 points (100 total):

| Section | What's Checked | |---------|---------------| | Title | Clear H1 heading, proper length, description below | | Description | Word count, clarity, presence of key info | | Badges | npm version, CI status, license, coverage, downloads | | Installation | Code blocks, package manager commands, context | | Usage Examples | Multiple code examples, detailed explanations | | API Documentation | Code samples, parameter tables, completeness | | Contributing Guide | PR workflow, setup commands, code of conduct | | License | License type specified, LICENSE file linked | | Screenshots/GIFs | Visual demos, multiple images, animated demos | | Table of Contents | Navigation links, section coverage |

Options

| Flag | Description | |------|-------------| | -j, --json | Output results as JSON | | -q, --quiet | Only output the score number (0-100) | | --no-suggestions | Hide improvement suggestions | | -V, --version | Show version number | | -h, --help | Show help |

CI Integration

Use readme-score in your CI pipeline to enforce documentation quality:

# GitHub Actions
- name: Check README quality
  run: |
    npx readme-score-cli . --quiet
    # Exits with code 1 if score < 50%

The CLI exits with code 1 if the score is below 50%, making it easy to use as a quality gate.

Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository
2. Create a feature branch: git checkout -b feature/my-feature
3. Install dependencies: npm install
4. Make your changes in src/
5. Build: npm run build
6. Test locally: node dist/index.js .
7. Submit a pull request

License

MIT License - see LICENSE for details.