lonescale-cli

Command-line interface for the LoneScale public API. Enrich contacts, source contacts by company and persona, and poll async job results — all from your terminal.

Install

npm install -g lonescale-cli

Or run without installing:

npx lonescale-cli --help

Requires Node.js >= 18.

Authentication

Get your API key from LoneScale and provide it in one of three ways (checked in this order):

# 1. Flag (per-command)
lonescale enrich --api-key ls_xxx ...

# 2. Environment variable
export LONESCALE_API_KEY=ls_xxx

# 3. Config file (~/.lonescale/config.json)
mkdir -p ~/.lonescale
echo '{ "api_key": "ls_xxx" }' > ~/.lonescale/config.json

Commands

lonescale enrich

Trigger waterfall enrichment (email/phone) for a list of contacts.

# From a JSON file
lonescale enrich --type email,phone --contacts contacts.json

# Inline JSON
lonescale enrich --type email --contacts-inline '[
  { "firstname": "John", "lastname": "Doe", "domain": "acme.com" }
]'

# Pipe from stdin
cat contacts.json | lonescale enrich --type email

Async vs sync:

# Async (default): returns job ID immediately
lonescale enrich --type email --contacts contacts.json
# → { "id": "abc-123", "status": "..." }

# Async + wait: polls until done
lonescale enrich --type email --contacts contacts.json --wait --timeout 120

# Sync: returns results directly (rate-limited: 5 req/min)
lonescale enrich --type email --contacts contacts.json --sync

Options:

| Option | Description | |--------|-------------| | --type <types> | (required) Enrichment types, comma-separated: email, phone | | --contacts <file> | Path to JSON file with contacts array | | --contacts-inline <json> | Inline JSON contacts array | | --custom <json> | Custom metadata JSON | | --wait | Poll until job completes | | --sync | Use sync endpoint (rate-limited: 5 req/min) | | --timeout <seconds> | Max wait time (default: 120) |

Contact format:

[
  {
    "firstname": "John",
    "lastname": "Doe",
    "email": "[email protected]",
    "job_title": "CTO",
    "linkedin_url": "https://linkedin.com/in/johndoe",
    "domain": "acme.com",
    "company_name": "Acme Inc"
  }
]

firstname and lastname are required. All other fields are optional but improve match accuracy.

lonescale source

Search and source contacts by company domain and persona criteria.

# Basic usage
lonescale source --domain acme.com --personas personas.json

# With filters
lonescale source \
  --domain acme.com \
  --company-name "Acme Inc" \
  --company-linkedin "https://linkedin.com/company/acme" \
  --personas personas.json \
  --locations US,FR,GB \
  --seniority c-suite,vp,director \
  --limit 50 \
  --wait

Options:

| Option | Description | |--------|-------------| | --domain <domain> | (required) Company domain | | --personas <file> | Path to JSON file with personas array | | --personas-inline <json> | Inline JSON personas array | | --company-name <name> | Company name | | --company-linkedin <url> | Company LinkedIn URL (improves accuracy ~25%) | | --locations <codes> | ISO country codes, comma-separated (e.g., US,FR,GB) | | --seniority <levels> | Seniority levels, comma-separated | | --limit <n> | Max contacts to retrieve | | --disable-company-info | Skip company enrichment details | | --custom <json> | Custom metadata JSON | | --wait | Poll until job completes | | --sync | Use sync endpoint (rate-limited: 5 req/min) | | --timeout <seconds> | Max wait time (default: 120) |

Personas format:

[
  {
    "name": "Engineering Leaders",
    "job_titles": ["CTO", "VP Engineering", "Head of Engineering"],
    "exclude_job_titles": ["Junior", "Intern"]
  }
]

Available seniority levels: owner, founder, c-suite, partner, vp, head, director, manager, senior, entry, intern

Available locations: AT, AU, BE, CA, CH, DE, DK, ES, FI, FR, GB, IE, IL, IT, LU, NL, NO, PT, SE, US

lonescale result

Retrieve the result of an async job.

# One-shot status check
lonescale result abc-123

# Poll until done
lonescale result abc-123 --poll --interval 5 --timeout 180

Options:

| Option | Description | |--------|-------------| | --poll | Keep polling until job finishes | | --interval <seconds> | Seconds between polls (default: 3) | | --timeout <seconds> | Max wait time (default: 120) |

Global Options

These options work with all commands:

| Option | Description | |--------|-------------| | --api-key <key> | LoneScale API key | | --output <format> | Output format: json, table, or minimal | | --debug | Enable debug logging (shows HTTP requests/responses) |

Output Formats

# JSON (default when piped)
lonescale source --domain acme.com --personas p.json --wait --output json

# Table (default in terminal)
lonescale source --domain acme.com --personas p.json --wait --output table

# Minimal (just the job ID or status — useful for scripting)
lonescale enrich --type email --contacts c.json --output minimal

Output data goes to stdout, logs and progress go to stderr. This means you can pipe results cleanly:

lonescale source --domain acme.com --personas p.json --wait --output json | jq '.contacts | length'

Scripting Examples

# Fire and poll pattern
JOB_ID=$(lonescale enrich --type email --contacts contacts.json --output minimal)
echo "Job started: $JOB_ID"
lonescale result "$JOB_ID" --poll --output json > results.json

# Batch enrichment across multiple files
for file in contacts/*.json; do
  echo "Processing $file..."
  lonescale enrich --type email --contacts "$file" --wait --output json > "results/$(basename $file)"
done

# Source contacts and filter with jq
lonescale source --domain acme.com \
  --personas-inline '[{"name":"Sales","job_titles":["VP Sales","Head of Sales"]}]' \
  --wait --output json | jq '.contacts[] | {name: (.firstname + " " + .lastname), email: .most_probable_email}'

Debug Mode

Use --debug to see HTTP request/response details (API keys are automatically redacted):

$ lonescale enrich --type email --contacts c.json --debug --wait
[DEBUG] POST https://public-api.lonescale.com/trigger/enrich
[DEBUG] Body: { "enrichment_type": ["email"], "contacts": [...] }
[DEBUG] Response: 200 { "id": "abc-123", "status": "..." }
[INFO] Job abc-123 started, polling...
[DEBUG] GET https://public-api.lonescale.com/trigger/run/abc-123
[DEBUG] Response: 200 { "status": "processing" }
[DEBUG] GET https://public-api.lonescale.com/trigger/run/abc-123
[DEBUG] Response: 200 { "status": "finished", "contacts": [...] }