---
slug: "cerul"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/cerul-ai/cerul@main/README.md"
repo: "https://github.com/cerul-ai/cerul"
source_file: "README.md"
branch: "main"
---
<div align="center">
  <br />
  <a href="https://cerul.ai">
    <picture>
      <source media="(prefers-color-scheme: dark)" srcset="./assets/cerul-paper-256.png" />
      <img src="./assets/cerul-graphite-256.png" alt="Cerul" width="88" />
    </picture>
  </a>
  <h1>Cerul</h1>
  <p><strong>Where video becomes citable.</strong></p>
  <p>Stop scrubbing. Start searching. The video search API for agents — meaning-based, grounded, timestamped.</p>

  <p>
    <a href="https://cerul.ai/docs"><strong>Docs</strong></a> &middot;
    <a href="https://cerul.ai/docs/search-api"><strong>API Reference</strong></a> &middot;
    <a href="https://cerul.ai/pricing"><strong>Pricing</strong></a> &middot;
    <a href="https://x.com/cerul_hq"><img src="https://img.shields.io/badge/follow-%40cerul__hq-000?style=flat-square&logo=x" alt="Follow on X" /></a> &middot;
    <a href="https://discord.gg/qHDEMQB9vN"><img src="https://img.shields.io/badge/join-Discord-5865F2?style=flat-square&logo=discord&logoColor=white" alt="Join Discord" /></a> &middot;
    <a href="#wechat-group"><img src="https://img.shields.io/badge/WeChat-Group-07C160?style=flat-square&logo=wechat&logoColor=white" alt="Join WeChat Group" /></a>
  </p>

  <p>
    <a href="./LICENSE"><img alt="License" src="https://img.shields.io/badge/license-Apache_2.0-3b82f6?style=flat-square" /></a>
    <a href="https://www.npmjs.com/package/cerul"><img alt="npm" src="https://img.shields.io/npm/v/cerul?style=flat-square&color=22c55e" /></a>
    <a href="https://pypi.org/project/cerul"><img alt="PyPI" src="https://img.shields.io/pypi/v/cerul?style=flat-square&color=22c55e" /></a>
  </p>
</div>

<br />

<div align="center">
  <img src="./assets/screenshot-home.png" alt="Cerul — Copy, paste, run. Get video results in seconds." width="840" />
</div>

<br />

<div align="center">
  <video src="https://github.com/user-attachments/assets/e0982048-3b40-42b9-80b6-a79b401d2355" width="720" autoplay loop muted playsinline></video>
</div>

<br />

## Why Cerul

Web pages are easy for AI agents to search. **Video is not.**

Most video search today is limited to transcripts — what was *said*. Cerul goes further by indexing what is *shown*: slides, charts, product demos, code walkthroughs, whiteboards, and other visual evidence.

> [!NOTE]
> Cerul is in active development. The API is live at [cerul.ai](https://cerul.ai) — sign up to get a free API key.

## Quickstart

### Claude Code plugin

Install the official Cerul plugin in Claude Code:

```bash
/plugin marketplace add cerul-ai/cerul-plugin-cc
/plugin install cerul@cerul-plugin
```

Source: [cerul-ai/cerul-plugin-cc](https://github.com/cerul-ai/cerul-plugin-cc).

### Use with your AI agent

Copy this and send it to your agent (Claude Code, Codex, Cursor, etc.):

```
Install the Cerul video search skill: mkdir -p ~/.claude/skills/cerul && curl -fsSL https://raw.githubusercontent.com/cerul-ai/cerul/main/skills/cerul/SKILL.md -o ~/.claude/skills/cerul/SKILL.md && cat ~/.claude/skills/cerul/SKILL.md
```

Your agent will install the CLI, set up credentials, and start searching videos as a tool.

<div align="center">
  <img src="./assets/agent-skill-search.png" alt="Claude Code using Cerul skill to search videos" width="720" />
  <img src="./assets/agent-skill-result.png" alt="Agent synthesizing video evidence into an answer" width="720" />
</div>

Or install via the skills CLI:

```bash
npx skills add cerul-ai/cerul
```

<details>
<summary><strong>Install for specific agents</strong></summary>

```bash
# Claude Code
mkdir -p ~/.claude/skills/cerul && curl -fsSL https://raw.githubusercontent.com/cerul-ai/cerul/main/skills/cerul/SKILL.md -o ~/.claude/skills/cerul/SKILL.md

# Windsurf
mkdir -p ~/.codeium/windsurf/skills/cerul && curl -fsSL https://raw.githubusercontent.com/cerul-ai/cerul/main/skills/cerul/SKILL.md -o ~/.codeium/windsurf/skills/cerul/SKILL.md

# OpenCode
mkdir -p ~/.config/opencode/skills/cerul && curl -fsSL https://raw.githubusercontent.com/cerul-ai/cerul/main/skills/cerul/SKILL.md -o ~/.config/opencode/skills/cerul/SKILL.md

# Cline / Cursor
mkdir -p .claude/skills/cerul && curl -fsSL https://raw.githubusercontent.com/cerul-ai/cerul/main/skills/cerul/SKILL.md -o .claude/skills/cerul/SKILL.md
```

</details>

### CLI

```bash
curl -fsSL https://cli.cerul.ai/install.sh | bash
cerul search "Sam Altman on AI video generation tools"
```

<div align="center">
  <img src="./assets/cli-search.png" alt="cerul search CLI output" width="720" />
</div>

> Inline video frame previews are supported in iTerm2, WezTerm, and Kitty. Enable with `cerul config` and toggle **Images** on. Other terminals show text-only results.

### MCP (Model Context Protocol)

Connect any MCP-compatible client to the hosted endpoint (replace with your API key):

```bash
# Claude Code
claude mcp add --transport streamable-http "https://api.cerul.ai/mcp?apiKey=YOUR_API_KEY" cerul

# Codex
codex mcp add --url "https://api.cerul.ai/mcp?apiKey=YOUR_API_KEY" cerul
```

Also works with Claude Desktop, Cursor, Windsurf, and other MCP clients.

<details>
<summary><strong>SDK & API</strong></summary>

**Python**

```bash
pip install cerul
```

```python
from cerul import Cerul

client = Cerul(api_key="YOUR_API_KEY")
results = client.search(query="Sam Altman on AGI timeline", max_results=5)

for r in results:
    print(r.title, r.url)
```

**JavaScript**

```bash
npm install cerul
```

```javascript
import { cerul } from "cerul";

const client = cerul({ apiKey: "YOUR_API_KEY" });
const result = await client.search({ query: "Sam Altman on AGI timeline", max_results: 5 });

for (const r of result.results) {
  console.log(r.title, r.url);
}
```

**cURL**

```bash
curl "https://api.cerul.ai/v1/search" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "Sam Altman on AGI timeline", "max_results": 5}'
```

Full API spec: [`openapi.yaml`](https://github.com/cerul-ai/cerul/blob/HEAD/openapi.yaml) | [cerul.ai/docs](https://cerul.ai/docs/search-api)

</details>

## License

Licensed under [Apache 2.0](https://github.com/cerul-ai/cerul/tree/HEAD/LICENSE).

<h2 id="wechat-group">Community</h2>

Questions, feedback, or just want to follow along? Join the conversation — pick whichever community is closest to you.

**🇨🇳 中国 (China)** — scan to join the WeChat group:

<p align="center">
  <strong>微信群 (WeChat)</strong><br />
  「Cerul.ai 官方社群」<br /><br />
  <img src="./assets/wechat-group.png" alt="Cerul.ai 官方微信社群二维码" width="240" />
</p>

**🌍 International** — chat with users and contributors worldwide on Discord:

<a href="https://discord.gg/qHDEMQB9vN"><img src="https://img.shields.io/badge/Join%20our-Discord-5865F2?style=for-the-badge&logo=discord&logoColor=white" alt="Join our Discord" /></a>

> **Heads up:** the WeChat QR rotates periodically and may expire. If a scan fails, ping us on [Discord](https://discord.gg/qHDEMQB9vN) or [X / Twitter](https://x.com/cerul_hq) for the latest invite.

<div align="center">
  <br />

  [![Star History Chart](https://api.star-history.com/svg?repos=cerul-ai/cerul&type=Date)](https://star-history.com/#cerul-ai/cerul&Date)

  <br />
  <sub>Built by <a href="https://github.com/JessyTsui">@JessyTsui</a></sub>
</div>