CLI Tool

shoal auth YOUR_API_KEY

shoal skill install

npx shoal-skill@latest

# 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

# 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

# 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

# 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

# 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

# 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

# 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

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

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

# List all event categories
shoal categories

# Show usage stats and budget
shoal usage

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

https://api.shoal.xyz/mcp

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