> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shoal.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI Tool

> Query the Shoal API from your terminal

## Installation

<Tabs>
  <Tab title="curl (Recommended)">
    The fastest way to install on macOS or Linux:

    ```bash theme={null}
    curl -fsSL https://api.shoal.xyz/install | bash
    ```

    The script checks for Node.js 18+, installs `shoal-cli` globally, and prints a quickstart.
  </Tab>

  <Tab title="npm">
    ```bash theme={null}
    npm install -g shoal-cli
    ```
  </Tab>

  <Tab title="npx (no install)">
    Run without installing:

    ```bash theme={null}
    npx shoal-cli entity search ethereum
    ```
  </Tab>
</Tabs>

## Authentication

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

```bash theme={null}
shoal auth YOUR_API_KEY
```

## Skills + CLI

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

```bash theme={null}
shoal skill install
```

Or install the skill package directly:

```bash theme={null}
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

```bash theme={null}
# 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

```bash theme={null}
# 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

```bash theme={null}
# 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)

```bash theme={null}
# 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

```bash theme={null}
# 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

```bash theme={null}
# 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

```bash theme={null}
# 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

```bash theme={null}
# 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.

```bash theme={null}
# 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:

```json theme={null}
[
  { "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-cases/business-development) use case for a full walkthrough.

### Categories

```bash theme={null}
# List all event categories
shoal categories
```

### Usage

```bash theme={null}
# 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:

```bash theme={null}
shoal signal top | jq '.data[].title'
```

## Agent Integrations

### Hosted MCP (Recommended)

Shoal now provides a hosted MCP server:

```text theme={null}
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](/integrations/mcp) 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:

```text theme={null}
/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](https://modelcontextprotocol.io) server. Use this only if your client does not support hosted MCP yet.

**Prerequisites:** run `shoal auth YOUR_API_KEY` first.

<Tabs>
  <Tab title="Claude Code">
    Add to `~/.claude/settings.json`:

    ```json theme={null}
    {
      "mcpServers": {
        "shoal": {
          "command": "shoal-mcp"
        }
      }
    }
    ```

    Or use the CLI:

    ```bash theme={null}
    claude mcp add --transport stdio shoal -- shoal-mcp
    ```
  </Tab>

  <Tab title="Cursor">
    Add to `.cursor/mcp.json` in your project (or the global `~/.cursor/mcp.json`):

    ```json theme={null}
    {
      "mcpServers": {
        "shoal": {
          "command": "shoal-mcp"
        }
      }
    }
    ```
  </Tab>

  <Tab title="Windsurf / Cline">
    Add to your MCP settings file:

    ```json theme={null}
    {
      "mcpServers": {
        "shoal": {
          "command": "shoal-mcp"
        }
      }
    }
    ```
  </Tab>
</Tabs>

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                                            |