# Virlo

> Pull raw performance signal from TikTok, Instagram, and YouTube using your saved Virlo comet. Fetch top videos, creator outliers, and ads for a niche. Use when: user asks what is performing, wants top videos, wants breakout creators, wants creator outliers, wants raw Virlo data, wants ads, needs a comet set up, or needs performance intelligence before synthesis. Do NOT use this as the final briefing layer — use content-radar when the goal is to combine performance with discussion signal and decide what matters.

- Skill: `themattberman/virlo` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add themattberman/virlo`
- Raw SKILL.md: https://api.skillmd.com/api/skills/themattberman/virlo/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools, Product & Planning
- Author: TheMattBerman (https://skillmd.com/u/themattberman)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/themattberman/virlo

---


# Virlo — Raw Performance Signal

## What Is Virlo?

Virlo is the **raw performance signal layer** in the pipeline.

It scans **TikTok, Instagram, and YouTube** for niche content based on your keywords. It runs on a schedule (daily, weekly, etc.) and surfaces:

- **Videos** matching your keywords, filtered by platform, views, and date
- **Creator Outliers** — creators whose content is massively outperforming their typical reach (breakout signals)
- **Meta Ads** — ads related to your keywords (when enabled)

Think of it as a **raw performance scanner** for any niche. Set it once, and it continuously collects intelligence.

---

## When To Use This Skill

Use Virlo when you need **raw performance intelligence**, not the final interpretation.

- **What is performing right now?**
- **Show me top videos in this niche**
- **Show me breakout creators / outliers**
- **Pull raw Virlo data**
- **Show me ads tied to this niche**
- **Set up or manage a comet**

Do NOT use Virlo when the real goal is:
- combining performance with Reddit/X discussion
- deciding what matters and why
- generating a weekly niche briefing
- feeding a fused signal set into The Forge

For those, use **Content Radar**.

---

## Concepts

### Comet (Custom Niche Config)
A "Comet" is Virlo's name for a saved niche configuration. You define:
- **Name** — your label for this tracking job
- **Keywords** — up to 20 phrases to scan for
- **Platforms** — tiktok, instagram, youtube (or all three)
- **Cadence** — how often to scrape (daily/weekly/monthly or cron)
- **Min Views** — filter out low-traction content
- **Time Range** — today, this_week, this_month, this_year

Once created, Virlo runs it automatically on your schedule and stores the results.

### Creator Outliers
A creator is an "outlier" when one of their videos dramatically outperforms their baseline. The **outlier ratio** = viral views ÷ average views. Higher ratio = bigger breakout signal.

---

## Pipeline Role

Think of the stack like this:
- **Virlo** = raw performance signal
- **Content Radar** = performance + discussion fused into a briefing
- **The Forge** = turns the briefing into brand-native concepts
- **Monday Drop** = orchestrates the weekly pack

Virlo does NOT decide what matters. It fetches the signal so other skills can interpret it.

---

## Script Location

```bash
~/clawd/skills/virlo/scripts/virlo.sh
```

---

## Commands

### Create a niche config
```bash
./virlo.sh create \
  --name "AI Marketing" \
  --keywords "ai marketing,vibe marketing,ai automation" \
  --platforms "tiktok,instagram,youtube" \
  --cadence "daily" \
  --min-views 1000 \
  --time-range "this_week"

# Optional flags:
#   --meta-ads          Enable Meta ads collection
#   --inactive          Create as paused (not active)
#   --exclude "spam,ads" Keywords to exclude from results
```

### List all configs
```bash
./virlo.sh list
./virlo.sh list --all    # Include inactive configs
```

### Get videos for a config
```bash
./virlo.sh videos <comet-id>
./virlo.sh videos <comet-id> --limit 20 --min-views 5000 --platform tiktok
./virlo.sh videos <comet-id> --order-by views --sort desc
```

### Get creator outliers
```bash
./virlo.sh outliers <comet-id>
./virlo.sh outliers <comet-id> --limit 20 --order-by outlier_ratio
./virlo.sh outliers <comet-id> --platform tiktok
```

### Get Meta ads (requires meta_ads_enabled on config)
```bash
./virlo.sh ads <comet-id>
./virlo.sh ads <comet-id> --limit 20
```

### Get a single config's details
```bash
./virlo.sh get <comet-id>
```

### Delete a config
```bash
./virlo.sh delete <comet-id>
```

---

## API Endpoints (Reference)

| Endpoint | What It Does |
|----------|-------------|
| `POST /v1/comet` | Create a new niche config |
| `GET /v1/comet` | List all your configs |
| `GET /v1/comet/:id` | Get one config's details |
| `DELETE /v1/comet/:id` | Remove a config |
| `GET /v1/comet/:id/videos` | Get collected videos |
| `GET /v1/comet/:id/creators/outliers` | Get breakout creators |
| `GET /v1/comet/:id/ads` | Get Meta ads |

All endpoints use Bearer auth: `Authorization: Bearer $VIRLO_API_KEY`

---

## Notes

- `virlo.sh setup` now saves `VIRLO_API_KEY` to the detected shell profile on macOS/Linux.
- On Windows, `virlo.sh setup` prints the PowerShell and Command Prompt commands to persist the key.
- Run the local shell scripts from Git Bash or WSL on Windows.
- **Cadence options:** `daily`, `weekly`, `monthly`, or any cron expression (max once/day frequency)
- **Time range options:** `today`, `this_week`, `this_month`, `this_year`
- **Platform options:** `tiktok`, `instagram`, `youtube`
- **Videos are collected after the first scheduled run** — new configs won't have data immediately
- **Outlier ratio** = viral video views ÷ creator's avg views (higher = bigger breakout)
- **Meta ads** only appear if `meta_ads_enabled: true` on the config

---

## Saved Configs

| Name | ID | Created |
|------|----|---------|
| *(run `./virlo.sh list` to populate)* | | |

Store your comet IDs in `~/clawd/skills/virlo/comets.json` after creating them.