@kantadev/cli

@kantadev/cli

Terminal (kanta) and MCP server (kanta-mcp) for Kanta Verify, Kanta Find, and the Kanta Database. Thin wrapper over the api.kanta.dev and database.kanta.dev REST APIs — no product logic lives here.

• Node 20+, ESM.
• Design specs: docs/superpowers/specs/2026-09-04-kanta-cli-mcp-verify-find-admin-design.md, docs/superpowers/specs/2026-09-04-kanta-database-api-mcp-design.md
• Full command reference: docs/cli.md

Install

npm install -g @kantadev/cli
kanta login            # paste your API key from app.kanta.dev

Local/dev:

cd kanta-cli
npm install
npm link

MCP (Claude Desktop / Claude Code / Cursor)

{
  "mcpServers": {
    "kanta": {
      "command": "npx",
      "args": ["-y", "@kantadev/cli", "kanta-mcp"],
      "env": { "KANTA_API_KEY": "your_key" }
    }
  }
}

The server calls GET /me once at startup to learn the key scope. If the API is unreachable it still boots with the customer tool set (admin tools appear once /me succeeds).

Auth

Key resolution order (first match wins):

• --api-key <key> global flag (never persisted)
• KANTA_API_KEY env var (optionally KANTA_BASE_URL, KANTA_DB_URL)
• --profile <name> from ~/.kanta/config.json
• default_profile from ~/.kanta/config.json
• Error — run kanta login

The Kanta Database API is a second base URL, resolved independently with the same key: --db-url → KANTA_DB_URL → profile db_base_url → https://database.kanta.dev/v1.

~/.kanta/config.json is written mode 0600:

{
  "default_profile": "personal",
  "profiles": {
    "personal": { "key": "kdev_live_…", "base_url": "https://api.kanta.dev", "db_base_url": "https://database.kanta.dev/v1" },
    "admin":    { "key": "kdev_live_…", "base_url": "https://api.kanta.dev", "db_base_url": "https://database.kanta.dev/v1" }
  }
}

kanta login --profile personal      # prompts for the key (hidden), validates via GET /me
kanta whoami
kanta config show                   # resolved config, key masked
kanta logout --profile personal

Customer commands

kanta verify [e-mail]
kanta verify bulk contacts.csv               # CSV needs an "email" column
kanta find Ada Lovelace analytical.co        # synchronous — prints the email (or "no email found")
kanta find bulk people.csv                   # CSV needs first_name,last_name,company; prints a job id
kanta jobs list [--status <s>]
kanta jobs get <id> [--breakdown]
kanta jobs results <id> [-o results.csv]
kanta jobs cancel|resume|delete <id>
kanta account
kanta credits

Add --json to any command for machine output.

Kanta Database

Search, count, facet, and export the B2B contact database. Search/count/facets are free; export costs 1 db credit per row delivered (admin keys are not charged).

kanta db count   --seniority c-suite --industry software
kanta db search  --function marketing --has-email --limit 25 [-o people.csv]
kanta db facets  --industry software --field seniority --field person_state
kanta db lookup  --email [e-mail]
kanta db lookup  --name "Jane Doe" --domain acme.com

kanta db export  --seniority vp --industry software --max 5000 -o leads.csv
kanta db exports                      # your recent export jobs
kanta db export-status <id>
kanta db download <id> -o leads.csv

kanta db companies count  --industry software --employees-min 50
kanta db companies search --hq-country "United States" --min-contacts 5
kanta db companies export --industry fintech --max 2000 -o firms.csv
kanta db company contacts <kanta_org_id> --limit 25

kanta --profile admin db ca-count     # CCPA California-record monitor (admin)

Person filter flags

Flag	Meaning
--query <text>	free text over name / title / company
--seniority <label…>	c-suite, vp, director, manager, … (case-insensitive)
--function <name…>	job function(s)
--title <text>	title prefix match
--title-exact <text…>	exact normalized title(s)
--country <name…> / --state <name…>	person location
--company <text>	company name prefix
--company-domain <domain…>	company domain(s)
--industry <name…>	company industry/industries
--employee-range <range…>	e.g. 51-200
--has-email / --has-linkedin / --has-phone	presence filters
--verification-status <s…>	admin only (else the API returns 403)
--filter-file <path>	raw JSON filter object, merged under the flags

Company flags: --query, --domain, --industry, --employee-range, --hq-country, --hq-state, --funding-stage, --employees-min/max, --revenue-min-k/max-k, --founded-after, --min-contacts, --filter-file.

The db export flow prints the match count and credit cost, prompts for confirmation (skip with -y), submits the job, polls until it finishes, and writes the CSV to -o. A confirm_credits_required response is retried once with the API's capped estimated_max.

Admin commands (admin-scoped key only)

kanta --profile admin admin credits add --email [e-mail] --product find --amount 500 --reason topup
kanta --profile admin admin jobs list [--status <s>] [--user <email>]
kanta --profile admin admin user [e-mail]
kanta --profile admin admin verify [e-mail]          # no credit charge
kanta --profile admin admin suppress add blocked.com # email vs domain auto-detected by "@"
kanta --profile admin admin suppress check [e-mail]

Every admin command calls GET /me first; if the resolving key is not scope: 'admin' it exits 1 with:

This command requires an admin profile. Active profile "<name>" is a standard key.

The admin tag

Admin capability is not self-service. It requires an api_keys row with scope = 'admin' and the owning user having is_god_mode = true.

• Apply EmailVerifier_V1/infra/api_key_scope_migration.sql to Supabase.
• Generate a normal key from app.kanta.dev for the operator.
• In Supabase Studio → Table Editor → api_keys, find that row (match on label or last_used_at) and set scope to admin. Save.
• kanta login --profile admin with that key.

Revoke by setting scope back to user. No API path or dashboard UI reads or writes scope, so a leaked standard key can never reach /admin/*.

MCP tools

See the config block at the top of this file. Admin tools appear in tools/list only when the key is admin-scoped.

• Verify / Find / jobs: kanta_verify_email, kanta_verify_bulk, kanta_find_email, kanta_find_bulk, kanta_jobs_list, kanta_job_get, kanta_job_results, kanta_job_cancel, kanta_job_delete, kanta_account, kanta_credits
• Database: kanta_db_count, kanta_db_search, kanta_db_facets, kanta_db_lookup, kanta_db_export, kanta_db_export_status, kanta_db_companies_count, kanta_db_companies_search, kanta_db_companies_facets, kanta_db_company_contacts
• Admin: kanta_admin_credits_add, kanta_admin_jobs_list, kanta_admin_user, kanta_admin_verify, kanta_admin_suppress_add, kanta_admin_suppress_check, kanta_db_ca_count

kanta_find_email is synchronous — it returns { email, confidence, method, pattern } inline (or { email: null }) and charges a find credit only on a hit. Bulk tools accept either an inline array or a path to a CSV and return a job_id. Result tools cap inline output at 100 rows and otherwise return a sample plus a CLI hint. kanta_db_export requires a confirm_credits integer — call kanta_db_count first, then pass the number of credits you intend to spend; on confirm_credits_required the tool returns the estimated_max to retry with.

Tests

npm test        # vitest

Layout

kanta-cli/
├── bin/kanta.js            `kanta` CLI entry
├── bin/kanta-mcp.js        `kanta-mcp` stdio MCP server entry
├── server.json             MCP registry manifest
├── src/
│   ├── core/               client.js config.js auth.js identity.js errors.js dbFilter.js
│   ├── cli/                index.js format.js context.js commands/ (incl. commands/db/)
│   └── mcp/                server.js register.js tools/ (customer.js admin.js database.js)
└── tests/                  bin.test.js core/ cli/ mcp/