# Synthient CLI

One binary for everything Synthient provides: account status, IP and domain intelligence, live feed streams, Parquet snapshots, and protobuf schemas over gRPC.

It speaks two languages at once: readable, colorized output when you run it by hand, and clean `json` / `csv` / NDJSON when a script, CI job, or notebook is on the other end. Production endpoints are baked in, so there's nothing to configure for normal use.

> **Note**: The CLI is open source at [github.com/synthient/cli](https://github.com/synthient/cli) and wraps the same v4 HTTP API, feed, and gRPC surfaces documented elsewhere in these docs.

## Install

Homebrew is the quickest path:

```bash
brew install synthient/tap/synthient
```

Or install with Go, or build from a local checkout:

**Install**

```bash title="Go"
go install github.com/synthient/cli/cmd/synthient@latest
```

```bash title="Source"
git clone https://github.com/synthient/cli.git
cd cli
go build -o ./dist/synthient ./cmd/synthient
./dist/synthient --version
```

## The shape of the CLI

Every command falls under one of a few surfaces. Once you know the map, the rest of this page is just detail.

```txt
synthient
  auth                 Store or remove an API key in the OS keychain
  status               Config, auth source, endpoint, quota, and scope status
  account              Account, scope, and quota details
  scopes               Which Synthient scopes the active key holds
  lookup               IP intelligence — one IP, many IPs, or stdin
  lookup domain        Domain intelligence from Helios observations
  feeds streams        List supported feed streams
  feeds snapshots      List daily and hourly Parquet snapshots
  feeds meta|schema    Snapshot metadata and Parquet schema
  feeds checksum       Expected SHA-256 for a snapshot
  feeds download       Download a snapshot to a Parquet file
  download             Shorthand wrapper around feeds download
  stream               Stream live NDJSON feed events
  grpc schema          Output protobuf descriptors via gRPC reflection
  mcp                  Run a Model Context Protocol server over stdio
```

Two conventions run through almost all of it:

- **Output mode:** finite read commands take `--format text|json|csv` and `--output -|file`. `text` is for humans; `json`/`csv` are for everything else.
- **Scopes:** feed and stream commands are gated by per-feed scopes on your key. `synthient scopes` shows what you hold; `--no-preflight` skips the check when you already know.

## Authentication

For automation, hand the key in through the environment:

```bash
export SYNTHIENT_API_KEY="..."
synthient status
```

For interactive use, store it once in the OS keychain; `status` confirms the active source without ever printing the secret:

```bash
synthient auth          # save to keychain
synthient auth --logout # remove it
```

**Demo:** `synthient auth && synthient status` — Store a key in the OS keychain, then confirm which auth source is active, the resolved endpoint, and remaining quota. The key itself is never shown.

Credentials resolve in order, first match wins:

```txt
1. SYNTHIENT_API_KEY        environment variable
2. .env in the working dir  (SYNTHIENT_API_KEY="...")
3. OS keychain              populated by `synthient auth`
```

## Account & access

`status` is the fast operational check; `account` is the machine-readable version for scripts; `scopes` shows which data surfaces your key can reach.

```bash
synthient status
synthient account --format json | jq .
synthient scopes
```

Feed and stream commands run a scope preflight before hitting the data plane. Skip it with `--no-preflight` when you already know the key is scoped, or when one less API call matters:

```bash
synthient feeds snapshots proxies --no-preflight
synthient stream proxies --duration 5s --no-preflight
```

| Scope                                           | Grants                                          |
| ----------------------------------------------- | ----------------------------------------------- |
| `BASIC`                                         | Account, IP lookup, batch lookup, domain lookup |
| `PROXY_FEEDS` / `PROXY_FIREHOSE`                | Proxy snapshots / live stream                   |
| `ANONYMIZERS_FEED` / `ANONYMIZERS_STREAM`       | Anonymizer snapshots / live stream              |
| `TORRENTS_FEED` / `TORRENTS_STREAM`             | Torrent snapshots / live stream                 |
| `HONEYPOT_HTTP_FEED` / `HONEYPOT_HTTP_STREAM`   | HTTP honeypot snapshots / stream                |
| `HONEYPOT_HTTPS_FEED` / `HONEYPOT_HTTPS_STREAM` | HTTPS/TLS honeypot snapshots / stream           |
| `HONEYPOT_DNS_FEED` / `HONEYPOT_DNS_STREAM`     | DNS honeypot snapshots / stream                 |
| `HONEYPOT_ADB_FEED` / `HONEYPOT_ADB_STREAM`     | ADB honeypot snapshots / stream                 |

## IP & domain intelligence

`lookup` is the workhorse. Give it one IP, several, or pipe a list on stdin. `lookup` and `lookup ip` are the same command.

```bash
synthient lookup "8.8.8.8"
synthient lookup "8.8.8.8" "1.1.1.1" "9.9.9.9" --format json
printf "8.8.8.8\n1.1.1.1\n" | synthient lookup --format json
```

**Demo:** `synthient lookup 8.8.8.8` — A single IP rendered as a readable report, then the same data as JSON for piping into jq or a pipeline.

It composes naturally with the rest of your shell: read an access log, dedupe, and write enriched CSV:

```bash
awk '{print $1}' access.log | sort -u \
  | synthient lookup --format csv --output ip-intel.csv
```

Domain intelligence comes from Helios observations via the `domain` subcommand:

```bash
synthient lookup domain "example.com"
synthient lookup domain "example.com" --format json | jq .
```

## Feed snapshots

Feeds are point-in-time Parquet snapshots of each data surface. Start by listing the streams and their snapshots:

```bash
synthient feeds streams
synthient feeds snapshots proxies --limit 25
```

**Demo:** `synthient feeds snapshots proxies --limit 10` — Browse available daily and hourly snapshots for a stream, then inspect a snapshot's metadata and Parquet schema before downloading anything.

| Stream           | Aliases                        | Description                                                   |
| ---------------- | ------------------------------ | ------------------------------------------------------------- |
| `proxies`        | `proxy`                        | Proxy IPs across residential, datacenter, and mobile networks |
| `anonymizers`    | `anonymizer`                   | VPN, Tor, private relay, and other anonymizer ranges          |
| `torrents`       | `torrent`                      | DHT and tracker peer sightings                                |
| `honeypot_http`  | `helios_http`, `http`          | HTTP request captures from Helios sensors                     |
| `honeypot_https` | `helios_https`, `https`, `tls` | TLS ClientHello captures from Helios sensors                  |
| `honeypot_dns`   | `helios_dns`, `dns`            | DNS observations from Helios tunnels (snapshots only)         |
| `honeypot_adb`   | `helios_adb`, `adb`            | ADB shell commands captured by Helios (snapshots only)        |

Snapshots are addressed by `latest`, a date, or a date and hour:

```txt
latest
YYYY-MM-DD
YYYY-MM-DD/HH
```

For reproducible jobs, resolve a concrete id instead of hard-coding `latest`, then inspect it:

```bash
SNAPSHOT=$(synthient feeds snapshots proxies --limit 1 --format json | jq -r '.feeds[0].id')
synthient feeds meta proxies "$SNAPSHOT"      # metadata + schema
synthient feeds schema proxies "$SNAPSHOT"    # schema only
synthient feeds checksum proxies "$SNAPSHOT"  # expected SHA-256
```

Large result sets paginate with a cursor:

```bash
PAGE=$(synthient feeds snapshots proxies --limit 25 --format json)
CURSOR=$(jq -r '.next_cursor // empty' <<<"$PAGE")
synthient feeds snapshots proxies --cursor "$CURSOR" --limit 25
```

## Downloading snapshots

`feeds download` is the explicit form: it takes a stream, a snapshot id, and a destination that must end in `.parquet`. With `--verify` it checks the file against the snapshot's checksum; without `--force` it won't overwrite. Interactive terminals get a determinate progress bar with size, rate, elapsed time, and percentage.

```bash
synthient feeds download proxies "$SNAPSHOT" proxies.parquet --verify --force
```

**Demo:** `synthient feeds download proxies latest proxies.parquet --verify` — A snapshot downloads with a live progress bar, then verifies against its published SHA-256 checksum before the command exits.

`synthient download` is a shorter wrapper for one-off pulls. Its date-based forms avoid resolving an id by hand:

```bash
synthient download proxies proxies.parquet --date 2026-06-02
synthient download proxies proxies.parquet --date 2026-06-03 --hour 0
```

| Flag                              | Purpose                                           |
| --------------------------------- | ------------------------------------------------- |
| `--date YYYY-MM-DD\|latest`, `-d` | Snapshot date for the wrapper command             |
| `--hour 0-23`                     | UTC hour for an hourly snapshot                   |
| `--force`                         | Overwrite an existing `.parquet` file             |
| `--verify`                        | Verify the download against the snapshot checksum |
| `--silent`, `-s`                  | Suppress download output                          |
| `--no-preflight`                  | Skip the feed scope preflight                     |

> **Note**: Prefer the explicit `feeds download` in scripts that already resolved a snapshot id; it's unambiguous about exactly which snapshot you're pulling.

## Live streams

Where snapshots are frozen, `stream` is the firehose: newline-delimited JSON straight from the live feed endpoints. It deliberately has no `--format`: the output is always NDJSON so it pipes cleanly into `jq`, log processors, and queue producers.

```bash
synthient stream proxies
```

**Demo:** `synthient stream proxies --filter type=RESIDENTIAL_PROXY --duration 5s` — Live residential-proxy observations stream in as NDJSON, bounded by a duration limit and narrowed by a filter.

Bound a run by event count or wall-clock time, and reconnect automatically if the server closes the stream:

```bash
synthient stream proxies --filter type=RESIDENTIAL_PROXY --max-events 250 --output proxies.ndjson
synthient stream proxies --filter type=RESIDENTIAL_PROXY --duration 5s
synthient stream proxies --reconnect --output proxies.ndjson
```

Filters are `field=value`, repeatable (all must match), and reach nested fields with dot notation. They are applied client-side after each event arrives, so a filtered run still receives the full stream. Use `--pretty` only for eyeballing output locally:

```bash
synthient stream proxies \
  --filter type=RESIDENTIAL_PROXY \
  --filter country_code=US \
  --filter asn=15169 \
  --duration 30s

synthient stream proxies --max-events 3 --pretty
```

Because it's NDJSON, summarizing a sample is a one-liner:

```bash
synthient stream proxies --filter type=RESIDENTIAL_PROXY --duration 5s \
  | jq -r '[.timestamp, .ip, .country_code, .provider] | @tsv'
```

## gRPC schema introspection

`grpc schema` uses gRPC reflection to dump protobuf descriptors: request everything, or drill into a specific service or method.

```bash
synthient grpc schema
synthient grpc schema synthient.v1.SynthientService
synthient grpc schema synthient.v1.SynthientService.StreamProxies
```

**Demo:** `synthient grpc schema synthient.v1.SynthientService` — Resolve a service's protobuf descriptors over reflection and print them as text, JSON, or a binary FileDescriptorSet for downstream tooling.

Write the schema out as JSON or a binary `FileDescriptorSet`, and point at a custom or local plaintext endpoint:

```bash
synthient grpc schema synthient.v1.SynthientService --format json --output synthient-schema.json
synthient grpc schema synthient.v1.SynthientService --format binpb --output synthient.protoset
synthient grpc schema --endpoint 127.0.0.1:50051 --plaintext
```

| Flag                               | Purpose                                       |
| ---------------------------------- | --------------------------------------------- |
| `--format text\|json\|binpb`, `-f` | Output representation                         |
| `--output -\|file`, `-o`           | Destination                                   |
| `--endpoint <host:port>`           | Override the configured gRPC endpoint         |
| `--timeout <duration>`             | Reflection timeout, default `15s`             |
| `--plaintext`                      | Connect without TLS                           |
| `--include-reflection`             | Include gRPC reflection descriptors in output |

## MCP server

`synthient mcp` runs a [Model Context Protocol](https://modelcontextprotocol.io) server over stdio, exposing the same lookups, feed metadata, and schemas as tools for MCP-compatible clients. It authenticates with the usual credential order and exits at startup if no key is found. The only flag is `--transport`, which currently accepts `stdio`.

```bash
synthient mcp
```

The [MCP server](https://docs.synthient.com/ai/mcp) page covers the tools it exposes and how to register it with a client. Plugins for [Claude Code](https://docs.synthient.com/ai/claude) and [Codex](https://docs.synthient.com/ai/codex) bundle it alongside skills for integrating and migrating.

## Output, color & quiet

The same `--format` / `--output` pair works across the finite read commands:

```bash
synthient status --format json
synthient account --format csv --output account.csv
synthient feeds snapshots proxies --format csv --output snapshots.csv
```

Color disables itself when output isn't a terminal, and you can force it off; `--quiet` suppresses human-oriented progress where it appears:

```bash
synthient --no-color status      # or: NO_COLOR=1 synthient status
synthient --quiet feeds download proxies "$SNAPSHOT" proxies.parquet --force
```

## Configuration & global flags

No config file is required; the production API, feed, and gRPC endpoints ship with the binary. Add a config file only for custom endpoints or named profiles:

```toml
# ~/.config/synthient/config.toml
[endpoints]
base_api = "https://api.synthient.com/api/v4"
base_feeds = "https://api.synthient.com/api/v4"
base_grpc = "grpc.synthient.com:443"

[profiles.staging.endpoints]
base_api = "https://staging-api.example.com/api/v4"
base_feeds = "https://staging-api.example.com/api/v4"
base_grpc = "staging-grpc.example.com:443"
```

```bash
synthient --profile staging status   # apply a named profile
synthient --config ./config.toml status
```

| Global flag        | Purpose                                           |
| ------------------ | ------------------------------------------------- |
| `--config <path>`  | Read configuration from a non-default TOML file   |
| `--profile <name>` | Apply endpoint overrides from `[profiles.<name>]` |
| `--no-color`       | Disable ANSI styling                              |
| `--quiet`, `-q`    | Suppress human progress output where supported    |
| `--version`, `-v`  | Print CLI version                                 |

## Shell completion

Generate completion scripts through Cobra for your shell:

```bash
synthient completion zsh > "${fpath[1]}/_synthient"
synthient completion bash > /usr/local/etc/bash_completion.d/synthient
synthient completion fish > ~/.config/fish/completions/synthient.fish
```

## Troubleshooting

**No credentials found.** Set `SYNTHIENT_API_KEY`, add it to a `.env`, or run `synthient auth`.

**Colors are missing.** Check `NO_COLOR`, `--no-color`, your terminal type, and whether output is redirected.

**Download refuses to overwrite.** Pass `--force` or choose a new `.parquet` filename.

**Download progress is hidden.** Progress only renders for interactive terminals; redirected output and `--quiet` are non-interactive.

**Missing feed or stream access.** Run `synthient scopes` and compare the required scope. Use `--no-preflight` only when you intentionally skip the account check.

**Snapshot lookup fails.** List snapshots first and use the returned id:

```bash
SNAPSHOT=$(synthient feeds snapshots <stream> --limit 1 --format json | jq -r '.feeds[0].id')
```

**gRPC schema connection fails.** Check the endpoint, TLS mode, and timeout. Use `--plaintext` only for local or explicitly plaintext reflection servers.