Churn

One command. Every doc your project needs. Every question your interview demands.

---

Install

pip install churn-cli

For PDF export support (--only pdf):

pip install "churn-cli[pdf]"

For Groq or OpenAI as your provider:

pip install "churn-cli[groq]"
pip install "churn-cli[openai]"

Requires Python 3.8+. By default Churn uses Gemini — get a free key at aistudio.google.com.

---

Usage

Churn has two main commands: interview for interview prep, and docs for documentation generation.

churn interview /path/to/your/project
churn docs /path/to/your/project

First run pe active provider ka API key maangega — ek baar enter karo, save ho jaata hai globally (~/.churn/config.json).

---

churn interview

Generates level-wise interview Q&A from your codebase.

churn interview /path/to/project
churn interview /path/to/project --level senior          # skip interactive prompt
churn interview /path/to/project --questions 15           # custom question count (default: 10)
churn interview /path/to/project --output report.md        # custom output file
churn interview /path/to/project --format json             # json output instead of markdown
churn interview /path/to/project --ignore tests/ --ignore migrations/   # skip folders

Options

-q, --questions INTEGER           Number of questions  [default: 10]
-l, --level [fresher|mid|senior]  Skip prompt, set level directly
-o, --output TEXT                 Output file  [default: churn-output.md]
-f, --format [md|json]            Output format  [default: md]
-i, --ignore TEXT                 Extra folders to ignore (repeatable)

Output Example

# Churn — MID Level

**Q1: In `matchingService.js`, what are the three criteria for a perfect match?**

The `findMatches` function checks: same campus, userProfile's wantedElectives includes
student's currentElective, and student's wantedElectives includes userProfile's currentElective.

---

---

churn docs

Generates complete project documentation from your codebase.

churn docs /path/to/project
churn docs /path/to/project --only readme,prd          # generate only specific docs
churn docs /path/to/project --only readme,prd,arch,pdf # include a combined PDF report
churn docs /path/to/project --output my-docs/           # custom output folder
churn docs /path/to/project --ignore tests/             # skip folders
churn docs /path/to/project --force                     # regenerate even if code is unchanged

Options

--only TEXT        Comma separated: readme, prd, arch, pdf  [default: readme,prd,arch]
-o, --output TEXT  Output folder  [default: churn-docs/]
-i, --ignore TEXT  Extra folders to ignore (repeatable)
--force            Regenerate every doc even if the code hasn't changed since the last run

Output

churn-docs/
├── README.md       — what it does, setup, usage, tech stack
├── PRD.md          — problem, features, roadmap inferred from code
├── ARCHITECTURE.md — folder structure, data flow, key files
└── REPORT.pdf       — all three combined, shareable (only with --only ...,pdf)

Each doc is generated strictly from what's in the code — README, PRD, and ARCHITECTURE don't invent features, flags, or files that aren't actually there. The PRD's roadmap section is inferred from real TODOs and unfinished code paths, not guesses.

Smart caching: Churn hashes your compressed code on every run. If nothing's changed since the last docs run, unchanged doc types are skipped instead of re-generated — saving API calls. Use --force to regenerate anyway. If a doc already exists, Churn updates it instead of rewriting from scratch, preserving wording that's still accurate.

PDF export uses xhtml2pdf (pure Python) — no native GTK/Cairo dependencies, so it works out of the box on Windows, macOS, and Linux. Requires pip install "churn-cli[pdf]".

---

churn auth

Manage API key authentication per provider.

churn auth login                       # set/update key for the active provider
churn auth login --provider groq       # set/update key for a specific provider
churn auth logout                      # remove key for the active provider
churn auth logout --provider openai    # remove key for a specific provider
churn auth status                      # show active provider + masked key status for all providers

---

churn config

View and edit local Churn configuration.

churn config show                  # print full config (API keys masked)
churn config set theme dark        # set a non-secret config value
churn config provider              # interactively switch active provider
churn config provider groq         # switch active provider directly
churn config open                  # print (and try to open) the config file location

api_key, providers, and active_provider can't be changed via config set — use churn auth login and churn config provider for those.

---

churn update

Check PyPI for a newer version and self-update.

churn update
churn --update   # equivalent global flag

---

Global Flags

churn --version   # show version
churn --update    # check for and install the latest version from PyPI
churn --help      # show all commands and options

---

What It Does

Churn scans a local project directory, identifies the most frequently edited files using git log, compresses the code, and sends it to your active AI provider (Gemini by default, Groq or OpenAI as alternatives).

• churn interview returns interview questions with detailed answers, saved as markdown or JSON.
• churn docs returns a full documentation set (README, PRD, ARCHITECTURE, and an optional combined PDF report).

---

Providers

Churn supports multiple AI providers — switch anytime with churn config provider:

Provider	Model	Notes
Gemini (default)	gemini-flash-latest	Auto-falls back to gemini-2.5-flash on 503
Groq	llama-3.3-70b-versatile	Requires pip install "churn-cli[groq]"
OpenAI	gpt-4o-mini	Requires pip install "churn-cli[openai]"

Keys can also be set via environment variables instead of churn auth login: GEMINI_API_KEY, GROQ_API_KEY, OPENAI_API_KEY — these take precedence over stored keys.

---

Files Scanned

Included: .py .js .ts .tsx .jsx .java .go .cpp .env.example

Ignored: node_modules/ .git/ dist/ build/ __pycache__/ .next/ venv/ churn-env/ .env

User can pass additional folders to ignore via -i/--ignore (repeatable).

---

Privacy

• No code is stored at any point
• Everything runs locally — no backend server
• Code is sent to your active provider's API for processing only
• .env files are never scanned — hardcoded in the ignore list
• API keys are stored locally at ~/.churn/config.json (file permissions locked to owner-only where supported), never transmitted anywhere else

---

Tech Stack

• Python 3.8+
• click — CLI framework
• questionary — interactive prompts
• python-dotenv — environment variables
• google-genai — Gemini API SDK
• groq — Groq API SDK (optional)
• openai — OpenAI API SDK (optional)
• markdown + xhtml2pdf — PDF report export (optional)

---

Local Development

git clone https://github.com/DhawalShankar/project-churn
cd project-churn
python -m venv venv
venv\Scripts\activate        # Windows
source venv/bin/activate     # Mac/Linux
pip install -e ".[pdf]"
churn interview /path/to/project
churn docs /path/to/project

---

Roadmap

• PyPI publish — pip install churn-cli
• Custom question count — --questions
• Custom output path — --output
• JSON export — --format json
• Skip folders — --ignore
• churn docs — README, PRD, ARCHITECTURE generation
• PDF export — REPORT.pdf
• Multi-provider support (Groq, OpenAI) — churn config provider
• Self-update — churn update / --update
• Doc caching — skip unchanged docs, update instead of rewrite
• GitHub public repo URL support
• VS Code Extension
• Custom focus flag — --focus security

---

License

Personal project. All rights reserved. © 2026 dhawalshankar