Metadata-Version: 2.4
Name: netlascli
Version: 0.3.1
Summary: CLI and Python client library for the Netlas.io API
Project-URL: Homepage, https://github.com/netlas-io/netlascli
Project-URL: Documentation, https://netlas.io/api
Project-URL: Issues, https://github.com/netlas-io/netlascli/issues
Author-email: "Marc Rivero López | @seifreed" <mriverolopez@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: api-client,cli,netlas,osint,security
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Information Technology
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Internet
Classifier: Topic :: Security
Requires-Python: >=3.14
Provides-Extra: dev
Requires-Dist: bandit>=1.8; extra == 'dev'
Requires-Dist: black>=24.10; extra == 'dev'
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: mypy>=1.13; extra == 'dev'
Requires-Dist: pip-audit>=2.7; extra == 'dev'
Requires-Dist: pytest-cov>=6.0; extra == 'dev'
Requires-Dist: pytest>=8.3; extra == 'dev'
Requires-Dist: ruff>=0.8; extra == 'dev'
Description-Content-Type: text/markdown

<p align="center">
  <img src="https://img.shields.io/badge/netlascli-Netlas.io%20API%20Client-blue?style=for-the-badge" alt="netlascli">
</p>

<h1 align="center">netlascli</h1>

<p align="center">
  <strong>CLI and Python client library for the Netlas.io API — internet host, domain, WHOIS, and certificate intelligence</strong>
</p>

<p align="center">
  <img src="https://img.shields.io/badge/python-3.14%2B-blue?style=flat-square&logo=python&logoColor=white" alt="Python Version">
  <a href="https://github.com/seifreed/netlascli/blob/main/pyproject.toml"><img src="https://img.shields.io/badge/dependencies-zero%20runtime-brightgreen?style=flat-square" alt="Zero Runtime Dependencies"></a>
  <img src="https://img.shields.io/badge/license-MIT-green?style=flat-square" alt="License">
  <a href="https://github.com/seifreed/netlascli/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/seifreed/netlascli/ci.yml?style=flat-square&logo=github&label=CI" alt="CI Status"></a>
</p>

<p align="center">
  <a href="https://github.com/seifreed/netlascli/stargazers"><img src="https://img.shields.io/github/stars/seifreed/netlascli?style=flat-square" alt="GitHub Stars"></a>
  <a href="https://github.com/seifreed/netlascli/issues"><img src="https://img.shields.io/github/issues/seifreed/netlascli?style=flat-square" alt="GitHub Issues"></a>
  <a href="https://buymeacoffee.com/seifreed"><img src="https://img.shields.io/badge/Buy%20Me%20a%20Coffee-support-yellow?style=flat-square&logo=buy-me-a-coffee&logoColor=white" alt="Buy Me a Coffee"></a>
</p>

---

## Overview

**netlascli** is a Python toolkit for the [Netlas](https://netlas.io) 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`](https://github.com/toon-format/spec) |
| **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

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

---

## Installation

### From PyPI

```bash
pip install netlascli
```

### From Source

```bash
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

```bash
# 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

```bash
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:

```bash
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:

```bash
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

```python
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

```python
from netlascli import output

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

---

## Requirements

- Python 3.14+
- See [pyproject.toml](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:

<a href="https://buymeacoffee.com/seifreed" target="_blank">
  <img src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png" alt="Buy Me A Coffee" height="50">
</a>

---

## License

This project is licensed under the MIT license. See [LICENSE](LICENSE).

**Attribution**
- Author: **Marc Rivero López** | [@seifreed](https://github.com/seifreed)
- Repository: [github.com/seifreed/netlascli](https://github.com/seifreed/netlascli)

---

<p align="center">
  <sub>Built for practical internet-wide reconnaissance and OSINT automation</sub>
</p>
