CLI Tool - Shoal API

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 entity search ethereum

Authentication

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

shoal auth YOUR_API_KEY

Skills + CLI

If you use Claude Code, you can install the Shoal skill directly from the CLI:

shoal skill install

Or install the skill package directly:

npx shoal-skill@latest

This installs the /shoal skill guidance locally. It does not replace the hosted MCP server at https://api.shoal.xyz/mcp.

Commands

Signal

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

# Get all signal events (bulk feed, higher-tier access)
shoal signal all
shoal signal all --limit 10 --offset 0

# Get events from the last 2 hours (bulk feed, higher-tier access)
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 (bulk feed, higher-tier access)
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

Entities

# Resolve a name into canonical Shoal entities
shoal entity search "Ethereum"
shoal entity search "Binance" --limit 5

# Get canonical entity detail by Shoal entity ID
shoal entity get 23151

# Traverse direct relationships
shoal entity relationships 23151
shoal entity relationships 23151 --limit 10

# List attached external references
shoal entity references 23151

Organizations (Compatibility)

# 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

Timeline

# Get a recent merged event timeline for one canonical entity
shoal timeline entity 23151 --since 7d
shoal timeline entity 23151 --since 2026-04-01T00:00:00Z --limit 10

# Use cursor pagination after the first page
shoal timeline entity 23151 --since 7d --cursor YOUR_CURSOR

Replay

# Get a premium merged replay across radar and signal
shoal replay global --since 7d
shoal replay global --since 2026-04-01T00:00:00Z --limit 10

# Use cursor pagination after the first page
shoal replay global --since 7d --cursor YOUR_CURSOR

Brief

# Single org brief (available on plans with brief access)
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 (higher-tier access)
shoal brief batch 526,765,1024
shoal brief batch 526,765,1024 --since 8h --compact

Webhooks

# Webhook commands require a plan with webhook access

# 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 Integrations

Hosted MCP (Recommended)

Shoal now provides a hosted MCP server:

https://api.shoal.xyz/mcp

Hosted MCP uses Shoal app authentication through app.shoal.xyz. Users sign in, approve access, and Shoal issues short-lived MCP tokens without exposing the raw API key to the MCP client. See MCP Server for the hosted setup flow and discovery URLs.

Claude Code Plugin Marketplace

If you use Claude Code, you can also install the Shoal plugin marketplace:

/plugin marketplace add shoalresearch/shoal-skill
/plugin install shoal@shoalresearch-tools
/reload-plugins

This installs the Shoal skill and registers the hosted MCP server for Claude Code.

Local stdio MCP (Fallback)

shoal-cli still ships a second binary, shoal-mcp, that runs a local stdio Model Context Protocol server. Use this only if your client does not support hosted MCP yet. 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: The exact tool list depends on the plan attached to the authenticated API key or hosted MCP account. Bulk feeds, briefs, and webhooks may be unavailable on lower tiers.

Tool	Description
`entities_search`	Resolve canonical entities by name or alias
`entities_get`	Get one canonical entity by Shoal entity ID
`entity_relationships`	Direct canonical relationships for one entity
`entity_references`	External references attached to one entity
`signal_top`	Top signal events by score
`signal_all`	All signal events (bulk feed, higher-tier access)
`signal_org`	Signal events for a specific entity
`signal_category`	Signal events by category
`signal_history`	Daily signal/radar activity for one entity (up to 90 days)
`radar_all`	All radar events (bulk feed, higher-tier access)
`radar_org`	Radar events for a specific entity
`radar_category`	Radar events by category
`orgs_search`	Search organizations by name (compatibility)
`orgs_get`	Get an org by ID with optional embedded events (compatibility)
`brief_org`	Intelligence brief for one entity
`brief_batch`	Briefs for up to 25 entities 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

​Installation

​Authentication

​Skills + CLI

​Commands

​Signal

​Radar

​Entities

​Organizations (Compatibility)

​Timeline

​Replay

​Brief

​Webhooks

​Enrich

​Categories

​Usage

​Relative Time Syntax

​Output

​Agent Integrations

​Hosted MCP (Recommended)

​Claude Code Plugin Marketplace

​Local stdio MCP (Fallback)