netlascli

CLI and Python client library for the Netlas.io API — internet host, domain, WHOIS, and certificate intelligence

---

Overview

netlascli is a Python toolkit for the Netlas API — internet-wide host, domain, WHOIS, certificate, and Discovery data. It provides a typed client library, a full-coverage CLI, and table/JSON/TOON output, built entirely on the Python standard library.

Key Features

Feature	Description
Zero runtime dependencies	Built on the Python standard library only
Full API coverage	Every Netlas API operation exposed as a typed client method and a CLI subcommand
Streaming downloads	Large result sets are yielded one document at a time instead of buffered in memory
Table, JSON, or TOON output	--format table (default), json, or toon
Typed errors	HTTP failures raise typed NetlasAPIError subclasses with status_code and body
Automatic retries	HTTP 429 responses are retried automatically
Cross-platform	Windows, Linux, and macOS, on x64 and ARM

Supported Outputs

Search/Detail results   table, JSON, TOON
Downloads                NDJSON (stdout or file), streamed

---

Installation

From PyPI

pip install netlascli

From Source

git clone https://github.com/seifreed/netlascli.git
cd netlascli
python3 -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -e ".[dev]"

---

Quick Start

# Save your API key
netlascli savekey YOUR_API_KEY

# Get a host summary
netlascli host example.com

# Search responses and export as JSON
netlascli responses-search "domain:example.com" --fields ip,port --format json

The API key can also be supplied via the --api-key flag or the NETLAS_API_KEY environment variable instead of netlascli savekey.

---

Usage

Command Line Interface

netlascli responses-search "domain:example.com" --fields ip,port
netlascli responses-count "domain:example.com"
netlascli domains-search "domain:*.example.com"
netlascli certs-search "domain:example.com"
netlascli indices
netlascli scans
netlascli user

Run netlascli --help or netlascli <command> --help for the full option list.

Available Commands (by category)

Category	Commands
Auth	savekey
Host	host, my-host
Responses	responses-search, responses-count, responses-download, responses-facet
Domains	domains-search, domains-count, domains-download, domains-facet
IP WHOIS	ip-whois-search, ip-whois-count, ip-whois-download, ip-whois-facet
Domain WHOIS	domain-whois-search, domain-whois-count, domain-whois-download, domain-whois-facet
Certificates	certs-search, certs-count, certs-download
Metadata	indices, mapping, facet-mapping
Discovery	discovery-node-searches, discovery-node-search, discovery-group-searches, discovery-group-search, discovery-status
Scans	scans, scan-create, scanner-agents, scan, scan-update, scan-delete, scan-report, scan-priority, scans-delete
Datastore	products, product, product-link
User	user, user-update, user-counters

*-search commands have a short alias dropping -search (responses, domains, ip-whois, domain-whois, certs); *-facet commands alias to *-stat (e.g. responses-stat), matching the query/stat naming from the netlas-python CLI. -i/--include FIELDS and -e/--exclude FIELDS are shorthand for --fields FIELDS --source-type include/exclude on search, download, and host commands (mutually exclusive with each other).

Downloads and Discovery group searches show a live progress line on a real terminal (stderr only — never stdout); pass --no-progress to disable it, or redirect stderr to make it disappear automatically in scripts/CI.

Global Flags

Option	Description
--api-key API_KEY	Netlas API key (overrides saved key and env var)
--base-url BASE_URL	Netlas API server URL
--format {table,json,toon}	Output format for non-streaming commands (default: table)
--no-progress	Disable the progress line for downloads and Discovery group searches

Output Format

Every non-streaming command prints an ASCII table by default:

netlascli indices
netlascli user --format json
netlascli user --format toon

Nested fields are flattened to dotted rows in table view (whois.org: ACME Inc); JSON and TOON preserve the full structure.

Downloading Data

*-download commands stream results to stdout one document per line (NDJSON), so they never hold the full result set in memory:

netlascli responses-download "domain:example.com" --size 1000 --fields ip,port --source-type include
netlascli responses-download "domain:example.com" --all --fields ip,port --source-type include
netlascli responses-download "domain:example.com" --size 500 --output-type csv --fields "*" --source-type include
netlascli responses-download "domain:example.com" --all --fields ip,port --source-type include -o results.ndjson

--size N downloads up to N documents; --all downloads every matching document (it counts first, then downloads — mutually exclusive with --size). -o/--output-file PATH writes to a file instead of stdout (- explicitly means stdout, the default). --format does not apply to download commands — streamed output is always printed as it arrives.

---

Python Library

Basic Usage

from netlascli import NetlasClient

client = NetlasClient(api_key="YOUR_API_KEY")

host = client.host("example.com")
results = client.search_responses("domain:example.com", fields=["ip", "port"])
count = client.count_responses("domain:example.com")
scans = client.get_scans()

# download_* and download_all_* are generators: documents are yielded as
# they arrive, so the full result set is never held in memory at once.
for document in client.download_responses(
    "domain:example.com", size=1000, fields=["ip", "port"], source_type="include"
):
    ...

for document in client.download_all_responses(
    "domain:example.com", fields=["ip", "port"], source_type="include"
):
    ...

If api_key is omitted, it is resolved from the NETLAS_API_KEY environment variable, then from the key saved by netlascli savekey.

Rendering Results

from netlascli import output

print(output.render(host, "table"))  # or "json" / "toon"

---

Requirements

• Python 3.14+
• See pyproject.toml for dependencies and extras

---

Contributing

Contributions are welcome.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

---

Support the Project

If this project is useful in your workflows, you can support development:

---

License

This project is licensed under the MIT license. See LICENSE.

Attribution

• Author: Marc Rivero López | @seifreed
• Repository: github.com/seifreed/netlascli

---

_{Built for practical internet-wide reconnaissance and OSINT automation}