The official CLI for Encrata.
Built for email intelligence lookups, validation workflows, async bulk jobs, contact list management, automation scripts, and local developer testing.
irm https://raw.githubusercontent.com/Encratahq/encrata-cli/main/install.ps1 | iexInstall a specific version:
& ([scriptblock]::Create((irm https://raw.githubusercontent.com/Encratahq/encrata-cli/main/install.ps1))) -Version 0.4.7brew tap Encratahq/tap
brew install encrataOr:
brew install Encratahq/tap/encratanpm install -g encrata-cliDownload a binary from the GitHub releases page:
https://github.com/Encratahq/encrata-cli/releases
Windows users can download a windows_amd64.zip or windows_arm64.zip asset,
extract it, and run encrata.exe.
# Verify the install
encrata version
# Save your API key
encrata config set-key YOUR_API_KEY
# Run your first lookup
encrata email validity jane@acme.com
# Get the full API response
encrata email validity jane@acme.com --jsonFastest path — login saves your key and verifies it:
encrata login enc_live_xxxxxxxx # or just: encrata login (prompts)
encrata whoami # confirm account, plan, credits, workspace
encrata logout # clear the saved keyThe CLI resolves your API key using this priority chain:
| Priority | Source | How to set |
|---|---|---|
| 1 | --api-key flag |
encrata email validity jane@acme.com --api-key YOUR_API_KEY |
| 2 | ENCRATA_API_KEY env var |
export ENCRATA_API_KEY=YOUR_API_KEY |
| 3 | Config file | encrata login YOUR_API_KEY (or config set-key) |
If no key is found, protected commands return an API key error.
Config is saved to ~/.encrata/config.yaml (written 0600).
| Command | Description |
|---|---|
login [api-key] |
Save the key and verify it against the API (prompts if omitted) |
logout |
Clear the saved key (the ENCRATA_API_KEY env var still applies) |
whoami |
Show the authenticated email, plan, remaining credits, role, and active workspace |
Behavior is consistent across every command:
| Situation | Output |
|---|---|
| Single lookup | Human-readable card (key/value) on stdout |
Bulk (--bulk) |
Progress bar + summary counts (not a per-row dump) |
--json |
Raw API JSON on stdout (full rows for bulk) |
--out file |
Results written to .csv / .xlsx / .json |
| Errors & notices | stderr (so stdout stays pipe-clean) |
Global flags (all commands): --json, --api-key, --base-url, --quiet,
--no-color (honors NO_COLOR), --timeout <secs>. The spinner auto-disables
when output is not a terminal.
| Code | Meaning |
|---|---|
0 |
Success (or a finding when --fail-on-finding is not set) |
1 |
Operational error (bad usage, network, or server) |
2 |
A finding was detected — breach/leak — only with --fail-on-finding |
3 |
Authentication failed |
4 |
Insufficient credits |
Save your API key locally.
encrata config set-key YOUR_API_KEYUse a custom API server, for example a local backend.
encrata config set-url http://localhost:8080Show the current CLI configuration.
encrata config showClear a saved value and revert it to its default.
encrata config unset api-key # remove the saved key
encrata config unset base-url # revert to the default API URL
encrata config unset output # revert to table output| Flag | Description |
|---|---|
--json |
Print raw JSON output |
--api-key |
Override the saved API key |
--base-url |
Override the saved API base URL |
--quiet |
Suppress decorative output (headers, spinner); results still print |
--no-color |
Disable colored output (also honors the NO_COLOR env var) |
--timeout |
Per-request timeout in seconds (0 = default 90s) |
Environment variables: ENCRATA_API_KEY, ENCRATA_BASE_URL, and NO_COLOR
are all honored. The config file (~/.encrata/config.yaml) is written with
0600 permissions since it stores the API key. The spinner auto-disables when
output is not a terminal.
Use help to discover commands, flags, and examples from the terminal.
encrata help
encrata --help
encrata COMMAND --help
encrata COMMAND SUBCOMMAND --helpExamples:
encrata email --help
encrata email bulk --help
encrata jobs --help
encrata keys --help
encrata webhooks --help
encrata workspace --help
encrata lists --help
encrata workflows --helpPrint the installed CLI version.
encrata versionUpdate the CLI binary to the latest GitHub release.
encrata update| Command | Use it for | Credits |
|---|---|---|
email validity |
Deliverability verdict (valid/invalid/catch-all/risky) + full report | 1/email |
email identity |
The person — name, role, company, socials, breaches | 1000/email |
email breaches |
Data-breach exposure for an address | 1/email |
email compliance |
Whether you may cold-email an address, and under whose law | 1/email |
email bulk |
Validate a whole file/list (= email validity --bulk) |
1/email |
API endpoint family: these commands now target /api/cli/email/* paths (/api/cli/email/validity, /api/cli/email/identity, /api/cli/email/breaches, /api/cli/email/compliance, /api/cli/email/validity/bulk) rather than legacy /api/agent/* aliases.
Every verb runs on one address, or on a file/STDIN list with --bulk.
Check whether a single email address is valid and deliverable. Returns
valid / invalid / catch-all / risky plus confidence, domain trust,
disposable/role flags, provider and SMTP detail.
encrata email validity jane@acme.com
encrata email validity jane@acme.com --json
# Validate a whole file (or STDIN) — same engine as `email bulk`
encrata email validity emails.csv --bulk
encrata email validity emails.csv --bulk --out results.csv --only validBulk mode (--bulk) is the uniform spelling of email bulk and takes the same
flags: --out, --format, --only valid|invalid|found, --stream, --job,
--enrich, --concurrency, --columns.
Resolve the identity and social profiles behind an email address. Pass a single
email, or use --bulk with a file (or - for STDIN) to resolve a whole list
concurrently.
# Single email
encrata email identity jane@acme.com
encrata email identity jane@acme.com --json
# Bulk from a file (or STDIN)
encrata email identity emails.csv --bulk
encrata email identity emails.csv --bulk --concurrency 16 --out people.csv
encrata email identity emails.csv --bulk --only found --out people.xlsxBulk options: --bulk, --concurrency (default 8), --out (.csv/.xlsx/.json),
--format, --only found. Bulk exports flatten to email, found, name,
company, job_role, location; --format json writes the raw objects. For
very large lists, prefer the async jobs --type identity surface.
Check whether an email appears in known data breaches. Pass a single email to
check it, or use --bulk with a CSV/text file (or - for STDIN) to stream a
whole list with a live progress bar.
# Single email
encrata email breaches jane@acme.com
encrata email breaches jane@acme.com --json
# Bulk from a file (or STDIN)
encrata email breaches emails.csv --bulk
cat emails.csv | encrata email breaches - --bulk
# Bulk with an export
encrata email breaches emails.csv --bulk --out breaches.csv
encrata email breaches emails.csv --bulk --out breaches.xlsx
encrata email breaches emails.csv --bulk --format jsonOptions:
| Flag | Description |
|---|---|
--full |
Show exposed data and registered services (single-email mode) |
--bulk |
Check a file (or - for STDIN) of emails via streaming |
--out |
Write bulk results to a file (.csv, .xlsx, or .json) |
--format |
Bulk export format: csv, xlsx, or json (default: inferred from --out) |
--only |
Export only matching rows: breached |
--fail-on-finding |
Exit with code 2 if any email is breached (otherwise exit 0) |
--json |
Print raw JSON output |
Bulk exports flatten each row to email, breached, breach_count, and
breaches (a |-joined list of breach names); --format json writes the raw,
nested result objects instead.
Exit codes (usable as a CI / sign-up guard, mirroring encrata password):
| Code | Meaning |
|---|---|
0 |
Success — or a breach was found but --fail-on-finding was not set |
1 |
Operational error (network, validation, or server) |
2 |
A breach was found (only with --fail-on-finding) |
3 |
Authentication failed |
4 |
Insufficient credits |
Answer whether you may cold-email an address, and under whose law. Returns the
governing jurisdiction, its rule, the main laws and restrictions, and how much to
trust the attribution (confident / medium / unknown).
The verdict can arrive in two phases: some signals resolve inside the request and one may finish afterwards. The printed message reflects whether the answer is provisional, confident, or unknown, so render it as shown.
encrata email compliance jane@acme.com
encrata email compliance jane@acme.com --json
encrata email compliance jane@acme.com --out compliance.json| Flag | Description |
|---|---|
--out |
Write the full JSON result to a file |
--json |
Print raw JSON output |
Check whether a password has appeared in known data breaches (HIBP k-anonymity). Your password is hashed locally with SHA-1 and only the hash is sent — the plaintext never leaves your machine and is never logged, cached, or stored.
API endpoint family: these commands target /api/cli/email/password/breaches and
/api/cli/email/password/breaches/bulk.
# Prompt interactively (no echo — never lands in shell history)
encrata password
# Pass a password as an argument
encrata password 'hunter2'
# Bulk-check a file (one password per line, de-duplicated, max 1000)
encrata password --file passwords.txt
# Bulk-check from STDIN
cat passwords.txt | encrata password --stdin
# Raw JSON output
encrata password 'hunter2' --jsonOptions:
| Flag | Description |
|---|---|
--file |
Check passwords from a file (one per line) |
--stdin |
Read passwords from STDIN (one per line) |
--fail-on-finding |
Exit with code 2 if any password is breached (otherwise exit 0) |
--json |
Print raw JSON output (defaults to a formatted table) |
Pricing: 1 credit per unique password (single = 1; bulk = number of unique hashes).
Exit codes (usable as a CI / sign-up guard):
| Code | Meaning |
|---|---|
0 |
Success — or a breach was found but --fail-on-finding was not set |
1 |
Operational error (network, validation, or server) |
2 |
A breach was found (only with --fail-on-finding) |
3 |
Authentication failed |
4 |
Insufficient credits |
Scan a GitHub repository for committed secrets and credentials. scan starts a
scan; get fetches a previous scan's result by its ID.
By default only the current checkout is scanned and the result comes back inline.
Use --deep to walk the full commit history: a deep scan runs in the background
and returns a scan ID whose result you fetch later with breaches github get.
# Scan the current checkout inline
encrata breaches github scan https://github.com/org/repo
# Deep (full-history) scan runs in the background, returns a scan ID
encrata breaches github scan https://github.com/org/repo --deep
# Target a branch/tag/commit and filter by severity
encrata breaches github scan https://github.com/org/repo --ref main --min-severity high
# Fetch a background scan's result later
encrata breaches github get scn_abc123| Flag | Description |
|---|---|
--deep |
Scan the full commit history (runs in the background) |
--ref |
Branch, tag, or commit to scan |
--min-severity |
Only report findings at or above low, medium, high, or critical |
--fail-on-finding |
Exit with code 2 if any secret is found |
--out |
Write the full JSON result to a file |
--json |
Print raw JSON output |
Exit codes mirror encrata password and email breaches: 0 success (or a
finding without --fail-on-finding), 1 operational error, 2 a secret was
found (with --fail-on-finding), 3 auth, 4 credits.
Validate a batch of emails from a CSV/text file or STDIN. Small batches stream
live results over the terminal with a progress bar; large batches (or --job)
run as an async job that is polled to completion.
By default, bulk validation uses the lean, high-throughput path and returns
email, status, and reason per row. Add --enrich to run the full
per-email report instead, so every export column (provider, mx, trust grade,
breaches, etc.) is populated — the same data as email validity --full.
encrata email bulk emails.csv
encrata email bulk emails.csv --out results.csv
encrata email bulk emails.csv --enrich --out results.csv
encrata email bulk emails.csv --enrich --concurrency 16 --only valid --out valid.csv
encrata email bulk emails.csv --out results.xlsx --columns email,status,trust_grade
encrata email bulk emails.csv --job --out results.json --format json
cat emails.csv | encrata email bulk - --stream
email bulk emails.csvandemail validity emails.csv --bulkare equivalent — same engine and flags. Use whichever reads better.
Options:
| Flag | Description |
|---|---|
--stream |
Force live streaming (SSE) mode |
--job |
Run as an async job and wait here (same engine as jobs; use jobs to start one and return later) |
--enrich |
Fill every export column with the full per-email report (same 1 credit/email, just slower) |
--concurrency |
Parallel lookups when --enrich is set (default 8) |
--out |
Write results to a file (.csv, .xlsx, or .json) |
--format |
Export format: csv, xlsx, or json (default: inferred from --out) |
--columns |
Subset of columns to export (email, status, reason always included) |
--only |
Export only matching rows: valid, invalid, or found |
Batches larger than 1,000 emails automatically switch to job mode unless
--stream is set (the CLI prints a notice when it does). Both paths bill 1
credit per successful unique email - the difference is speed vs detail: the lean
default returns email, status, reason fast, while --enrich runs the full
per-email report (all columns) and is slower.
CSV and XLSX exports flatten each result into a fixed, ordered column set.
Booleans render as yes/no and lists join with |. email, status and
reason are always present; the rest are empty when not returned:
email, status, reason, message, confidence, disposable, role, role_name,
free_provider, provider, did_you_mean, canonical, domain, mx, smtp_mx_host,
smtp_catch_all, smtp_greylisted, trust_grade, spf, dmarc, dmarc_policy, dkim,
mta_sts, tls_rpt, bimi, dnssec, person_signal_count, person_signal_sources,
registrar, domain_created_at, domain_age_days, breaches_count, gravatar,
registered_services, google_account, checked_at
Use --columns email,status,trust_grade to pick a subset. --format json
writes the raw, nested result objects (unflattened) instead of a flat table.
Manage asynchronous jobs for large inputs the backend processes in the
background. One namespace, three job types selected with --type
(validity is the default; also identity and password).
# Validity (default) — from a file or STDIN
encrata jobs create emails.csv
encrata jobs list
encrata jobs status JOB_ID
encrata jobs results JOB_ID --status invalid
encrata jobs download JOB_ID --format csv --out results.csv
encrata jobs cancel JOB_ID
encrata jobs retry JOB_ID
# Identity — same verbs, add --type identity
encrata jobs create emails.csv --type identity
encrata jobs results JOB_ID --type identity --found-only
encrata jobs download JOB_ID --type identity --out people.csv
# Password — hashes only, never plaintext
encrata jobs create --type password --sha1-file hashes.txt
encrata jobs create --type password --password-file passwords.txt # hashed locally
encrata jobs results JOB_ID --type password --breachedEvery verb (create, list, status, results, download, cancel,
retry) accepts --type validity|identity|password.
Options:
| Command | Flag | Description |
|---|---|---|
| all | --type |
Job type: validity (default), identity, password |
create (password) |
--sha1s / --sha1-file / --password-file |
Hash sources (plaintext hashed locally, never sent) |
create |
--file-name |
Optional display name |
results |
--status |
Validity: filter by per-row status |
results |
--page / --page-size |
Pagination |
results |
--only |
Keep only matching rows: valid, invalid, found, or breached |
download |
--format |
Validity: csv, xlsx, or json |
download |
--only |
Keep only matching rows: valid, invalid, found, or breached |
download |
--out |
Write to a file instead of stdout |
retry |
Re-drive dead-lettered chunks (validity/identity; password has no retry) |
--onlyis the single row filter acrossemail bulk,email breaches, andjobs. The older--valid-only/--found-only/--breachedflags still work as hidden aliases.
Note:
jobs <verb> --typeis the single async-job surface. The former standaloneidentity-jobs/password-jobsgroups and the MCP-style names (bulk-validate-emails,get-email-job-status, …) have been removed.
Run a saved workflow against a CSV, TXT, or XLSX file, track the run, and download the resulting enriched CSV. The workflow itself is created and configured in the Encrata app; the CLI provides the bulk execution flow.
# 1. Upload source emails and copy the returned file ID
encrata workflows upload emails.xlsx
# 2. Start the saved workflow over that file
encrata workflows run WORKFLOW_ID --file FILE_ID
# 3. Check progress, then download the completed CSV
encrata workflows status RUN_ID
encrata workflows download RUN_ID --out enriched-results.csv
# Manage or filter workflow runs
encrata workflows runs --workflow-id WORKFLOW_ID
encrata workflows cancel RUN_ID --yesSubcommands:
| Command | Description |
|---|---|
upload <file> |
Upload a CSV, TXT, or XLSX input file; --workflow-id optionally associates it with a workflow. |
run <workflow-id> |
Start a bulk run; requires --file <file-id>. |
status <run-id> |
Show the run state, credit use, output rows, and step results. |
runs |
List runs; use --workflow-id, --limit, and --offset to filter or paginate. |
cancel <run-id> |
Request cooperative cancellation; add --yes to skip the prompt. |
download <run-id> |
Save the run's generated CSV; --out defaults to run-<id>.csv. |
integrations (int) |
Manage connected destinations such as Google Sheets, HubSpot, and Salesforce. |
For connected export destinations:
encrata workflows integrations providers
encrata workflows integrations list
encrata workflows integrations create-sheet INTEGRATION_ID --title "Enriched leads"
encrata workflows integrations disconnect INTEGRATION_ID --yesUse encrata workflows integrations session --json to retrieve the short-lived
Nango Connect session token for a browser-based connection flow, then save the
completed connection with integrations save --connection-id ... --provider-config-key ....
Manage reusable contact lists — named collections of emails you can share across enrichment and monitoring workflows.
API endpoint family: these commands target /api/cli/lists*.
encrata lists list
encrata lists create "Prospects" --emails a@example.com --emails b@example.com
encrata lists create "Q3 Leads" --file emails.csv
encrata lists get LIST_ID
encrata lists emails LIST_ID
encrata lists add LIST_ID --emails new@example.com
encrata lists remove LIST_ID --emails old@example.com
encrata lists delete LIST_IDSubcommands:
| Command | Aliases | Description |
|---|---|---|
list |
ls |
List all contact lists |
create |
Create a list, optionally seeding emails | |
get |
show |
Show a list's details |
emails |
List every email in a list | |
add |
Add emails to a list | |
remove |
rm-emails |
Remove emails from a list |
delete |
rm, del |
Delete a list permanently |
Options:
| Command | Flag | Description |
|---|---|---|
create |
--emails |
Initial email addresses (repeatable) |
create |
--file |
Read initial emails from a file |
add |
--emails / --file |
Emails to add |
remove |
--emails / --file |
Emails to remove |
Create, list, rename, enable/disable, cap, and revoke API keys.
encrata keys ls
encrata keys create "CI key"
encrata keys rename KEY_ID "Prod key"
encrata keys enable KEY_ID
encrata keys disable KEY_ID
encrata keys limit KEY_ID --credits 5000
encrata keys limit KEY_ID --unlimited
encrata keys revoke KEY_ID
encrata keys revoke KEY_ID --permanentSubcommands:
| Command | Description |
|---|---|
ls |
List API keys with ID, name, prefix, status, credits used, and limit |
create |
Create a new API key (the full key is shown once) |
rename |
Rename a key: keys rename <id> <new-name> |
enable |
Re-enable a disabled key |
disable |
Disable a key without deleting it (reversible with enable) |
limit |
Set (--credits <N>) or clear (--unlimited) a key's credit cap |
revoke |
Disable a key; add --permanent to delete it for good |
Options:
| Command | Flag | Description |
|---|---|---|
limit |
--credits |
Credit cap for the key (must be >= 0) |
limit |
--unlimited |
Remove the credit cap (unlimited usage) |
revoke |
--permanent |
Permanently delete the key instead of disabling it |
Register HTTPS endpoints that receive real-time event notifications from your workspace. Deliveries are signed with HMAC-SHA256 so your receiver can verify them.
encrata webhooks create https://example.com/hook --events lookup.completed,credits.low
encrata webhooks list
encrata webhooks update WEBHOOK_ID --disable
encrata webhooks test WEBHOOK_ID
encrata webhooks deliveries WEBHOOK_ID --limit 20
encrata webhooks delete WEBHOOK_IDSubcommands: list, create, update, delete, test, deliveries.
Valid event types:
lookup.completed, apikey.created, apikey.revoked, credits.low, credits.exhausted
Options:
| Command | Flag | Description |
|---|---|---|
create |
--events |
Events to subscribe to (comma-separated, required) |
create |
--description |
Optional description |
update |
--url |
New HTTPS endpoint URL |
update |
--events |
Replace subscribed events (comma-separated) |
update |
--description |
New description |
update |
--enable / --disable |
Activate or deactivate the webhook |
delete |
--yes |
Skip the confirmation prompt |
deliveries |
--limit |
Maximum deliveries to show (default 20) |
create returns the signing secret once — store it as ENCRATA_WEBHOOK_SECRET
in your receiver to verify the X-Encrata-Signature header. URLs must use HTTPS.
Managing webhooks requires a selected workspace.
Manage workspaces and their members (alias: ws). Member, update, and
delete operations act on your current (active) workspace, which is tracked
server-side — run workspace switch <id> first to change it.
Workspace commands call the CLI workspace namespace: /api/cli/workspaces*.
encrata workspace list
encrata workspace create "Acme Inc" --slug acme
encrata workspace switch WORKSPACE_ID
encrata workspace update --name "Acme Corp" --slug acme
encrata workspace delete # deletes the CURRENT workspace (admin only)
encrata workspace members
encrata workspace members invite teammate@acme.com --role tech
encrata workspace members set-role MEMBER_ID --role admin
encrata workspace members remove MEMBER_IDSubcommands: list, create, switch, update, delete, and
members (list, invite, set-role, remove).
Valid member roles: admin, tech, readonly (the creator is the owner).
Options:
| Command | Flag | Description |
|---|---|---|
create |
--slug |
Custom slug (auto-generated when omitted) |
create |
--logo-url |
Logo URL |
update |
--name |
New name (required) |
update |
--slug |
New slug (regenerated from name if omitted) |
update |
--logo-url |
New logo URL |
update |
--id |
Target workspace ID (defaults to current) |
delete |
--yes |
Skip the confirmation prompt |
members invite |
--role |
admin, tech, or readonly (default readonly) |
members set-role |
--role |
New role for the member |
members remove |
--yes |
Skip the confirmation prompt |
update, delete, and member changes are admin-only and always target your
active workspace. Destructive actions (delete, members remove) confirm first
unless --yes.
The
workspacecommand is also available asws— e.g.ws list,ws switch <id>,ws members list.
Generate a completion script for your shell:
encrata completion bash > /etc/bash_completion.d/encrata
encrata completion zsh > "${fpath[1]}/_encrata"
encrata completion fish > ~/.config/fish/completions/encrata.fish
encrata completion powershell | Out-String | Invoke-ExpressionRun encrata completion --help for shell-specific install instructions.
Billing is 1 credit per successful unique email. Duplicate emails are de-duplicated, and invalid or failed checks are not charged.
| Command | Credits |
|---|---|
email validity |
1 credit per successful email |
email identity |
1 credit per successful email |
email breaches |
1 credit per successful email (single or --bulk) |
email bulk |
1 credit per successful unique email |
jobs (validity / identity) |
1 credit per successful unique email |
jobs --type password |
1 credit per unique password hash |
lists |
Free — list management does not consume credits |
keys |
Free — key management does not consume credits |
webhooks |
Free — webhook management does not consume credits |
workspace |
Free — workspace management does not consume credits |
Use this when you want to change the CLI and run your local build.
- Go 1.25.4+
- An Encrata API key
- Optional: a local Encrata backend running on
http://localhost:8080
- Clone the repo.
git clone https://github.com/Encratahq/encrata-cli.git
cd encrata-cli- Run tests.
go test ./...- Run the CLI locally.
go run . version
go run . email validity jane@acme.com- Point local runs at a local backend.
$env:ENCRATA_BASE_URL = "http://localhost:8080"
go run . email validity jane@acme.comgo build -o encrata .On Windows:
go build -o encrata.exe .Output: ./encrata or ./encrata.exe.
- Documentation: https://docs.encrata.com/cli
- API Reference: https://docs.encrata.com/api-reference
- Dashboard: https://encrata.com
- Releases: https://github.com/Encratahq/encrata-cli/releases
MIT