Urler – Domain discovery pipeline

CLI pipeline that uses AI (MiniMax) to suggest domain names, checks availability (WHOIS; Cloudflare when API is available), scores them (length, TLD, no-hyphen preference, and a recognizable-words component so domains that contain or are real words rank higher than random-looking strings), and sends a digest to Telegram. Tracks cost per run.

Quick start

1. Clone the repo and enter the project directory.

2. Create a virtualenv (recommended) and install dependencies:

   python3 -m venv .venv
   source .venv/bin/activate   # On Windows: .venv\Scripts\activate
   pip install -r requirements.txt

3. Configure: Copy .env.example to .env and set the required keys:

   • MINIMAX_API_KEY – from MiniMax platform
   • TELEGRAM_BOT_TOKEN – from @BotFather
   • TELEGRAM_CHAT_ID – your chat ID (e.g. from @userinfobot)

   Do not commit .env — it contains secrets. Use .env.example as a template only.

4. First run:

   • One batch (no Telegram bot): python run.py — generates domains, checks availability, scores them, and (if Telegram is configured) sends a digest. The data/ directory is created on first run; data/results.json stays empty until you run the pipeline.
   • Telegram bot: python run.py listen — starts the bot; then in Telegram send /start to open the menu and run searches from there.

Optional env check (after creating .env):

python scripts/check_env.py

Setup (detailed)

• Python 3.11+ and a virtualenv (recommended).

• Install dependencies: pip install -r requirements.txt

• Configuration: See Configuration below for all environment variables.

Usage

Commands

• run (default) – Full pipeline: generate domains → check availability → score → send Telegram → print cost.
• cost – Show cost history and total tracked spend.
• listen – Start the Telegram bot. Use /start in the bot to open the menu. All runs are started from the menu (Run → set options → confirm). See Telegram bot below.

Examples

# Basic run (default: no cap—take all domains MiniMax returns)
python run.py
python run.py run

# Cap to a specific number of domains
python run.py --count 20
python run.py --count 50 --keywords health

# Steer ideas with keywords or niche
python run.py --keywords tech
python run.py --keywords "finance investing"

# Only domains without hyphens (e.g. coolbrand.com, not cool-brand.com)
python run.py --no-hyphens
python run.py --no-hyphens --count 25 --keywords startup

# TLD(s): default .com; specify one or more (e.g. .com and .ai)
python run.py --tld com
python run.py --tld com ai --keywords tech

# Run the pipeline 5 batches in a row (each batch: generate → check → score → notify)
python run.py --batches 5
python run.py --batches 3 --count 20 --no-hyphens

# Never-ending mode: runs until /stop in Telegram, $5 cost, or 24h
python run.py --loop
python run.py --loop --no-hyphens

# Start the Telegram bot; then in Telegram use /start and the menu
python run.py listen

# Show how much you've spent (MiniMax + any paid APIs)
python run.py cost

Options

Option	Default	Description
--count N	100	Domains to generate per batch (min 5, max 100).
--keywords "..."	(none)	Keywords or niche to steer AI suggestions.
--no-hyphens	off	Only suggest and keep domains without hyphens.
--tld TLD ...	com	TLD(s) to generate and check (e.g. --tld com ai).
--batches N	1	Number of batches in this run (min 1, max 50). One batch = one generate → check → score → notify cycle.
--loop	off	Never-ending mode: run until you send /stop in Telegram, total cost reaches $5, or 24h elapses. Finishes the current batch then exits.
--llm-scores	off	Use MiniMax to score available domains (extra API call). Default uses heuristic scoring only unless USE_LLM_VALUATION=1.

Loop mode: With --loop, the pipeline runs batch after batch. It stops after the current batch when: you send /stop in the Telegram chat; total tracked cost reaches $5; or 24 hours have passed.

Telegram bot (when you run python run.py listen):

• Send /start (or /help) to open the main menu: Run | Results; Cost.
• Run – Guided flow: keywords (or skip) → no hyphens? → TLDs → use LLM to score? → how many domains to generate per batch? (5, 10, 50, or 100) → when to stop (end after N batches, spend limit, or run until you stop it) → if needed, pick N or max spend → confirm → run starts. A Stop button appears on the “Run started” message; pressing it or sending /stop stops at the next safe point.
• Results – Filter by score type and TLD, choose how many to show; the bot sends the top domains by score.
• Cost – Sends current cost summary.
• The bot sends a short up/down notification when the listen process starts or exits.

After generation, the list is screened against data/results.json: domains that have already appeared in any past run are skipped so only new candidates are checked. Output is progress-only (no AI text): “Generating domain ideas…”, “Generated N domains.” (or “Screened out X duplicate(s)… Y domains to check.”), “Checking availability…”, “Sending Telegram notification…”, “Done.”, then a cost line.

Scoring: Each domain gets a 0–100 score from length, TLD (.com preferred), no-hyphen preference, and recognizability (dictionary-based: real words or word-like segments get a bonus; long random strings get a small penalty). The top 20 available domains by score are sent to Telegram.

Scheduling

Run on a schedule (e.g. daily) with cron:

0 9 * * * cd /path/to/urler && /path/to/python run.py >> /path/to/urler/logs/urler.log 2>&1

Ensure logs exists or redirect elsewhere.

Data

• data/cost.db – run costs (MiniMax token usage and totals).
• data/availability_cache.db – optional availability cache when CACHE_AVAILABILITY=1.
• data/results.json – log of all pipeline runs and batches: timestamp, options, generated domains, availability (per domain), scores, and cost per batch.
• data/words.txt – bundled word list used for recognizability scoring (fallback when the english-words package is not used).

Configuration

All configuration is via environment variables (e.g. in .env). Never commit .env.

Variable	Required	Description
MINIMAX_API_KEY	Yes	MiniMax API key for domain generation (and optional LLM scoring). MiniMax platform
TELEGRAM_BOT_TOKEN	Yes for notifications / bot	Telegram Bot API token. @BotFather
TELEGRAM_CHAT_ID	Yes for notifications / bot	Chat ID that receives messages. @userinfobot
CLOUDFLARE_API_TOKEN	No	Cloudflare API (optional; when set, used for availability).
CLOUDFLARE_ACCOUNT_ID	No	Cloudflare account ID (with token).
CACHE_AVAILABILITY	No	Set to 1 to cache WHOIS/availability results. Default off.
CACHE_TTL_DAYS	No	Cache TTL in days (default 7).
LOOP_MAX_HOURS	No	Max hours for loop/“until stopped” runs (default 24).
LOOP_MAX_COST_USD	No	Max total cost (USD) for loop/“until stopped” runs (default 5.0).
APP_NAME	No	Name shown in Telegram (default Urler).