Signals CLI

Lead intelligence CLI for developers and AI agents -- Discover leads, manage subscriptions, and automate workflows from the terminal.

The Signals CLI provides a command-line interface to the Signals API, enabling developers and AI agents to monitor sources (LinkedIn, funding databases, etc.) and discover new leads programmatically.

---

Installation

npm install -g signals-sortlist-cli

For AI Agents

Install the Signals skill for your AI agent (Cursor, Claude Code, OpenClaw, etc.):

npx skills add sortlist/signals-cli

This installs the SKILL.md which gives your agent full knowledge of the CLI commands, patterns, and workflows.

---

Authentication

The recommended way to authenticate is the interactive login command:

signals login

This prompts for your API key (get it from Settings > API Keys in your dashboard), validates it, and saves it to ~/.signals/config.json.

Alternatively, set the SIGNALS_API_KEY environment variable (takes priority over saved config):

export SIGNALS_API_KEY=your_api_key

To remove saved credentials:

signals logout

API keys are scoped to your team. Use --business (-b) to specify which business to operate on for leads, subscriptions, and webhooks.

---

Commands

Signals (catalog)

The signal catalog lists all available monitoring types. This is read-only and public.

# List all signal types
signals signals:list

# Get details for a specific signal
signals signals:get linkedin-company-engagers

Businesses

Each team can have multiple businesses. All leads, subscriptions, and webhooks are scoped to a business.

# List all businesses in your team
signals businesses:list

# Get a business with its Ideal Customer Profile
signals businesses:get 1

# Create a business from a website (auto-analyzes name, description, and ICP)
signals businesses:create --website https://acme.com

# Create a business manually
signals businesses:create --name "Acme Corp" --website https://acme.com

# Create with ICP attributes
signals businesses:create --name "Acme Corp" \
  --icp '{"target_job_titles":["CTO","VP of Engineering"],"target_locations":["North America"]}'

businesses:create options:

Option	Required	Description
--website	Conditional	Website URL. If passed alone, auto-analyzes name/description/ICP
--name	Conditional	Business name (required when not using website-only mode)
--description	No	Short description
--icp	No	Ideal Customer Profile attributes as JSON string

# Update a business name
signals businesses:update 1 --name "New Name"

# Update the ICP (include the ICP id from businesses:get response)
signals businesses:update 1 --icp '{"id":1,"target_job_titles":["CTO","VP Engineering"],"lead_matching_mode":70}'

businesses:update options:

Option	Description
--name	Business name
--website	Website URL
--description	Short description
--icp	ICP attributes as JSON string (include id to update existing ICP)

Subscriptions

A subscription is a signal you've activated with a specific configuration (e.g. "Track engagers on Apple's LinkedIn page"). All subscription commands require --business (-b).

# List all subscriptions
signals subscriptions:list --business 1

# Get a subscription with stats
signals subscriptions:get 42 --business 1

# Create a subscription
signals subscriptions:create --business 1 \
  --signal linkedin-company-engagers \
  --name "Apple Engagers" \
  --config '{"linkedin_url":"https://www.linkedin.com/company/apple/"}'

# Update a subscription
signals subscriptions:update 42 --business 1 --name "Renamed Subscription"

# Pause (stops scanning for new leads)
signals subscriptions:pause 42 --business 1

# Resume
signals subscriptions:resume 42 --business 1

# Delete
signals subscriptions:delete 42 --business 1

subscriptions:create options:

Option	Required	Description
--business	Yes	Business ID
--signal	Yes	Signal slug from the catalog
--name	Yes	Name for this subscription
--config	No	Signal-specific config as JSON string

subscriptions:update options:

Option	Description
--name	Updated name
--active	Set active state (true/false)
--config	Updated config as JSON string

Leads

Leads are enriched profiles discovered by your active subscriptions. Each lead includes name, company, LinkedIn URL, email, phone, and more. All lead commands require --business (-b).

# List leads (paginated)
signals leads:list --business 1
signals leads:list --business 1 --page 2 --per-page 50

# Get a single lead with full details and delivery history
signals leads:get 1234 --business 1

# Delete a lead (soft-delete)
signals leads:delete 1234 --business 1

leads:list options:

Option	Default	Description
--business	—	Business ID (required)
--page	1	Page number
--per-page	25	Results per page (max 100)

Webhooks

Register URLs to receive an HTTP POST in real-time whenever a new lead is discovered. All webhook commands require --business (-b).

# List webhooks
signals webhooks:list --business 1

# Create a webhook with HMAC signature verification
signals webhooks:create --business 1 --url https://example.com/webhook --secret whsec_abc123

# Delete a webhook
signals webhooks:delete 10 --business 1

webhooks:create options:

Option	Required	Description
--business	Yes	Business ID
--url	Yes	URL to receive POST requests
--secret	No	Secret for HMAC-SHA256 signature verification

---

All Output is JSON

Every command outputs JSON for easy parsing with jq or consumption by AI agents:

# Get all lead emails
signals leads:list --business 1 --per-page 100 | jq '.leads[] | .payload.email'

# Get subscription IDs that are active
signals subscriptions:list --business 1 | jq '.subscriptions[] | select(.active) | .id'

# Count total leads
signals leads:list --business 1 | jq '.meta.total_count'

# List business names
signals businesses:list | jq '.businesses[] | .name'

---

Common Workflows

Set up a new business and start monitoring

# 1. Create a business from a website (auto-generates ICP)
signals businesses:create --website https://acme.com

# 2. Note the business ID from the response, then browse signals
signals signals:list

# 3. Create a subscription
signals subscriptions:create --business 1 \
  --signal linkedin-company-engagers \
  --name "Acme Engagers" \
  --config '{"linkedin_url":"https://www.linkedin.com/company/acme/"}'

# 4. Check for leads
signals leads:list --business 1

Pause and resume scanning

signals subscriptions:pause 42 --business 1    # Stop scanning
signals subscriptions:resume 42 --business 1   # Start scanning again

Set up real-time notifications

# Register a webhook
signals webhooks:create --business 1 --url https://my-app.com/signals --secret my_secret

# Verify
signals webhooks:list --business 1

---

Environment Variables

Variable	Required	Description
SIGNALS_API_KEY	No	Your Signals API key (overrides saved config from signals login)

---

Error Handling

Exit Code	Meaning
0	Success
1	Error (message on stderr)

HTTP Status	Meaning
401	Missing or invalid API key
404	Resource not found
422	Validation error
429	Rate limited (60 req/min)

---

Development

git clone https://github.com/sortlist/signals-cli.git
cd signals-cli
npm install
npm run dev    # Watch mode
npm run build  # Production build

Project Structure

src/
  index.ts              # CLI entry point (yargs)
  api.ts                # SignalsAPI client class
  config.ts             # Config management (~/.signals/config.json)
  commands/
    login.ts            # login, logout
    signals.ts          # signals:list, signals:get
    businesses.ts       # businesses:list, businesses:get, businesses:create, businesses:update
    subscriptions.ts    # Subscription management
    leads.ts            # Lead management
    webhooks.ts         # Webhook management

---

API Documentation

Full API docs: https://api.meetsignals.ai/docs/api

---

License

MIT

---

Links

• Website: api.meetsignals.ai
• API Docs: api.meetsignals.ai/docs/api
• GitHub: sortlist/signals-cli
• Issues: Report bugs