Install
From 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 it for you.
01 — Prerequisites
Two things, nothing exotic
- 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.
- 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_….
node --version # v18.0.0 or newer
02 — Setup
Install, authenticate, confirm
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. If it does, you are done installing.
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 ctc find "Jane Smith" acme.com --estimate
03 — Hand-off
Or skip all of the above: paste 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.
04 — Configuration
One file, two environment variables
~/.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.
05 — Troubleshooting
The four ways installs go wrong
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 — not found, invalid input, out of credits, rate limited.
Re-run with --json for a machine-readable error object,
and see the full exit-code 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.