Usage

#A first scan

bash

aliens_eye someone

Aliens Eye asks every site in its catalog whether a profile called someone exists, showing live progress, then prints a table of what it found and writes a report to results/.

Run aliens_eye with no arguments and it asks for everything instead: the usernames, a scan profile, a scan level and where to save the report.

Several usernames scan one after another:

bash

aliens_eye someone someone_else

A username has to be at least two characters.

#Reading the results

Every site gets one of these verdicts:

Status	Means
Found	The page looks like a real profile and survived the checks every Found gets.
Maybe	Something is there, but the evidence is mixed: a challenge page, a block, a site that answers the same way for a made-up name.
Not Found	The site said no such user (HTTP 404 or 410), or the page looks like its "no such user" page.
Skipped	The username cannot exist on that site: the site's rules say it is too long, too short or uses characters it does not allow. Nothing is requested.
Error, Timeout	The request failed after its retries: no answer in time, connection refused, an unreadable response.

Found and Maybe carry a confidence percentage. A Found at 85% or more counts as a high-confidence match in the summary.

Found and Maybe are leads to check, not findings. A username on two sites can belong to two different people, and a site can show a profile-looking page for a name nobody has. Open the link and look before you rely on a result.

To see why a site got its verdict, add --explain: it prints the HTTP response, what each detector scored, the thresholds, the control check and any browser fallback.

bash

aliens_eye someone --site github --explain

#How long a scan takes

By default a scan covers the extended catalog of 7,700+ sites. At the default settings Aliens Eye checks about 16 sites a second, so a plain scan of one username takes around eight minutes, longer through a proxy or Tor.

To go faster:

--catalog standard scans the original list of 788 sites, in under a minute.
--site github,reddit,gitlab scans only sites whose name contains one of those words.
--tag coding scans only sites with that tag (see Sites and catalogs).
--no-nsfw skips adult sites.
--exclude-site skips sites by name.

#Scan levels: variations of the name

A level decides which spellings of the username are tried:

Level	Tries	Usernames per input
`basic` (default)	the name exactly as typed	1
`intermediate`	plus `name_`, `_name`, `name.`, `name1`, `name123`, `__name__`, …	12
`advanced`	plus prefixes and suffixes: `realname`, `the_name`, `name.official`, …	123

bash

aliens_eye someone -l intermediate

Each variation is a full scan, so advanced multiplies the work by 123: close to a million requests against the extended catalog. When you choose Advanced at the interactive prompt, Aliens Eye says how many requests it will make and asks first; passing -l advanced as a flag does not ask.

#Starting from an email, a name or a phone number

bash

aliens_eye --from-email john.doe@example.com    # john.doe, johndoe, john_doe, john
aliens_eye --from-name "John Doe"               # john, doe, johndoe, john.doe, jdoe, …
aliens_eye --from-phone "+1 555 0100"           # the digits, 15550100

These generate the usernames to scan; they can be combined with usernames of your own.

#Scan profiles

A profile sets the network options in one go, and skips the interactive question:

Profile	Concurrency	Timeout	Retries	Playwright
`quick`	25	6 s	1	off
`full`	50	10 s	2	off (the defaults)
`aggressive`	80	15 s	3	on

bash

aliens_eye someone --profile quick

An option given on the command line, such as -c 100, wins over the profile.

#Proxies and Tor

bash

aliens_eye someone --tor                                # socks5://127.0.0.1:9050
aliens_eye someone --proxy socks5://127.0.0.1:1080
aliens_eye someone --proxy http://user:pass@proxy:8080

--tor needs a Tor daemon running locally. HTTP(S), SOCKS4 and SOCKS5 proxies are supported. Through a proxy, sites see the proxy's address; some block well-known exit nodes, which shows up as more Maybe results.

#Saving and reading reports

Reports go to results/ as <username>_<level>_<date>_<time>.json. Choose formats and a directory:

bash

aliens_eye someone --format json,html,csv --output reports
aliens_eye someone --format all             # JSON, CSV, HTML and Markdown

Reports lists every format, including PDF and graph exports.

Show a saved report again, or compare two:

bash

aliens_eye -r results/someone_basic_20261107_120000.json
aliens_eye -r results/someone_basic_20261107_120000.json --explain
aliens_eye diff results/old.json results/new.json

#In scripts and pipelines

--plain drops the colours and the progress display. --json-stdout prints the report as JSON on standard output, one line per username, and sends the banner, progress and summary to standard error:

bash

aliens_eye someone --json-stdout \
  | jq -r '.variations[].sites[] | select(.status == "Found") | .url'

--only-found keeps only Found and Maybe sites in the report; the counts still cover every site scanned.

To hide the note about the author's other project under the banner, set ALIENS_EYE_NO_PROMO=1.

#Responsible use

Aliens Eye only requests public profile pages, the same ones anyone can open in a browser. What you do with the results is your responsibility: follow the law where you are and the sites' terms, and do not use it to stalk or harass anyone.

#Next

Investigations: link the profiles, follow their links, watch for changes.
Command reference: every option and subcommand.