Find the subdomains of any domain from the terminal, powered by the free Subdomain API - no signup, no API key.
Single-file Python script with inline dependency metadata (PEP 723), run with uv. No install, no venv management.
uv run sda.py example.comThe first run resolves httpx, rich, and typer into uv's cache; every run
after that starts instantly.
uv run sda.py <domain> [options]
The input is forgiving - these all look up example.com:
uv run sda.py example.com
uv run sda.py https://www.example.com/about
uv run sda.py blog.example.com
uv run sda.py "user:pass@example.com:8080/path"| Option | Description |
|---|---|
--json, -j |
Output the full response as JSON (domain, count, total, subdomains). |
--csv |
Output as CSV with a subdomain header. |
--count-only, -c |
Output only the number of subdomains returned. |
--output, -o FILE |
Write to a file instead of stdout; a .txt / .json / .csv extension selects the format. |
--timeout SECONDS |
Request timeout (default: 30). |
--retries N |
Retries after HTTP 429/503 with exponential backoff, honoring Retry-After (default: 3). |
--quiet, -q |
Suppress status messages on stderr. |
--version |
Show the version and exit. |
--help |
Show help. |
# Pipe-friendly: plain list, one subdomain per line
uv run sda.py github.com --quiet | sort
# Just the count
uv run sda.py github.com --count-only
# JSON to a file (format inferred from extension)
uv run sda.py github.com -o github-subs.json
# CSV via flag
uv run sda.py github.com --csv -o github-subs.csv| Code | Meaning |
|---|---|
| 0 | Success (including "no subdomains found"). |
| 1 | API or network error (invalid domain rejected by the API, exhausted retries, timeout). |
| 2 | Usage error (invalid input, conflicting flags). |
| 130 | Interrupted (Ctrl+C). |
- Queries
GET https://api.subdomain.app/v1/query?domain=<domain>. - Input is normalized locally (scheme,
www.,*., credentials, port, path stripped), then the API further reduces it to the registrable domain. - Results are printed one per line on stdout; the spinner, summary panel, and warnings go to stderr, so piping stays clean.
- Up to 10,000 subdomains per domain (most recently seen first). When the
index knows more (
total>count), the summary panel says so. - HTTP 429/503 responses are retried with exponential backoff + jitter,
honoring the
Retry-Afterheader.
Results come from a passive, historic index. Some subdomains may no longer resolve, others may be brand new, and coverage is best-effort - verify before relying on the data. Only queried domains are stored by the service; see the site's privacy policy and terms.
Run the offline test suite (mocked HTTP via httpx.MockTransport, CLI via
typer's CliRunner):
uv run test_sda.pytest_sda.py carries its own PEP 723 header including pytest, so no project
setup is needed.