The CLI
Six work verbs plus a handful of utility commands, value-first positionals, structural routing, deterministic everything. This page is the design rationale; the docs are the full reference.
$ npm install -g contactctl
01 — The surface
This is the actual --help output. If a capability is not here, the product does not have it — the surface is deliberately small enough to hold in your head.
contactctl 0.1.0 — CLI for AI agents to find, verify, and enrich B2B contacts.
Aliases: contactctl, ctc
Single lookup
ctc verify <email> deliverability of one email [0.02 credits]
ctc whois <email> reverse email lookup -> person + company profile [1 credit]
ctc find <full name> <domain|company> work email for a person at a company [1 credit]
(--personal: personal email instead [3 credits])
ctc find <linkedin_url> work email from a LinkedIn profile [1 credit]
ctc phone <full name> <domain|company> mobile phone [10 credits]
Bulk lookup (csv/tsv in, csv out; row order preserved)
ctc verify <file.csv> [out.csv] batch verify [0.02 credits/row]
ctc whois <file.csv> [out.csv] batch reverse lookup [1 credit/row found]
ctc find <file.csv> <out.csv> batch work email [1 credit/row found]
ctc phone <file.csv> <out.csv> batch phone [10 credits/row found]
Search & lookalikes
ctc search people --domain D [...] people at a named company [0.25 credits/search]
ctc search companies --industry I [...] companies by attributes [0.25 credits/search]
ctc lookalike <domain> similar companies [0.35 credits/row]
ctc lookalike <linkedin_url> similar people [0.35 credits/row]
Helpers (free, no network)
ctc search filters [<field>] list search filter fields / a field's accepted values
ctc lookalike filters list lookalike filter fields
Utility
ctc instructions agent usage guide
ctc usage credit balance and recent spend
ctc auth [<api_key>] | ctc auth status connect / show account
ctc version [--json]
Universal flags
--json deterministic JSON output (every command)
--estimate print the credit cost of the action and exit (no spend)
--help detailed usage for any commandPer-command syntax, batch rules, and JSON shapes: full documentation
02 — Design decisions
01
The thing you know goes straight into the command: a name, a domain, an email, a URL, a file. No --first-name/--last-name ceremony, no subcommand trees to memorize.
Flags exist only for behavior — output format, cost caps, timeouts — never for the data itself. The result reads like a sentence and types like one.
02
The CLI routes each positional on its shape: an email regex, a URL, a dot-without-spaces (domain), or plain text. It never interprets natural language and never asks a model what you meant.
Deterministic routing means the same command line always does the same thing — the property that lets an agent compose commands without trial runs.
03
--json produces stable shapes on every command, versioned through version --json. Exit codes carry the verdict: 0 found, 2 not found, 4 budget cap, 9 timeout.
A script can branch on $? without parsing anything; an agent can parse JSON without screen-scraping prose.
04
ctc instructions prints the complete operating guide — routing rules, batch behavior, costs, exit codes — in roughly 60 lines. An agent reads it once per session and needs nothing else.
Until that read happens, the tool costs zero context. There is no resident schema, no tool manifest, no prompt overhead.
03 — Why CLI-first
Contact-data products are built as dashboards because buyers are humans. But the work is increasingly done by agents — and an agent cannot click. Every GUI feature becomes a detour: export queues instead of stdout, column-mapping wizards instead of CSV conventions, notification emails instead of exit codes.
A CLI inverts all of it. The interface is text, which is what agents are made of. State
lives in files, which agents can version, diff, and re-run. Composition is free — pipes,
cron, CI, Make — instead of waiting for a vendor integration. And capability discovery is --help, not a training video.
This is also why ContactCTL ships as a native binary rather than an MCP server: instant startup, zero standing context cost, and nothing between the agent and the work. The full comparison is on the MCP page; how it plugs into specific stacks is on integrations.