Quickstart: run your first monitoring analysis

Written by Elena David, SEO, ORM, and AI Visibility Consultant.

Purpose

Run Reputation Monitor with its supplied fictional snapshots and verify each output. This tutorial does not require editing the data.

Prerequisites

• Complete the installation guide.
• Keep data/reviews_previous.csv and data/reviews_current.csv unchanged.
• Start in the project root with .venv active.

1. Start the dashboard

streamlit run streamlit_app.py

Open the local URL printed in the terminal. Keep Alert me about new reviews rated 2 stars or less at its default value, select CSV upload, upload data/reviews_current.csv as the current snapshot, and upload data/reviews_previous.csv as the previous snapshot.

The dashboard displays an average rating and distribution chart, three new reviews, two new alerts, and a review table. It confirms Previous reviews imported successfully — 15 reviews available for comparison. For the current sample, it reports Current reviews imported with issues — 18 reviews ready for analysis; 2 reviews rejected because required information was missing, invalid, or duplicated. Download both report formats from the page.

2. Run the equivalent CLI analysis

reputation-monitor

The CLI uses these defaults:

• previous snapshot: data/reviews_previous.csv;
• current snapshot: data/reviews_current.csv;
• output directory: reports;
• maximum rating that triggers an alert: 2; only newly detected 1-star and 2-star reviews qualify.

3. Read validation warnings

The current sample intentionally contains two invalid records. The application writes these warnings to standard error:

WARNING: current snapshot row 20: rating must be from 1 to 5
WARNING: current snapshot row 21: empty required field(s): review_id

These are command-line diagnostic findings, not a failed run. The rejected records are excluded, and imported reviews continue through the analysis. The dashboard keeps these record-level details in application logs and presents the imported and rejected counts instead.

4. Verify the terminal summary

Standard output should contain:

Reputation monitoring complete
Valid previous reviews: 15
Valid current reviews:  18
Malformed rows skipped: 2
New reviews:            3
New low-rating alerts:  2
Alerts CSV: reports/alerts.csv
HTML report: reports/monitoring_report.html

The three new valid IDs are REV-016, REV-017, and REV-018. Only REV-016 and REV-018 meet the default maximum alert rating, so the alert count is two. Moving the dashboard slider updates this maximum and its label.

5. Inspect the alert CSV

Print the file without requiring a spreadsheet application:

python -c "from pathlib import Path; print(Path('reports/alerts.csv').read_text(encoding='utf-8'))"

Verify that the file contains one header row and two alert rows. See CSV alerts for the field definitions.

6. Open the HTML report

On macOS:

open reports/monitoring_report.html

On common Linux desktop environments:

xdg-open reports/monitoring_report.html

On Windows PowerShell:

Start-Process reports/monitoring_report.html

The report should display four summary metrics, a two-row alert table, and the two validation findings. For interpretation guidance, see Understanding monitoring reports.

7. Run the tests

python -m pytest

The verified suite contains 38 collected test cases and completes without failures on Python 3.11.

Troubleshooting

If an input file is not found, confirm that the terminal is in the project root. If the command itself is unavailable, reactivate .venv and repeat the project installation. Use the troubleshooting reference for other symptoms.

Next steps

Learn the available arguments in the CLI reference, then prepare a separate fictional snapshot with Preparing reputation data.