seamless-ai-cli

v0.1.8

Published

9 days ago

CLI and MCP server for the Seamless.ai B2B prospecting platform — contact search, company search, research, and org data

0High
0Medium
0Low

bcharleson

seamless seamless-ai b2b prospecting lead-generation contacts companies sales cli mcp ai-agent automation outbound

seamless-ai-cli

JSON-first, agent-native CLI and MCP server for the Seamless.ai B2B prospecting platform.

Search 1.9B+ contacts and 121M+ companies, run AI research/enrichment, and retrieve your org's data — all from the terminal or via any MCP-compatible AI agent.

Installation

npm install -g seamless-ai-cli

Requirements: Node.js 18+

PATH note: If the seamless command is not found after install, add npm's global bin to your shell PATH:
export PATH="$(npm root -g)/../bin:$PATH"
# Make permanent: add to ~/.zshrc or ~/.bashrc

Authentication

Get your API key from: Settings → API Key in your Seamless.ai account.

Option 1 — Environment variable (recommended for agents)

export SEAMLESS_API_KEY="your-api-key-here"

Option 2 — Login command (saves to `~/.seamless-cli/config.json`)

seamless login
# or non-interactively:
seamless login --api-key "your-api-key-here"

Option 3 — Per-command flag

seamless contacts list --api-key "your-api-key-here"

Priority order: --api-key flag > SEAMLESS_API_KEY env > ~/.seamless-cli/config.json

Quick Start

# Search for contacts at a specific company
seamless contacts search --company-name "Stripe" --department "Engineering"

# Search for VP-level contacts in software
seamless contacts search --seniority "VP" --industry "Computer Software" --limit 25

# Research a contact from search results (returns requestId)
seamless contacts research --search-result-ids "abc123,def456"

# Poll research results (auto-wait until complete)
seamless contacts poll --request-ids "req_abc123" --wait

# List your org's saved contacts
seamless contacts list --limit 100

# Search companies in financial services with 51-200 employees
seamless companies search --industry "Financial Services" --company-size "51 - 200"

# Research companies by domain
seamless companies research --domains "stripe.com,shopify.com"

# Get pretty-printed output
seamless contacts search --company-domain "stripe.com" --pretty

Output Format

All commands output compact JSON to stdout by default — ideal for piping and agent consumption.

# Default: compact JSON
seamless contacts list
# → {"data":[{"firstName":"John","lastName":"Doe","email":"[email protected]",...}],...}

# Pretty-printed
seamless contacts list --pretty

# Select specific fields (supports dot notation)
seamless contacts list --fields "firstName,lastName,email,contactLocation.city"

# Suppress output (exit code only — 0 = success, 1 = error)
seamless contacts list --quiet

Errors go to stderr:

{"error":"No API key found. Set SEAMLESS_API_KEY or run: seamless login","code":"AUTH_ERROR"}

Commands

Auth

| Command | Description | |---------|-------------| | seamless login | Authenticate and save API key | | seamless logout | Remove stored credentials | | seamless status | Show current authentication status |

MCP Server

| Command | Description | |---------|-------------| | seamless mcp | Start stdio MCP server for AI agent integration |

contacts search

Search Seamless.ai's 1.9B+ contact database with powerful filters.

seamless contacts search [options]

| Option | Description | Limit | |--------|-------------|-------| | --company-name <names> | Company name(s), comma-separated | max 100 | | --company-name-search-type <type> | Name match mode: default | related | exact | — | | --company-domain <domains> | Domain(s), e.g. stripe.com,shopify.com | max 100 | | --contact-state <states> | US state(s): CA, TX, NY, etc. (abbreviations auto-expanded) | max 10 | | --contact-country <countries> | Country/countries, comma-separated | max 10 | | --contact-zip-code <zips> | Zip/postal code(s), comma-separated | max 10 | | --location-type <type> | Location scope: bothOR | bothAND | company | contact | — | | --full-name <names> | Full name(s) to search, comma-separated | max 10 | | --job-title <titles> | Job title(s), comma-separated | max 10 | | --department <depts> | Department(s): Engineering, Sales, Marketing, etc. | max 5 | | --seniority <levels> | Seniority: Director, VP, C-Suite, Manager, etc. | max 5 | | --contact-keyword <keywords> | Contact keyword(s), comma-separated | max 10 | | --industry <industries> | Industry/industries, comma-separated | max 5 | | --company-founded-on <ranges> | Company founded year/range(s), comma-separated | max 4 | | --company-size <ranges> | Employee ranges, pipe-separated: "51 - 200\|201 - 500\|1,001 - 5,000" — see size table below | max 10 | | --company-revenue <ranges> | Revenue ranges, comma-separated | max 10 | | --technologies <techs> | Technologies used: Salesforce, HubSpot, etc. | max 10 | | --technologies-is-or | Match contacts using ANY tech listed (OR). Default: ALL (AND) | — | | --last-modified-after <date> | ISO8601 date filter | — | | --last-modified-before <date> | ISO8601 date filter | — | | -l, --limit <n> | Results per page (1-100, default 25) | — | | --next-token <token> | Pagination token from previous search | — |

Examples:

seamless contacts search --seniority "VP,Director" --industry "Computer Software,Internet"
seamless contacts search --company-domain "stripe.com" --department "Engineering"
seamless contacts search --technologies "HubSpot" --company-size "51 - 200|201 - 500" --limit 50
seamless contacts search --company-name "Apple" --company-name-search-type exact
seamless contacts search --contact-state "CA,NY" --location-type contact
seamless contacts search --full-name "John Smith" --contact-keyword "RevOps"
seamless contacts search --technologies "Salesforce,HubSpot" --technologies-is-or

Response includes: data[] with searchResultId, name, company, title, location — plus supplementalData.nextToken for pagination.

contacts research

Submit contacts for deep AI enrichment. Returns requestIds — poll with contacts poll.

seamless contacts research [options]

| Option | Description | |--------|-------------| | --search-result-ids <ids> | Comma-separated searchResultIds from contacts search | | --contacts <pairs> | "Name:Company" pairs, comma-separated | | --linkedin-urls <urls> | LinkedIn profile URL(s), comma-separated | | --is-job-change | Flag as job-change research |

Examples:

# From search results (most common)
seamless contacts research --search-result-ids "abc123,def456"

# From raw data
seamless contacts research --contacts "John Smith:Stripe,Jane Doe:Shopify"

# From LinkedIn
seamless contacts research --linkedin-urls "https://linkedin.com/in/johndoe"

contacts poll

Poll research request status. Use --wait to block until complete.

seamless contacts poll --request-ids <ids> [options]

| Option | Description | |--------|-------------| | --request-ids <ids> | Comma-separated requestIds (required) | | --wait | Auto-poll until all requests complete | | --poll-interval <s> | Seconds between polls when --wait is set (default 5) | | --max-attempts <n> | Max poll attempts (default 24 ≈ 2 minutes) |

Researched contact data includes: email, phone, personalEmail, contactLocation, jobHistory[], lIProfileUrl, and more.

contacts list

List researched contacts saved to your org.

Note: Date range must be ≤30 days. Defaults to the last 30 days if omitted.

seamless contacts list [options]

| Option | Description | |--------|-------------| | -p, --page <n> | Page number (default 1) | | -l, --limit <n> | Results per page (1-500, default 50) | | --start-date <date> | Range start ISO8601 e.g. 2024-11-01T00:00:00Z (default: 30 days ago) | | --end-date <date> | Range end ISO8601 e.g. 2024-11-30T23:59:59Z (default: now) |

companies search

Search 121M+ companies with rich filters.

seamless companies search [options]

companies research

Submit companies for deep AI enrichment. Returns requestIds.

seamless companies research [options]

| Option | Description | |--------|-------------| | --search-result-ids <ids> | searchResultIds from companies search | | --domains <domains> | Company domain(s), comma-separated | | --company-names <names> | Company name(s), comma-separated |

companies poll

Poll company research status.

seamless companies poll --request-ids <ids> [options]

Same options as contacts poll.

companies list

List researched companies saved to your org.

Note: Date range must be ≤30 days. Defaults to the last 30 days if omitted.

seamless companies list [options]

Same options as contacts list.

oauth exchange

Exchange an OAuth authorization code for an access token (for app developers building on the Seamless.ai platform).

seamless oauth exchange [options]

| Option | Description | |--------|-------------| | --client-id <id> | Your OAuth application client ID | | --client-secret <secret> | Your OAuth application client secret | | --redirect-uri <uri> | Redirect URI registered with your app | | --code <code> | Authorization code from the OAuth callback |

Example:

seamless oauth exchange \
  --client-id "your-client-id" \
  --client-secret "your-client-secret" \
  --redirect-uri "https://myapp.com/callback" \
  --code "auth_code_from_callback"

Response: { "access_token": "...", "refresh_token": "...", "expires_at": 1712000000 }

oauth refresh

Refresh an expired access token.

seamless oauth refresh [options]

| Option | Description | |--------|-------------| | --client-id <id> | Your OAuth application client ID | | --client-secret <secret> | Your OAuth application client secret | | --redirect-uri <uri> | Redirect URI registered with your app | | --refresh-token <token> | Refresh token from a previous token exchange |

Example:

seamless oauth refresh \
  --client-id "your-client-id" \
  --client-secret "your-client-secret" \
  --redirect-uri "https://myapp.com/callback" \
  --refresh-token "your-refresh-token"

Pagination

Search results use nextToken-based pagination:

# First page
seamless contacts search --seniority "VP" --limit 50 --pretty
# → supplementalData.nextToken = "eyJwYWdl..."

# Next page
seamless contacts search --seniority "VP" --limit 50 --next-token "eyJwYWdl..."

Org list endpoints (contacts list, companies list) use page-based pagination with --page.

Research Workflow

The research flow is asynchronous — submit → poll:

# 1. Search for contacts
seamless contacts search --company-name "Stripe" --seniority "VP" --pretty
# → Note the searchResultId for each result

# 2. Submit for research (enrichment)
seamless contacts research --search-result-ids "abc123,def456"
# → {"requestIds":["req_xyz789"]}

# 3. Poll until complete (--wait handles the retry loop)
seamless contacts poll --request-ids "req_xyz789" --wait
# → Full contact data with email, phone, job history, etc.

MCP Server (AI Agent Integration)

Run as an MCP server for direct AI agent integration:

# Start MCP server (stdio transport)
seamless mcp

# Or use the direct binary
node /path/to/dist/mcp.js

Claude Desktop / Claude Code config

{
  "mcpServers": {
    "seamless": {
      "command": "seamless",
      "args": ["mcp"],
      "env": {
        "SEAMLESS_API_KEY": "your-api-key-here"
      }
    }
  }
}

Available MCP Tools (10 total)

| Tool | Description | |------|-------------| | contacts_search | Search contacts with all filters including locationType, technologiesIsOr, companyNameSearchType | | contacts_research | Submit contacts for enrichment via IDs, name:company pairs, or LinkedIn URLs | | contacts_poll | Poll contact research status (supports wait: true for blocking) | | contacts_list | List org contacts with date filters (≤30-day range) | | companies_search | Search companies with all filters including companyKeyword, technologiesIsOr | | companies_research | Submit companies for enrichment via IDs, domains, or names | | companies_poll | Poll company research status (supports wait: true for blocking) | | companies_list | List org companies with date filters (≤30-day range) | | oauth_exchange | Exchange OAuth authorization code for access + refresh tokens | | oauth_refresh | Refresh an expired OAuth access token |

Industry Taxonomy

Seamless.ai uses its own industry strings. Generic terms like "SaaS", "Fintech", or "Technology" return 0 results. Use exact values:

Company Size Values

--company-size uses pipe | as separator (not comma) because size values contain commas. Spaces around the dash are required.

| Flag value | Employees | |------------|-----------| | 1 - 10 | 1–10 | | 11 - 50 | 11–50 | | 51 - 200 | 51–200 | | 201 - 500 | 201–500 | | 501 - 1,000 | 501–1,000 | | 1,001 - 5,000 | 1,001–5,000 | | 5,001 - 10,000 | 5,001–10,000 | | 10,001+ | 10,001+ |

seamless companies search --company-size "51 - 200"
seamless companies search --company-size "51 - 200|201 - 500"
seamless companies search --company-size "1,001 - 5,000|5,001 - 10,000|10,001+"

Rate Limits

Seamless.ai allows approximately 100 requests per 60 seconds per endpoint. The client automatically:

Respects X-RateLimit-Reset and Retry-After headers
Retries up to 3 times with exponential backoff on 429, 500, 502, 503, 504
Reports remaining credits via X-PublicAPI-Credits header in API responses

Error Codes

| Code | Meaning | Fix | |------|---------|-----| | AUTH_ERROR | Invalid or missing API key | Set SEAMLESS_API_KEY or run seamless login | | INSUFFICIENT_CREDITS | No Seamless.ai credits remaining | Add credits in account settings | | RATE_LIMIT | ~100 req/60s exceeded | Auto-retried up to 3× with exponential backoff | | VALIDATION_ERROR | Bad request parameters | Check --help for correct options | | NOT_FOUND | Resource not found | Verify IDs are correct | | TIMEOUT | Request timed out | Retry — transient network issue | | NETWORK_ERROR | Cannot reach API | Check connectivity |

Environment Variables

| Variable | Description | |----------|-------------| | SEAMLESS_API_KEY | Seamless.ai API key |

License

MIT

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

seamless-ai-cli

Installation

Authentication

Option 1 — Environment variable (recommended for agents)

Option 2 — Login command (saves to ~/.seamless-cli/config.json)

Option 3 — Per-command flag

Quick Start

Output Format

Commands

Auth

MCP Server

contacts search

contacts research

contacts poll

contacts list

companies search

companies research

companies poll

companies list

oauth exchange

oauth refresh

Pagination

Research Workflow

MCP Server (AI Agent Integration)

Claude Desktop / Claude Code config

Available MCP Tools (10 total)

Industry Taxonomy

Company Size Values

Rate Limits

Error Codes

Environment Variables

License

Option 2 — Login command (saves to `~/.seamless-cli/config.json`)