# CLI
------------------------------------------------------------------------
### seo_rat_sync
``` python
def seo_rat_sync(
site_url:str, # e.g. "sc-domain:example.com"
days:int=30, # how many days back to sync
secrets:str='/home/runner/.config/seo_rat/client_secrets.json', token:str='./token.pickle'
):
```
*Sync GSC data for a site*
------------------------------------------------------------------------
### seo_rat_report
``` python
def seo_rat_report(
website_id:int, # Website ID from the database
days:int=90, # Days of GSC data to include
insights:bool=False, # Include query trends and green keywords
):
```
*Generate SEO report for a website*
------------------------------------------------------------------------
### load_mapper
``` python
def load_mapper(
domain:str
)->dict:
```
*Load and run the mapper for a given domain.*
------------------------------------------------------------------------
### seo_rat_audit
``` python
def seo_rat_audit(
website_id:int, # Website ID from the database
url:str='', # Page URL to audit
file_path:str='', # Local file path to audit
days:int=90, # Days of GSC data to include
insights:bool=False, # Include trends and green keywords
):
```
*Audit a single page for SEO issues*
------------------------------------------------------------------------
### seo_rat_rank
``` python
def seo_rat_rank(
website_id:int, # Website ID from the database
keywords:str, # Comma-separated keywords to tracke
range_type:str='entire_history', # Date range type
country:str='', # Optional country code (e.g. 'sau')
):
```
*Check keyword rankings for a website*
------------------------------------------------------------------------
### print_rankings
``` python
def print_rankings(
results:list
)->None:
```
*Print keyword rankings as a rich table.*
------------------------------------------------------------------------
### seo_rat_top_pages
``` python
def seo_rat_top_pages(
website_id:int, # Website ID from the database
range_type:str='entire_history', # Date range type
limit:int=20, # Number of pages to show
country:str='', # Optional country code (e.g. 'sau')
):
```
*Show top performing pages by clicks and impressions*
------------------------------------------------------------------------
### print_top_pages
``` python
def print_top_pages(
rows:list, country:str | None=None
)->None:
```
*Print top pages as a rich table.*
------------------------------------------------------------------------
### seo_rat_wins
``` python
def seo_rat_wins(
website_id:int, # Website ID from the database
page_url:str='', # Optional page URL to filter
range_type:str='entire_history', # Date range type
min_impressions:int=100, # Minimum impressions threshold
min_position:float=10.0, # Minimum avg position
max_position:float=50.0, # Maximum avg position cutoff
limit:int=20, # Number of results to show
country:str='', # Optional country code
):
```
*Show high-impression, low-ranking keyword wins*
------------------------------------------------------------------------
### print_wins
``` python
def print_wins(
rows:list
)->None:
```
*Print keyword wins as a rich table.*
------------------------------------------------------------------------
### seo_rat_canob
``` python
def seo_rat_canob(
website_id:int, # Website ID from the database
keyword:str='', # Specific keyword to check (omit for full site scan)
similarity_threshold:float=0.8, # Similarity threshold for content groups
):
```
*Detect keyword cannibalization across pages*
------------------------------------------------------------------------
### print_canob_groups
``` python
def print_canob_groups(
result:dict
)->None:
```
*Print content group duplicates as a rich table.*
------------------------------------------------------------------------
### print_canob_keyword
``` python
def print_canob_keyword(
result:dict
)->None:
```
*Print keyword cannibalization result as a rich table.*
## Indexing
------------------------------------------------------------------------
### print_crawl_errors
``` python
def print_crawl_errors(
pages:list
)->None:
```
*Call self as a function.*
------------------------------------------------------------------------
### print_index_report
``` python
def print_index_report(
all_pages:list, grouped:dict
)->None:
```
*Call self as a function.*
------------------------------------------------------------------------
### print_index_check
``` python
def print_index_check(
status:IndexStatus
)->None:
```
*Call self as a function.*
------------------------------------------------------------------------
### fmt_date
``` python
def fmt_date(
dt:str | None
)->str:
```
*Format ISO datetime to YYYY-MM-DD.*
------------------------------------------------------------------------
### seo_rat_index_refresh
``` python
def seo_rat_index_refresh(
website_id:int, # Website ID from the database
sitemap_url:str, # Sitemap URL to fetch and re-check
):
```
*Refresh index status for all pages in a sitemap*
------------------------------------------------------------------------
### seo_rat_crawl_errors
``` python
def seo_rat_crawl_errors(
website_id:int, # Website ID from the database
):
```
*Show pages with crawl or indexing issues*
------------------------------------------------------------------------
### seo_rat_index_report
``` python
def seo_rat_index_report(
website_id:int, # Website ID from the database
sitemap_url:str='', # Sitemap URL to refresh data (optional)
):
```
*Show index status report grouped by reason*
------------------------------------------------------------------------
### seo_rat_index_check
``` python
def seo_rat_index_check(
website_id:int, # Website ID from the database
page_url:str, # Page URL to inspect
):
```
*Check and store index status for a single page*
## Trends & Comparsion
------------------------------------------------------------------------
### seo_rat_trend
``` python
def seo_rat_trend(
website_id:int, # Website ID from the database
keyword:str, # Keyword to track
range_type:str='entire_history', # Date range type
months:int=3, # Months for last_months range type
days:int=7, # Days for last_days range type
country:str='', # Optional country code
):
```
*Show position trend for a keyword aggregated by period*
------------------------------------------------------------------------
### aggregate_by_period
``` python
def aggregate_by_period(
rows:list, range_type:str, months:int=3
)->list:
```
*Aggregate daily rows by week or month depending on range.*
------------------------------------------------------------------------
### print_trend
``` python
def print_trend(
keyword:str, rows:list
)->None:
```
*Call self as a function.*
------------------------------------------------------------------------
### seo_rat_add_website
``` python
def seo_rat_add_website(
url:str, # Website URL (e.g., https://example.com)
name:str, # Display name for the website
site_type:str, # Type: quarto, astro, wordpress, etc.
desc:str='', # Optional description
lang:str='en', # Language code (e.g., en, ar)
content_dir:str='', # Local path to content directory
website_id:int=None, # ID to update existing website (omit to create new)
):
```
*Add a new website or update existing by ID*
------------------------------------------------------------------------
### seo_rat_list_websites
``` python
def seo_rat_list_websites(
):
```
*List all registered websites*
------------------------------------------------------------------------
### seo_rat_delete_website
``` python
def seo_rat_delete_website(
website_id:int, # Website ID to delete
):
```
*Delete a website by ID (irreversible!)*
``` python
# Test: List all websites
seo_rat_list_websites()
# Test: Add a new website
seo_rat_add_website(
url="https://test-example.com",
name="Test Site",
site_type="astro",
desc="A test website",
lang="en"
)
seo_rat_list_websites()
seo_rat_delete_website(5)
seo_rat_list_websites()
```
๐ Websites
โโโโโโณโโโโโโโโโโโโโณโโโโโโโโโโโโโโโโโโโโโโโโโณโโโโโโโโโณโโโโโโโ
โ ID โ Name โ URL โ Type โ Lang โ
โกโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฉ
โ 1 โ Awazly โ https://awazly.com โ astro โ ar โ
โ 2 โ shelid โ https://shelid.com โ astro โ ar โ
โ 3 โ emdadelgaz โ https://emdadelgaz.com โ astro โ ar โ
โ 4 โ kareemai โ https://kareemai.com โ quarto โ ar โ
โโโโโโดโโโโโโโโโโโโโดโโโโโโโโโโโโโโโโโโโโโโโโโดโโโโโโโโโดโโโโโโโ
โ
Website added: Test Site (ID: 5)
๐ Websites
โโโโโโณโโโโโโโโโโโโโณโโโโโโโโโโโโโโโโโโโโโโโโโโโณโโโโโโโโโณโโโโโโโ
โ ID โ Name โ URL โ Type โ Lang โ
โกโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฉ
โ 1 โ Awazly โ https://awazly.com โ astro โ ar โ
โ 2 โ shelid โ https://shelid.com โ astro โ ar โ
โ 3 โ emdadelgaz โ https://emdadelgaz.com โ astro โ ar โ
โ 4 โ kareemai โ https://kareemai.com โ quarto โ ar โ
โ 5 โ Test Site โ https://test-example.com โ astro โ en โ
โโโโโโดโโโโโโโโโโโโโดโโโโโโโโโโโโโโโโโโโโโโโโโโโดโโโโโโโโโดโโโโโโโ
โ
Deleted: Test Site (ID: 5)
๐ Websites
โโโโโโณโโโโโโโโโโโโโณโโโโโโโโโโโโโโโโโโโโโโโโโณโโโโโโโโโณโโโโโโโ
โ ID โ Name โ URL โ Type โ Lang โ
โกโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฉ
โ 1 โ Awazly โ https://awazly.com โ astro โ ar โ
โ 2 โ shelid โ https://shelid.com โ astro โ ar โ
โ 3 โ emdadelgaz โ https://emdadelgaz.com โ astro โ ar โ
โ 4 โ kareemai โ https://kareemai.com โ quarto โ ar โ
โโโโโโดโโโโโโโโโโโโโดโโโโโโโโโโโโโโโโโโโโโโโโโดโโโโโโโโโดโโโโโโโ
------------------------------------------------------------------------
### seo_rat_compare
``` python
def seo_rat_compare(
website_id:int, # Website ID from the database
start1:str, # First period start (YYYY-MM-DD)
end1:str, # First period end (YYYY-MM-DD)
start2:str, # Second period start (YYYY-MM-DD)
end2:str, # Second period end (YYYY-MM-DD)
page_url:str='', # Optional specific page URL to compare
):
```
*Compare GSC metrics between two date ranges, optionally for a specific
page*
------------------------------------------------------------------------
### print_comparison
``` python
def print_comparison(
result:dict
)->None:
```
*Print date range comparison as a rich table.*
``` python
# Test: Compare two date ranges (use a real website_id from your DB)
seo_rat_compare(
website_id=4, # Change to real ID
start1="2025-03-01",
end1="2025-03-31",
start2="2025-04-01",
end2="2025-04-05",
page_url="https://kareemai.com/" # Change to real URL or omit for site-wide
)
```
๐ Page Comparison: https://kareemai.com/
โโโโโโโโโโโโโโโโณโโโโโโโโโโโโโโโโโโโโโโโโโโโณโโโโโโโโโโโโโโโโโโโโโโโโโโโณโโโโโโโโโโโโโโโโโโโโโโ
โ Metric โ 2025-03-01 to 2025-03-31 โ 2025-04-01 to 2025-04-05 โ Change โ
โกโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฉ
โ Clicks โ 0 โ 0 โ +0 โ
โ Impressions โ 3 โ 2 โ -1 โ
โ Avg Position โ 17.67 โ 4.5 โ -13.170000000000002 โ
โ Avg CTR % โ 0 โ 0 โ - โ
โโโโโโโโโโโโโโโโดโโโโโโโโโโโโโโโโโโโโโโโโโโโดโโโโโโโโโโโโโโโโโโโโโโโโโโโดโโโโโโโโโโโโโโโโโโโโโโ
------------------------------------------------------------------------
### seo_rat_country_breakdown
``` python
def seo_rat_country_breakdown(
website_id:int, # Website ID from the database
range_type:str='last_month', # Date range type
start_date:str='', # Custom start date (YYYY-MM-DD)
end_date:str='', # Custom end date (YYYY-MM-DD)
page_url:str='', # Optional specific page URL to filter
limit:int=20, # Number of top countries to show
):
```
*Show traffic breakdown by country, optionally for a specific page*
------------------------------------------------------------------------
### print_country_breakdown
``` python
def print_country_breakdown(
rows:list
)->None:
```
*Print country breakdown as a rich table.*
``` python
# Test: Country breakdown (use a real website_id from your DB)
seo_rat_country_breakdown(
website_id=1, # Change to real ID
limit=20
)
seo_rat_country_breakdown(
website_id=4, # Change to real ID
range_type="last_month",
page_url="https://kareemai.com/blog/posts/speech_recognition/muaalm_quran_chance.html", # Change to real URL or omit for site-wide
limit=10 # Show top 10 countries
)
```
๐ Traffic by Country
โโโโโโโโโโโณโโโโโโโโโโโโโณโโโโโโโโโโโโโโณโโโโโโโโโโโโโโโณโโโโโโโ
โ Country โ Clicks โ Impressions โ Avg Position โ CTR โ
โกโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฉ
โ sau โ 72 (85.7%) โ 18,763 โ 25.6 โ 0.3% โ
โ egy โ 8 (9.5%) โ 2,440 โ 23.8 โ 0.3% โ
โ lby โ 1 (1.2%) โ 43 โ 5.2 โ 2.9% โ
โ kwt โ 1 (1.2%) โ 403 โ 17.1 โ 0.5% โ
โ esp โ 1 (1.2%) โ 15 โ 20.3 โ 6.7% โ
โ are โ 1 (1.2%) โ 94 โ 19.1 โ 1.2% โ
โ zaf โ 0 (0.0%) โ 1 โ 9.0 โ 0.0% โ
โ yem โ 0 (0.0%) โ 119 โ 7.0 โ 0.0% โ
โ vnm โ 0 (0.0%) โ 17 โ 40.0 โ 0.0% โ
โ uzb โ 0 (0.0%) โ 1 โ 6.0 โ 0.0% โ
โ usa โ 0 (0.0%) โ 111 โ 21.3 โ 0.0% โ
โ ukr โ 0 (0.0%) โ 1 โ 49.0 โ 0.0% โ
โ uga โ 0 (0.0%) โ 1 โ 12.0 โ 0.0% โ
โ twn โ 0 (0.0%) โ 1 โ 8.0 โ 0.0% โ
โ tur โ 0 (0.0%) โ 19 โ 7.6 โ 0.0% โ
โ tun โ 0 (0.0%) โ 6 โ 5.5 โ 0.0% โ
โ tha โ 0 (0.0%) โ 1 โ 42.0 โ 0.0% โ
โ tcd โ 0 (0.0%) โ 2 โ 6.0 โ 0.0% โ
โ syr โ 0 (0.0%) โ 88 โ 5.1 โ 0.0% โ
โ swe โ 0 (0.0%) โ 2 โ 19.5 โ 0.0% โ
โโโโโโโโโโโดโโโโโโโโโโโโโดโโโโโโโโโโโโโโดโโโโโโโโโโโโโโโดโโโโโโโ
Total: 84 clicks across 20 countries
No country data found