mkaireadme is a cross-platform Python CLI that leverages the power of generative AI to create and maintain high-quality README.md files for any project. Stop writing documentation from scratch—let your code speak for itself.

---

✨ Visual Demo

# Navigate to your project directory
$ cd my-awesome-project

# Run the generation command
$ mkaireadme gen --model google/gemini-flash-1.5

🤖 Analyzing project context...
🧠 Contacting google/gemini-flash-1.5 via OpenRouter...
📝 Writing README.md...

✅ Successfully created README.md!

---

📋 Table of Contents

• Features
• Tech Stack
• Installation
• Getting Started
• Command Reference
• Configuration
• Contributing
• License

✨ Key Features

• 🧠 AI-Powered Generation: Uses state-of-the-art language models (via OpenRouter) to analyze your project and generate a tailored, comprehensive README.
• 🌐 Cross-Platform Compatibility: Works seamlessly on Windows, macOS, and Linux.
• 🔄 Smart Updates: Intelligently updates existing READMEs by injecting new content between markers, preserving your custom sections.
• 🛠️ Deep Customization: Guide the AI with a simple .mkaireadme.yml file to specify project goals and custom instructions.
• 📜 License Management: Includes built-in license generation (from a list of common templates) and automatic README integration.
• 🤖 Flexible Model Selection: Browse and choose from dozens of AI models to find the perfect fit for your needs and budget.
• 💰 Content Budgeting: Smartly analyzes large projects by prioritizing key files, ensuring you stay within the AI model's token limits.

🛠️ Tech Stack

• Python 3.9+
• Typer: Modern CLI framework for a great user experience.
• Rich: Beautiful terminal styling, tables, and progress indicators.
• OpenAI: Official library for robust AI integration via OpenRouter.
• python-dotenv: Secure environment variable management.
• pathspec: Gitignore-style file exclusion for precise context analysis.
• PyYAML: Simple and clean configuration file handling.

🚀 Installation

Install mkaireadme directly from PyPI with a single command:

pip install mkaireadme

🏁 Getting Started

Get your first AI-generated README in just 3 simple steps.

Step 1: Set Your API Key

The tool requires an API key from OpenRouter to function. Set it once, and it will be saved locally for all future use.

mkaireadme set-key YOUR_OPENROUTER_API_KEY

Step 2: Create a License (Recommended)

A LICENSE file is crucial for any serious project. mkaireadme can create one for you.

mkaireadme license

This will prompt you to choose from a list of popular open-source licenses.

Step 3: Generate Your README!

Navigate to your project's root directory and run the gen command.

# Use the recommended Gemini Flash model
mkaireadme gen --model google/gemini-flash-1.5

That's it! Your new README.md is ready. To update it later after making changes to your project, just run the same command again.

📚 Command Reference

gen

The core command to generate or update the README.

Option	Description	Example
--model	(Required) The AI model to use.	anthropic/claude-3-haiku
--force-overwrite	Replace the entire README, ignoring update markers.	--force-overwrite
--debug	Enable verbose logging for troubleshooting.	--debug

models

Browse and search for available AI models on OpenRouter.

# Show a list of recommended models
mkaireadme models

# Search for a specific model provider or name
mkaireadme models llama

license

An interactive command to generate a LICENSE file for your project.

set-key

Securely saves your OpenRouter API key for future use.

⚙️ Configuration

For more control over the AI's output, create a .mkaireadme.yml file in your project's root directory.

# .mkaireadme.yml

# Provide high-level goals to guide the AI's description
project_goals: "To build a fast, lightweight, and user-friendly CLI tool for automating documentation."

# Give specific instructions to include in the AI prompt
custom_instructions: "Emphasize the cross-platform compatibility. Mention that it is open-source and contributions are welcome."

# Exclude files or directories from the analysis to save tokens
exclude:
  - "docs/"
  - "tests/"
  - "*.log"
  - "dist/"

🤝 Contributing

Contributions are welcome! Whether it's a bug report, a feature request, or a pull request, your input is valued. Please feel free to open an issue to discuss your ideas.

📜 License

This project is licensed under the MIT License - see the LICENSE file for details.