Novash
Novash is an open-source, command-line SEO checker for websites. Point it at a URL and it downloads the page, audits the core on-page SEO elements, scores the result out of 100, and tells you exactly what to fix — all from your terminal.
Features
- 🔍 Automated page crawling — fetches and parses any public webpage, with built-in handling for timeouts, bad URLs, and connection errors.
- 📄 Title check — detects whether the page has a non-empty
<title>tag. - 📝 Meta description check — detects a non-empty
<meta name="description">tag. - 📌 H1 check — finds meaningful
<h1>tags, automatically ignoring ones that are hidden (display:none,aria-hidden, etc.), empty, or too short to be a real heading. - 🖼️ Image alt-text audit — counts every
<img>tag and reports how many are missingalttext. - 📊 SEO scoring — a 100-point score with clear, transparent deductions (see Scoring below).
- 💡 Actionable suggestions — plain-language fixes generated from whatever the audit finds wrong.
- 📤 JSON export — save the full report to a file for use in other tools, dashboards, or CI pipelines.
- 🎨 Colorful terminal output — powered by Rich, with green/yellow/red color-coding so you can scan a report at a glance.
Installation
Novash requires Python 3.8+.
Clone the repository and install it locally:
git clone https://github.com/<your-username>/novash.git
cd novash
pip install .
This installs Novash's dependencies (requests, beautifulsoup4, rich, typer) and registers the novash command on your PATH.
For development (editable install, so code changes take effect immediately):
pip install -e .
Usage Examples
Scan a website and print the report to your terminal:
novash scan https://example.com
Scan a website and also save the full report as JSON:
novash scan https://example.com --export report.json
View help for any command:
novash --help
novash scan --help
CLI Commands
| Command | Description |
|---|---|
novash scan <url> |
Crawl a URL, run all SEO checks, calculate the score, and print the report. |
novash scan <url> --export <file> |
Same as above, and also save the full report as a pretty-printed JSON file. |
novash --help |
Show general help and available commands. |
novash scan --help |
Show detailed help for the scan command. |
Options
| Option | Description |
|---|---|
--export <filename> |
Save the report as JSON, e.g. --export report.json. Optional. |
Example Output
╭───────────────────╮
│ NOVASH SEO REPORT │
╰───────────────────╯
🌐 Website: https://example.com
📄 Title
✓ Title found:
Example Domain
📝 Meta Description
✗ Meta description missing
📌 H1 Tags
✓ H1 tags found:
- Example Domain
🖼️ Images
✓ Total images: 11
✓ Images with alt text: 1
✗ Images without alt text: 10
╭──────────────────────╮
│ ⚠️ SEO Score: 82/100 │
╰──────────────────────╯
💡 Suggestions
- Add a meta description.
- Add alt text to 10 images.
If every check passes, the Suggestions section shows a single line instead:
💡 Suggestions
✅ No SEO issues found.
Scoring
Novash starts every page at 100 points and deducts:
- 15 points if the title is missing
- 15 points if the meta description is missing
- 15 points if no meaningful H1 tag is found
- Up to 20 points, proportional to the percentage of images missing alt text:
penalty = (images_without_alt / total_images) * 20
The score never drops below 0, and is color-coded in the terminal:
| Score | Color |
|---|---|
| 90–100 | 🟢 Green |
| 70–89 | 🟡 Yellow |
| 0–69 | 🔴 Red |
Roadmap
Planned improvements for future versions:
- Multi-page / full-site crawling (follow internal links)
- Additional checks: canonical tags, robots meta, Open Graph tags, heading hierarchy (H1–H6), broken links, page load time
- HTML and PDF report export, alongside JSON
- Configurable scoring weights via a config file
- Batch scanning of multiple URLs from a file
- CI/CD integration (fail a build if the score drops below a threshold)
- Publish to PyPI for
pip install novash
Have an idea? Open an issue — see Contributing below.
Contributing
Contributions are welcome! To get started:
- Fork the repository and clone your fork.
- Create a new branch for your change:
git checkout -b feature/your-feature-name
- Install in editable mode so your changes are picked up immediately:
pip install -e .
- Make your changes, and keep functions small, documented, and covered by a quick manual test (each module includes a
if __name__ == "__main__":block you can run directly, e.g.python checks.py). - Commit and push your branch, then open a pull request describing what you changed and why.
Please keep pull requests focused — one feature or fix per PR makes review much easier. Bug reports and feature requests are just as welcome as code; feel free to open an issue.
License
This project is open-source. Add your preferred license (e.g. MIT) in a LICENSE file before publishing.
Metadata
Release files for novash 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| novash-0.1.0.tar.gz | 63.2 kB | Without provenance | Details for novash-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| novash-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for novash-0.1.0-py3-none-any.whl |
Total release size: 132.1 kB
Release files / novash-0.1.0.tar.gz
| Download URL | novash-0.1.0.tar.gz |
|---|---|
| Size | 63.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
5f07cfe597434744f3d273c6531c677a9a9c775f2bf8ed9b41908f5da56bb6fb
|
|
BLAKE2b-256 checksum How to use checksums |
9cf52d29ee36394da0c2a4b300355b587361b1a7c7534f5fbfe0663e2baa4401
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.6
|
Release files / novash-0.1.0-py3-none-any.whl
| Download URL | novash-0.1.0-py3-none-any.whl |
|---|---|
| Size | 68.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
63a5cabcd4a468b5049da7aa5965b1847650723ed98ca780260f26f7cf008528
|
|
BLAKE2b-256 checksum How to use checksums |
ef05162a4b1b73657acbbb3481cc9a8c53931698e35e00cfdd9ee5db870ea702
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.6
|
Security for novash 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.