Metadata-Version: 2.4
Name: RDTSearch
Version: 0.15.0
Summary: Official terminal client for RDTvlokip Search — an independent, privacy-first French search engine
Author: RDTvlokip
License-Expression: AGPL-3.0-or-later
Project-URL: Homepage, https://rdtsearch.rdtvlokip.fr/
Project-URL: Search engine, https://search.rdtvlokip.fr
Project-URL: API, https://search.rdtvlokip.fr/api-docs
Project-URL: Repository, https://github.com/RDTvlokip/rdtsearch
Project-URL: PyPI, https://pypi.org/project/rdtsearch/
Keywords: search,seo,backlinks,cli,tui,search engine,privacy
Classifier: Environment :: Console
Classifier: Natural Language :: French
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP :: Indexing/Search
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# RDTSearch

Official terminal client for **[RDTvlokip Search](https://search.rdtvlokip.fr)** — an independent, privacy-first French search engine (~4.6M indexed pages, in-house crawler).

**Single file, zero dependencies** (Python 3.8+ stdlib only), bilingual **French / English**, Windows first, Linux/macOS supported.

## Features

- **Search** the index with highlighted snippets, featured snippets, tracker and adult-content flags
- **Domain tools**: indexing status, submission tracking, continuous indexing **watch**
- **Engine statistics**: pages/domains/URLs totals, daily and hourly crawl charts
- **Backlink analysis (SEO)**: global link graph stats, top linked domains, per-domain backlinks (source, anchor, nofollow/sponsored/UGC), anchor-text distribution, evolution history, CSV/JSON export
- **SEO duel** (`compare`): two domains side by side — indexed pages, inbound links, top anchor, winner
- **Self-diagnostic** (`doctor`): terminal, configuration and server health in one command
- **Local snapshot cache**: backlink analyses are kept per day to save the anonymous quota
- **Autocomplete suggestions** and **server health** (latency, server time)
- **Interactive TUI**: framed interface with live stats sidebar, Tab completion and command palette (with aliases), recent-domain completion for domain arguments, type-to-filter menus, fish-style ghost completion, input history, arrow-key menus, contextual footer, result detail sheets with score breakdown, open results in your browser or copy their URL (`c <n>`), per-command help (`/help backlinks`), and **Vloki** — a pixel-art spider companion on the home screen with rotating tips, who waves at you on launch and every 10 idle seconds
- **Subtle animations** (optional, on by default): eased counters and bars, top-down view reveal, view-pill flash, error shake, sparklines drawn in, breathing watch indicator with a live sparkline, notice flash, spinner with elapsed time and request steps — all skipped outside a TTY
- **Settings** (`/settings` in the TUI, `rdtsearch settings` in the CLI): language, theme (default / ocean / high-contrast), glyphs (UTF/ASCII), colors, animations, adult-content filter, persistent history, API timeout, default stats period, sidebar, watch bell — with reset, cache purge and a terminal diagnostic
- **Scripting friendly**: `--json` on every command, piped mode, colors auto-disabled outside a TTY, HTTP 429 / `Retry-After` handled

## Installation

```
pip install rdtsearch
```

or, isolated (recommended for CLI tools):

```
pipx install rdtsearch
```

Requires Python 3.8+. No third-party packages.

## CLI usage

```
rdtsearch search "debian" [-p N]       search the index (page N)
rdtsearch domain example.com           indexing status of a domain
rdtsearch watch example.com [-i SEC]   watch indexing continuously (default 300s)
rdtsearch compare a.com b.com          SEO duel between two domains
rdtsearch stats [-d DAYS]              engine and crawler statistics (default: stats_days setting)
rdtsearch suggest "linu"               autocomplete suggestions
rdtsearch health                       server health and latency
rdtsearch doctor                       client + server self-diagnostic
rdtsearch status example.com           submission status of a domain
rdtsearch settings [KEY [VALUE]]       show or change persistent settings
                                       keys: lang theme glyphs colors hide_adult history
                                             timeout animations stats_days sidebar bell
                                       actions: reset, clear-cache

rdtsearch backlinks stats              global link graph statistics
rdtsearch backlinks top [-n N]         domains with the most backlinks
rdtsearch backlinks detail example.com backlinks of a domain (source, anchor, flags)
rdtsearch backlinks anchors example.com anchor-text distribution
rdtsearch backlinks history example.com backlink evolution snapshots
rdtsearch backlinks export example.com [--format csv|json] [-o FILE]
```

Global options:

| Option | Effect |
|---|---|
| `--json` | raw JSON output (every command) |
| `--lang auto\|fr\|en` | interface language (default: saved setting or OS language) |
| `--timeout S` | API timeout in seconds, 1–120 (default: 15) |
| `--no-color` | disable colors |
| `--tui` | force the interactive interface |
| `--version` | show version |

`backlinks detail` and `/backlinks` reuse today's local snapshot to save the anonymous quota; add `--fresh` to query the API again.

## Interactive TUI

Run `rdtsearch` with no arguments in a terminal.

- **Type anything** and press Enter to search
- **Digits** open a result in your browser, `i <n>` shows a result detail sheet (score breakdown), `c <n>` copies its URL to the clipboard, `n` / `p` change page
- **Slash commands**: `/backlinks` `/clear` `/compare` `/doctor` `/domain` `/health` `/help` `/refresh` `/settings` `/stats` `/status` `/suggest` `/watch` `/quit` — `/help <command>` shows a focused help sheet with examples and aliases
- **`/watch <domain> [sec]`** runs a live indexing monitor (default 30s): the frame redraws with a timestamped change log and a live sparkline — press any key to stop; optional bell on change
- **`/compare a.com b.com`**, **`/doctor`** and **`/backlinks history <domain>`** (evolution sparkline + snapshot table) are available in the TUI too, as full views
- **`/domain`** shows the domain's share of the whole index; **`/stats`** shows the trend vs the previous period
- **Tab**: command completion, recent-domain completion after `/domain`, `/backlinks`, `/status`, `/watch`, `/compare`, command-name completion after `/help`, contextual menus (suggestions, results, periods, settings), and a full command palette on an empty line — in the results menu, `i` opens the detail sheet instead of the browser
- **Type-to-filter menus**: typing letters filters any menu live; Backspace erases the filter, digits still jump to an entry
- **Ghost completion** (fish-style): the likely continuation appears in grey, accept it with `→` or `Tab` at the end of the line
- **↑ ↓** input history, **Esc** clears the line, commands are colored green (valid) or red (unknown) as you type

## Settings

Persistent settings: interface **language**, **theme** (default / ocean / high-contrast — colors the frame border, header bar, view pills and logo), **glyphs** (auto / UTF / ASCII), **colors** (auto / on / off), **animations**, **adult-content** filter, **history** persistence (off by default), **API timeout**, default **stats period**, **sidebar** visibility, and **watch bell**. A diagnostic panel shows the detected terminal size, encoding, active glyphs/colors and OS language.

- **TUI**: `/settings`, then Tab or the setting's number (`1`–`13`); the current value is checked and preselected, and after saving you return to the settings menu to chain changes (Esc to leave); the colors/glyphs menus preview the highlighted value live; modified settings are marked with a bullet. Direct form: `/settings lang fr`, `/settings reset`, `/settings clear-cache`.
- **CLI**: `rdtsearch settings` (overview, `--json` supported), `rdtsearch settings timeout 30` (set and save), `rdtsearch settings lang` (show one value), `rdtsearch settings reset`, `rdtsearch settings clear-cache`. Unlike `--lang`/`--timeout` (session only), `settings` persists.

Config lives in `%APPDATA%\rdtsearch\` (Windows) or `~/.config/rdtsearch/` (Unix).

## Anonymous limits

The backlinks API has a free anonymous tier (server-side): 10 backlinks per analysis, 3 analyses per day, export reserved for premium accounts. The client reports these limits clearly and caches each analysis locally so re-viewing it does not spend quota.

## Terminal support

- Full Unicode interface in modern terminals: Windows Terminal, VS Code, ConEmu/Cmder, and all Unix terminals
- Automatic ASCII fallback in the legacy Windows console (cmd.exe / conhost); forceable via `/settings`
- Piped or redirected output falls back to a plain, script-friendly mode

## License

[GNU AGPLv3](https://www.gnu.org/licenses/agpl-3.0.html) — free software; if you run a modified version as a network service, you must offer its source to users.

## Links

- Homepage: https://rdtsearch.rdtvlokip.fr/
- PyPI: https://pypi.org/project/rdtsearch/
- Source (GitHub): https://github.com/RDTvlokip/rdtsearch
- Search engine: https://search.rdtvlokip.fr
- API documentation: https://search.rdtvlokip.fr/api-docs
