virlo

name

virlo

description

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.

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

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

---

Commands

Create a niche config

./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

./virlo.sh list
./virlo.sh list --all    # Include inactive configs

Get videos for a config

./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

./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)

./virlo.sh ads <comet-id>
./virlo.sh ads <comet-id> --limit 20

Get a single config's details

./virlo.sh get <comet-id>

Delete a config

./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.