a.
Node.js 18 or newer
The CLI ships as an npm package with prebuilt binaries for macOS, Linux, and Windows — Node is only the installer.
node --version # v18.0.0 or newer
Empty shell to first
contact, in five commands.
Every block on this page is copy-paste exact. Run it yourself, or scroll to the hand-off block and let your agent run the whole thing for you.
Show me the commands
npm install · auth · status · first lookup. About three minutes.
Two things first,
nothing exotic.
If you have a recent Node and a key from your dashboard, you are ready to install.
b.
An API key
Subscribe on the pricing page, then copy the key from your dashboard. It is shown once and looks like ctc_live_….
Install, authenticate,
find your first contact.
Two commands install it, the third proves it worked, the last two find your first contact.
1
Install the package globally
One package, two equivalent binaries: contactctl and the
short alias ctc.
npm install -g contactctl
2
Authenticate with your API key
Replace <YOUR_KEY> with the key from your dashboard. The key is validated against the API and
stored locally with 0600 permissions.
contactctl auth <YOUR_KEY>
3
Confirm the connection
contactctl auth status prints your account, plan, and
balance, and exits 0. If it does, you are done installing.
$ contactctl auth status
account you@company.com
plan growth · 1,000 credits/month
balance 1,000 credits
key ctc_live_AbCd1234…
$ echo $?
0
4
Run your first lookups
A verification costs 0.02 credits. The second command spends nothing: --estimate prints what a find would cost (1 credit if found, free on a miss) and exits.
$ ctc verify jane@acme.com
{ "email": "jane@acme.com", "status": "deliverable", "confidence": 0.99 }
# a verification is 0.02 credits
$ ctc find "Jane Smith" acme.com --estimate
estimated_credits: 1
# prints the price locally, spends nothing — a miss is free
Or skip all of it —
hand this to your agent.
Swap in your API key, paste the block into Claude Code, Codex CLI, Cursor, or Gemini CLI, and the agent performs the whole setup.
Install the contactctl CLI globally with npm, authenticate with this key: <YOUR_KEY>, then run `contactctl instructions` and use it for contact lookups.
One file,
two environment variables.
Where the key lives, and how to override it for CI, containers, and locked-down networks.
~/.config/contactctl/config.json Written by contactctl auth with 0600 permissions. Holds the API key. Delete it to sign out.
CONTACTCTL_API_KEY Environment variable that overrides the config file. Use it in CI, containers, and ephemeral machines.
CONTACTCTL_API_URL Points the CLI at a different API base URL. Only needed when your network team routes egress through an internal host.
Precedence: CONTACTCTL_API_KEY beats the config file. Neither is ever sent anywhere except the ContactCTL API.
The four ways
installs go wrong.
Three setup snags with the exact fix, plus what a non-zero exit code is actually telling you.
contactctl: command not found
npm's global bin directory is not on your PATH. Find it, add it to your shell profile, then open a new shell.
npm config get prefix # add <prefix>/bin (macOS/Linux) or <prefix> (Windows) to PATH
EACCES: permission denied
Your npm prefix points at a system directory. Do not reach for sudo — move the prefix into your home directory (or use a Node version manager like nvm or fnm, which avoids the problem entirely), then reinstall.
npm config set prefix ~/.npm-global # add ~/.npm-global/bin to PATH, then: npm install -g contactctl
Behind a corporate proxy
Configure npm's proxy for the install itself. At runtime the CLI honors the standard HTTPS_PROXY and NO_PROXY environment variables; if your network rewrites egress hosts, set CONTACTCTL_API_URL to the address your team provides.
npm config set proxy http://proxy.company.com:8080 npm config set https-proxy http://proxy.company.com:8080
A command exited non-zero
That is the CLI working as designed: exit codes are deterministic, and a non-zero code tells
you exactly what happened — 2 not found, 3 risky, 4 over budget or
out of credits, 5 auth missing, 6 invalid input. Re-run with --json for a machine-readable
error object, and see the full table in the docs.
Installed? The rest is
one command at a time.
Every command, flag, exit code, and JSON shape lives in the documentation.