readme-forge-cli

Intelligent README.md generator — analyzes projects, detects tech stacks, and forges professional documentation automatically.

---

Features

• Auto-Detection — Detects language, frameworks, project type, license automatically
• 20+ Languages — Python, JavaScript, TypeScript, Go, Rust, Java, Ruby, C#, and more
• 50+ Frameworks — Django, React, FastAPI, Next.js, Spring Boot, Rails, and more
• Smart Badges — Auto-generates shields.io badges for language, version, license, CI, PyPI/npm
• Tech Stack Table — Categorized framework display with language versions
• Directory Tree — Optional project structure visualization
• Template Support — Built-in templates (minimal, detailed) or custom Jinja2 templates
• Configurable Sections — Toggle badges, TOC, features, installation, usage, contributing
• Multiple Styles — Banner, simple, or minimal header styles
• Rich Terminal UI — Beautiful project analysis output with Rich

---

Installation

pip install readme-forge-cli

---

Quick Start

# Generate README for current project
readme-forge generate .

# Preview without writing
readme-forge generate . --preview

# Analyze project without generating
readme-forge analyze .

# Quick detection (great for scripting)
readme-forge detect . --format json

---

Commands

readme-forge generate

Generate a README.md for your project.

readme-forge generate [PATH] [OPTIONS]

Options:
  -o, --output TEXT          Output file path (default: README.md)
  --style [banner|simple|minimal]  Header style
  --badge-style [flat|flat-square|for-the-badge|plastic]  Badge style
  --no-badges               Skip badges
  --no-toc                  Skip table of contents
  --no-features             Skip features section
  --no-install              Skip installation section
  --no-usage                Skip usage section
  --no-contributing         Skip contributing section
  --no-license              Skip license section
  --tree                    Include project structure tree
  --tree-depth INT          Tree depth (default: 3)
  --api                     Include API reference section
  --emoji / --no-emoji      Use emoji in headers (default: on)
  --preview                 Preview without writing file
  -f, --force               Overwrite existing README
  -q, --quiet               Minimal output

Example:

$ readme-forge generate ./my-project --force

🔍 Analyzing project at my-project...

╭─── 📋 Project Analysis ─────────────────────────────╮
│  Name             my-awesome-tool                    │
│  Description      An awesome CLI tool                │
│  Version          2.1.0                              │
│  Type             CLI Tool                           │
│  Language         Python                             │
│  Frameworks       Click, pytest, Hatch               │
│  License          MIT                                │
│  Author           Jane Dev                           │
│  Structure        ✅ Tests  ✅ CI/CD  ✅ Docker      │
╰──────────────────────────────────────────────────────╯

╭─── ✅ README Generated ─────────────────────────────╮
│  Output           README.md                          │
│  Sections         8                                  │
│  Badge Style      flat                               │
│  Header Style     banner                             │
╰──────────────────────────────────────────────────────╯

readme-forge analyze

Analyze a project and display detected information.

readme-forge analyze [PATH]

readme-forge tree

Display the project directory tree.

readme-forge tree [PATH] [--depth INT]

readme-forge stats

Show project file statistics.

readme-forge stats [PATH]

readme-forge detect

Quick detection for scripting and CI/CD.

readme-forge detect [PATH] [--format text|json]

JSON output:

{
  "name": "my-project",
  "language": "Python",
  "languages": ["Python", "TypeScript"],
  "frameworks": ["FastAPI", "Docker", "GitHub Actions"],
  "project_type": "API Server",
  "license": "MIT",
  "version": "1.0.0"
}

readme-forge templates

List available README templates.

readme-forge from-template

Generate README from a built-in or custom Jinja2 template.

readme-forge from-template [PATH] -t TEMPLATE [-o OUTPUT] [-f]

---

Supported Languages

Language	Extensions
Python	.py
JavaScript	.js, .jsx
TypeScript	.ts, .tsx
Go	.go
Rust	.rs
Java	.java
C#	.cs
C/C++	.c, .cpp, .cc
Ruby	.rb
PHP	.php
Swift	.swift
Kotlin	.kt, .kts
Dart	.dart
Shell	.sh, .bash
Scala	.scala
Elixir	.ex, .exs
Haskell	.hs

---

Detected Frameworks

Python: Django, Flask, FastAPI, Click, Typer, pytest, Hatch, Poetry, setuptools, Sphinx, Celery, SQLAlchemy, Pydantic

JavaScript/TypeScript: React, Next.js, Vue.js, Angular, Express, NestJS, Vite, Webpack, Jest, Mocha, ESLint, Prettier, Tailwind CSS, Storybook

Go: Gin, Echo, Fiber, Cobra

Rust: Actix, Rocket, Tokio, clap, serde

Java: Spring Boot, Maven, Gradle

Ruby: Rails, Sinatra, RSpec

DevOps: Docker, Kubernetes, Terraform, GitHub Actions, GitLab CI

---

Custom Templates

Create a Jinja2 template file:

# {{ info.name }}

{{ info.description }}

**Language:** {{ info.primary_language.value }}
**License:** {{ info.license.value }}

{% for fw in info.frameworks %}
- {{ fw.value }}
{% endfor %}

Use it:

readme-forge from-template . -t my-template.j2 -o README.md

---

Development

git clone https://github.com/SanjaySundarMurthy/readme-forge.git
cd readme-forge
pip install -e ".[dev]"
pytest tests/ -v

---

License

MIT License — see LICENSE for details.