CLI Tool

Installation

curl (Recommended)
npm
npx (no install)

The fastest way to install on macOS or Linux:

curl -fsSL https://api.shoal.xyz/install | bash

The script checks for Node.js 18+, installs shoal-cli globally, and prints a quickstart.

npm install -g shoal-cli

Run without installing:

npx shoal-cli signal top

Authentication

Save your API key (stored in ~/.config/shoal-cli):

shoal auth YOUR_API_KEY

Commands

Signal

# Get top signal events by score
shoal signal top
shoal signal top --limit 5

# Get all signal events
shoal signal all
shoal signal all --limit 10 --offset 0

# Get events from the last 2 hours
shoal signal all --since 2h

# Get signal events for a specific org
shoal signal org 526
shoal signal org 526 --since 1d

# Get signal events by category
shoal signal category partnership
shoal signal category funding --since 2h

# Get daily signal/radar activity history for an org
shoal signal history 526
shoal signal history 526 --days 60

Radar

# Get all radar events
shoal radar all
shoal radar all --limit 10

# Get events from the last day
shoal radar all --since 1d

# Get radar events for a specific org
shoal radar org 526
shoal radar org 526 --since 1d

# Get radar events by category
shoal radar category partnership
shoal radar category regulation_legal --since 2h

Organizations

# Search by name
shoal orgs search "Ethereum"

# Get by ID with optional embedded events
shoal orgs get 526
shoal orgs get 526 --include radar,signal

Brief

# Single org brief (radar + signal combined)
shoal brief org 526
shoal brief org 526 --since 2h --limit 10

# Compact mode for agents
shoal brief org 526 --since 8h --compact

# Batch brief for multiple orgs
shoal brief batch 526,765,1024
shoal brief batch 526,765,1024 --since 8h --compact

Webhooks

# List all webhooks
shoal webhooks list

# Create a webhook (receives both radar and signal by default)
shoal webhooks create https://your-server.com/webhook

# Create a webhook for signal events only
shoal webhooks create https://your-server.com/webhook --events signal

# Get a webhook by ID
shoal webhooks get 42

# Update a webhook
shoal webhooks update 42 --url https://new-endpoint.com/webhook
shoal webhooks update 42 --no-active   # disable
shoal webhooks update 42 --active      # re-enable

# Delete a webhook
shoal webhooks delete 42

Enrich

Enrich a contacts file with Shoal radar and signal events. Input is a JSON array of [{name, company}] objects.

# Enrich and print to stdout
shoal enrich contacts.json

# Write results to a file (progress shown in terminal)
shoal enrich contacts.json --output enriched.json

# Limit to 10 events per company
shoal enrich contacts.json --limit 10

Input format:

[
  { "name": "alice@example.com", "company": "Chainlink" },
  { "name": "bob@example.com", "company": "Arbitrum" }
]

Each contact is enriched with matched, shoal_org (id + label), and filtered radar/signal arrays where the company is the primary event owner. See the Business Development use case for a full walkthrough.

Usage

# Show usage stats and budget
shoal usage

Relative Time Syntax

The --since flag supports relative time shortcuts:

Shortcut	Meaning
`30m`	30 minutes ago
`2h`	2 hours ago
`1d`	1 day ago

You can also pass a full ISO 8601 timestamp: --since 2026-02-28T00:00:00Z

Output

All commands output JSON. Pipe to jq for formatting:

shoal signal top | jq '.data[].title'

Agent Integration (MCP)

shoal-cli ships a second binary, shoal-mcp, that runs a Model Context Protocol server over stdio. Once configured, AI agents can call Shoal tools directly — no shell commands needed. Prerequisites: run shoal auth YOUR_API_KEY first.

Claude Code
Cursor
Windsurf / Cline

Add to ~/.claude/settings.json:

{
  "mcpServers": {
    "shoal": {
      "command": "shoal-mcp"
    }
  }
}

Or use the CLI:

claude mcp add --transport stdio shoal -- shoal-mcp

Add to .cursor/mcp.json in your project (or the global ~/.cursor/mcp.json):

{
  "mcpServers": {
    "shoal": {
      "command": "shoal-mcp"
    }
  }
}

Add to your MCP settings file:

{
  "mcpServers": {
    "shoal": {
      "command": "shoal-mcp"
    }
  }
}

After restarting your agent, the following tools will be available:

Tool	Description
`signal_top`	Top signal events by score
`signal_all`	All signal events (paginated, filterable by time)
`signal_org`	Signal events for a specific org
`signal_category`	Signal events by category
`signal_history`	Daily signal/radar activity for an org (up to 90 days)
`radar_all`	All radar events (paginated, filterable by time)
`radar_org`	Radar events for a specific org
`radar_category`	Radar events by category
`orgs_search`	Search organizations by name
`orgs_get`	Get an org by ID with optional embedded events
`brief_org`	Intelligence brief for one org
`brief_batch`	Briefs for up to 25 orgs in one call
`categories`	List all event categories
`webhooks_list`	List all webhooks
`webhooks_create`	Register a new webhook
`webhooks_get`	Get a webhook by ID
`webhooks_update`	Update a webhook
`webhooks_delete`	Delete a webhook
`enrich`	Enrich a list of contacts with Shoal intelligence
`usage`	API usage and quota

Getting Started

Guides

SDK & Tools

Installation

Authentication

Commands

Signal

Radar

Organizations

Brief

Webhooks

Enrich

Categories

Usage

Relative Time Syntax

Output

Agent Integration (MCP)

Getting Started

Guides

SDK & Tools

​Installation

​Authentication

​Commands

​Signal

​Radar

​Organizations

​Brief

​Webhooks

​Enrich

​Categories

​Usage

​Relative Time Syntax

​Output

​Agent Integration (MCP)

Installation

Authentication

Commands

Signal

Radar

Organizations

Brief

Webhooks

Enrich

Categories

Usage

Relative Time Syntax

Output

Agent Integration (MCP)